@fxri/toolkit 1.11.7 → 1.12.0

package/skills/fxri-plan-to-task/references/conventions-spec.md

@@ -1,215 +1,379 @@
-# 规范载体规范（conventions）
-
-> 面向多人 + AI 协作，任何语言项目可直接使用，仅依赖文件读写能力。本文件为 SKILL.md 的配套规范，定义 `.tasks/conventions/` 的目录结构、归属分类、读写判定、内容修订与存量迁移；任务文件本身的规范见 `task-spec.md`。
-
-## 1. 载体结构
-
-```
-.tasks/
-├── active/                    # 进行中的任务
-├── archive/                   # 已终结任务归档
-└── conventions/               # 项目协作规范载体
-    ├── index.md               # 唯一入口与唯一权威（常驻读）；首行为形态标记
-    ├── history.md             # 规范演进记录（只追加；写入与读取频次低，按需读）
-    ├── common.md              # 全端通用条文（按需创建）
-    └── <端名>.md              # 各端专有条文（按需创建）
-```
-
-- `index.md` 是唯一入口：端清单在此声明、每条规范在此留一行指针（首列为稳定 ID），读取时只读它即可掌握规范全貌
-- `history.md` 是修订留痕：规则语义变更在此追加；与 `index.md` 分离，避免「每次语义变更追加」的写与「每次建档常驻读」的读两类频次互相陪绑
-- 分册**按需创建**，判据是「该归属下有无需独立承载的条文」，不设条数阈值——溯源索引式项目可能始终只有 `index.md`
-- 目录与任务目录同在 `.tasks/` 根层，纯 Markdown 随 git 走；默认 `.tasks` 目录名可随任务区自定而变，内部结构不变
-- 非任务文件：`toolkit tasks` 各子命令不读其内容，`check` 不因内容告警；仅在**载体形态异常**时给软告警（旧单文件残留、缺 `index.md`、标记与结构不一致）；**入口层现场异常**（壳标记与当前 toolkit 不一致、壳被 gitignore 覆盖）另见下段入口壳
-
-载体可另配套**入口壳（一阶触发面）**：在**已存在的**项目级技能目录（`.agents/skills/`、`.trae/skills/`、`.trae-cn/skills/`、`.cursor/skills/`、`.claude/skills/`；多 agent 混用团队多个并存时**每处各写一份**、互不覆盖，一个都不存在时回落 `.agents/skills/`）下生成 `toolkit-conventions/SKILL.md`，目录名与 frontmatter `name` 同名（Agent Skills 标准要求）。壳只作入口、不承载条文，正文指回任务区 `conventions/index.md`；由 `toolkit init` 幂等生成（可安全删除，重跑补回；已存在壳按标记版本分流——标记不旧于当前版本保持不变，落后或无标记就地更新为当前版本），只在已有目录内落盘、不为使用者未安装的 agent 凭空建目录，本包源仓库自身不生成。壳首部为 frontmatter，故其形态标记 `<!-- toolkit-conventions-entry: v2 -->` 退居其后、须全文件扫描（区别于载体标记只看首行）；壳标记与当前 toolkit 不一致、或被 `.gitignore` 覆盖时，`toolkit conventions status` 与 `toolkit tasks check` 软告警——标记不一致可重跑 `toolkit init` 就地更新为当前版本；同类告警在多落点并存时**合并为一条**并内联全部落点路径（仓库根相对路径），不按壳逐条重复。体检只扫上述 5 个内置候选目录（`findEntryShells`）：用户手工把壳拷到未收录目录（如 `.windsurf/skills`）不参与体检。⚠️ 同一批候选目录还承载**项目面技能薄壳**（`toolkit skills install --scope project` 在真源 `<仓库根>/.agents/skills/` 之外的其他已存在候选目录生成 `fxri-*` 薄壳），与 `toolkit-conventions/` 入口壳**不同名并存、互不覆盖**；两者机制独立——入口壳由 `toolkit init` 生成、技能薄壳由技能分发生成。
-
-规范触发面共三层，**任一层可用即可触达**：① 全局技能 `fxri-plan-to-task`（随包分发到各 agent 全局技能目录，其工作流第 1 步即要求读 `conventions/index.md`）——**不依赖项目内任何文件、恒在兜底**；② 上述项目级入口壳（用户不主动发问也能被 agent 读到）；③ `AGENTS.md` 指针块（仅在文件已存在时幂等追加，不存在不新建，跳过时提示仍有第 1 层可触达）。三层同时缺席的唯一情形：装包后未跑 `toolkit skills install`（或 agent 不加载全局技能），且项目既无 `AGENTS.md` 又未跑 `toolkit init`——`init` 检测到尚未安装全局技能时会在「下一步」中补一行 `toolkit skills install` 指引（已安装则不重复提示），把这一情形收敛为「用户忽略了 `init` 的提示」。
-
-## 2. index.md 结构
-
-首行为形态标记，其后三节固定顺序：端清单 → 索引 → 用法说明（演进记录已移出，见 §3.2）。
-
-### 2.0 首行标记
-
-```markdown
-<!-- toolkit-conventions: v2 -->
-# 项目协作规范索引
-```
-
-- 标记置 `index.md` **首行**；仅**破坏性结构变更**递增 `v<n>`，措辞修正不递增；无标记即「引入机制前的形态」（v1）
-- 标记不写包版本号——写包版本会让「发版即全员过时」
-- 载体标记只看首行，正文示例里的同形注释不参与判定
-
-### 2.1 端清单（唯一权威）
-
-```markdown
-## 一、端清单
-
-> 端名与任务 frontmatter 的 `scope` 取值共用同一套词表；保留字 `index` / `common` 不得作端名。
-
-| 端名 | 说明 |
-| --- | --- |
-| web | 前端主站 |
-| server | 后端服务 |
-```
-
-单端项目写一行或留空表并注明「本项目单端，规范全归 common」。
-
-### 2.2 索引（首列稳定 ID）
-
-```markdown
-| ID | 规则 | 当前语义 | 归属 | 状态 | 确立来源任务 | 单一事实源 |
-| --- | --- | --- | --- | --- | --- | --- |
-| C-1 | 四级时间源 | 时间取证优先级：当场打点 > 聊天记录时间戳 > git 提交时间 > 系统时间兜底 | common | 生效 | 20260906-会话收尾沉淀能力升级 | task-spec.md（口径随版本走） |
-```
-
-- **ID**：`C-<n>`（`C` 表 conventions），**去补零、不带端前缀、只追加不重排不回收**；插入或重排不漂移，废弃条目不回收其 ID（容量不是问题，去补零取的是可读性）
-- **引用**：载体内部引用一律行内代码包裹（如 `` `C-17` ``），便于机械匹配；v1 遗留的裸「第 N 条」在升级时改写（见 §10.2）
-- **归属**：取值必须 ∈ {`common`} ∪ 端清单，否则为悬空指针（需修正）
-- **状态**：`生效` / `已废弃`；废弃不删行，改状态即可（与「归档任务不可变」同哲学：留痕优于抹除）
-- **单一事实源**：条文正文去哪看。已指向项目现有规则层（AGENTS / 全局规则 / skills）时填指向；条文就在本载体分册内时填分册名（如 `common.md`）
-
-### 2.3 用法说明
-
-写明本项目采用哪种形态、读写判定要点、以及规则层源头变更时的同步纪律。
-
-## 3. 分册与演进记录
-
-### 3.1 分册结构
-
-```markdown
-# 全端通用规范（common）
-
-> 归属：common（所有端适用）。条文全文见本节，索引见 index.md。
-
-## C-1. 四级时间源
-
-（条文全文）
-```
-
-端分册同构，首部 `# {端名} 规范`、`> 归属：{端名}`。小节标题用稳定 ID（`## C-<n>. {规则名}`），与 `index.md` 索引一致，便于互引。
-
-### 3.2 history.md 结构
-
-演进记录独立成文件，**仅追加、不改旧行**：
-
-```markdown
-# 规范演进记录
-
-> 元规则：规则语义变更时不得覆盖旧语义直接丢史——在「演进记录」追加一条（规则 → 旧语义 → 变更为 → 修订来源任务），`index.md` 索引表只保留当前语义；规则层源头变更（`AGENTS.md` / `docs/ai-rules.md` / skills 条文）随该变更同批落盘。
-> 表语义边界：本表只记**规范语义变更**；载体结构升级、入口壳生成 / 删除均不入表。
-
-| 规则 ID / 名称 | 修订内容 | 修订来源任务 |
-| --- | --- | --- |
-```
-
-- 首列记 `C-<n>` 或规则名，二者兼可（历史行可能早于 ID 引入）
-- **表语义边界写死**：载体结构升级（如 v1 → v2）、入口壳生成 / 删除都不入表——表只记**规范语义**变更
-
-## 4. 端名规则
-
-- **与任务 frontmatter `scope` 取值逐字一致**：两者共用同一套词表，读取时才能机械匹配（任务写 `scope: web+server` → 加载 `web.md` + `server.md`）
-- **形态约束**：非空、不含空格、不含路径分隔符（`/ \ : * ? " < > |`）
-- **保留字**：`index`、`common` 不得作端名
-- **风格**：随项目 `scope` 既有写法（`web` / `server` / `admin` / `前端` 均成立），无全局词表——工具无法预知项目端构成，故不硬编码取值
-- **跨仓归属**：跨仓库改造时任务 `scope` 只标本仓内的端 / 面，不写另一仓的端名——任务档是仓库自述（见 `SPEC.md` §0）
-
-## 5. 读取判定（分层）
-
-1. **常驻**：只读 `index.md`（端清单 + 索引），成本与规范条数成线性、不随分册增大；`history.md` 按需读、不常驻
-2. **按需**：取当前任务 `scope` 的每个值 → 命中端清单的加载对应分册，再叠加 `common.md`
-3. **非端值**：`scope` 中不在端清单的值视为分类标签，静默跳过，不报错
-4. **空 scope**：只加载 `common.md`（保守，不臆测端归属）
-
-## 6. 写入判定（沉淀归属）
-
-1. 先问「这条是否**所有端都适用**」→ 是则归 `common`
-2. 否则逐端确认「适用于哪些端」→ 写入命中的端分册
-3. **禁止跨端合并归属**：不得出现「web+server 共识」这类跨端条目——真全端升 `common`，只适用几端则各端各记一条
-4. `common` 语义锁死为「所有端都适用」，**不得用作「不确定归哪端」的暂存区**，否则会退化为垃圾桶
-5. 写入前须经用户确认；一次性决策不升格为规范，留在任务正文
-
-## 7. 两种形态
-
-形态差异体现在分册是否存在与「单一事实源」列取值，**不是结构二选一**：
-
-| 形态 | 适用 | 表现 |
-| --- | --- | --- |
-| 溯源索引式 | 项目已有规则层（AGENTS / 全局规则 / skills） | 不复制条文，索引行「当前语义」写简版语义、「单一事实源」写指向；可能只有 `index.md` |
-| 条文式 | 无其他规则文件的项目 | 条文全文写入对应归属分册，本载体即项目唯一规范载体 |
-
-同一项目内可混用：部分规则指向外部规则层、部分条文落在本载体。
-
-## 8. 内容修订
-
-- 语义变更：先在 `history.md` 追加一行（规则 ID / 名称 → 旧语义 → 变更为 → 修订来源任务），再更新 `index.md` 索引行「当前语义」；条文在分册内的同步改分册
-- 规则作废：索引行状态改 `已废弃`，不删行、不删分册条目、不回收 `C-<n>`
-- 规则层源头变更（AGENTS / 全局规则 / skills 条文改了）：同步检查索引对应行当前语义是否需更新，随该变更同批落盘
-- **内部引用一律写 ID**：载体内部互引（用法说明、分册配套说明等）写 `` `C-<n>` ``，不写「第 N 条」——序号随插入重排漂移，ID 不会
-
-## 9. 表格形态（紧凑为规范形态）
-
-载体内所有表格（`index.md` 端清单与索引表、`history.md` 演进记录、各分册与任务文件表格）一律采用**紧凑形态**：单元格之间只留一个空格（`| 值 | 值 |`），不做列对齐填充。理由：填充出的空白层在渲染预览时不显示，却在纯文本阅读时把表格撑成难读的宽行——紧凑形态在渲染与源码两侧都最易读。
-
-- **填充态来源**：宿主仓库若对任务区跑 prettier，GFM 表格会被**列对齐填充**（按列内最宽单元格补空格）——格式化器的刻意行为，非本工具写入
-- **判据**：任一行去缩进后若 `行 !== "| " + 各单元格以 " | " 相连 + " |"` 即为填充态；同一判据既用于归一写入、也用于体检检出（`src/conventions/compact.ts`）
-- **写入纪律**：手工建档、沉淀、归档时写表一律用紧凑形态，**不为对齐空格手工补齐**；工具自身写入的表格（`init` 骨架、`upgrade` 改写、`archive` 归档块）本就紧凑
-- **豁免托管**：`toolkit init` 检测到宿主疑似用 prettier 时幂等托管 `.prettierignore`、把任务区**整目录**排除，从源头不再被填充（本包源仓库自身、任务区在仓库外或即仓库根、无 prettier 迹象三种情形跳过；末者报告提示「项目启用 prettier 后重跑 `toolkit init` 会自动补上」）
-- **存量归一**：`toolkit conventions format` 把已存在的填充收敛回紧凑形态——只动单元格间距与列对齐填充、**不改语义**，跳过 fenced code block（代码块内原样保留），保留对齐标记（`:---` / `---:`）与行尾符，**幂等**（已紧凑时原样返回并报 `already-compact`），`--dry-run` 只预览行号不写盘；范围为任务区全部 md（载体三件 + `active/` + `archive/`）。**归一不入 `history.md`**——属形态变更、非规范语义变更
-- **检出告警**：`toolkit conventions status` 与 `toolkit tasks check` 对填充态软告警（前者聚合为一条、后者逐文件一条），指向上述两种处置；只报形态、不阻断（`status` 退出码恒 0、`check` 计 warn）
-
-## 10. 存量迁移
-
-### 10.1 旧单文件 → 目录形态（v0 → v1）
-
-触发：`toolkit tasks check` 报旧 `conventions.md` 存在；或用户直接要求迁移。
-
-**三段式**（可中断，中途停下不丢内容）：
-
-1. **机器搬骨架**：建 `conventions/`，旧文件**整体**搬为 `index.md`（原文一字不丢），删除旧文件——此刻 `index.md` 是原文快照，功能上与旧文件等价
-2. **AI 提归属建议**：读原有条目，逐条给出「`common` / 某端」建议与理由（旧文件无端信息，语义分流无法机械完成），形成待确认清单
-3. **用户逐条确认**：确认后写索引行 + 把条文全文拆入对应分册；**未确认的条目保持原样留在 `index.md`**，不强推
-
-补充要求：
-
-- 迁移与内容重排分开做：先完成形态迁移（结构到位），再谈条目归属调整，避免一次变更混合两种风险
-- 端清单在迁移时同步建立：从项目已有 `scope` 取值与实际子项目构成归纳，经用户确认写入端清单节
-- 旧文件已不存在时不重复迁移
-
-### 10.2 v1 → v2 结构升级
-
-触发：`toolkit conventions status` 报「需升级」；`toolkit tasks check` 报形态告警（标为 v2 缺 `history.md` 或索引表首列非 `ID`；有 `history.md` 但首列仍是 `#`）；或用户直接要求升级。
-
-优先用 `toolkit conventions upgrade`（纯机械，可 `--dry-run` 预演），动作序：
-
-1. **发 ID**：按现有条序 `1..n` 发 `C-1..C-n`，索引表首列由 `#` 改 `ID`
-2. **切 `history.md`**：原 `index.md`「演进记录」节整表平移为独立 `history.md`（列结构不变），`index.md` 撤该节；标题归一 `# 项目协作规范索引`，首行补标记
-3. **改内部引用**：裸「第 N 条」（仅 N ≤ 索引表最大序号者）改写为 `` `C-<n>` ``；带外部文档限定词前缀的引用（如 `AGENTS.md` 质量门第 5 条、`SPEC.md` 协作模型第 3 条、`task-spec.md` 第 6 节）一律不动；改写清单进报告
-4. **分册小节归一**：分册小节标题改 `## C-<n>. {规则名}`
-
-补充要求：
-
-- **ID 映射不落盘**：映射由 `upgrade` 输出（实跑与 `--dry-run` 均打印）；真值可由 git 历史复现（迁移提交的父提交即 v1 原件），故不落盘代价近零
-- **先判后写**：遇形态异常（标记与结构不一致）拒绝执行并给非 0 退出码，**不写任何文件**，提示人工确认
-- `upgrade` 幂等：已是 v2 时原样返回，不做二次改写
-- 手动迁移时按同一动作序执行
-
-## 11. 兼容读（迁移期）
-
-读取时先找 `conventions/index.md`；不存在再看旧单文件 `conventions.md`，存在则按旧单文件内容读取并**在对话中提示可迁移**。两者并存时以目录形态为准，并提示旧文件待清理。v1 与 v2 都按目录形态正常读取，形态差异见 §10.2 的判据（`index.md` + `history.md` + 首列 `ID` 为 v2，否则 v1）。
-
-## 12. 自查清单
-
-- [ ] `index.md` 首行为形态标记（v2 为 `<!-- toolkit-conventions: v2 -->`）
-- [ ] `conventions/` 存在时必有 `index.md`（缺则为形态异常）
-- [ ] 索引表首列为 `ID`，取值为 `C-<n>`：去补零、无重复、废弃条目不复用其 ID
-- [ ] v2 形态必有 `history.md`，表头为 `规则 ID / 名称 | 修订内容 | 修订来源任务`，且不改旧行
-- [ ] 载体内部引用均为 `` `C-<n>` ``，无残留裸「第 N 条」
-- [ ] 端清单非空且不含保留字 `index` / `common`
-- [ ] 索引表「归属」列取值 ∈ {`common`} ∪ 端清单（无悬空指针）
-- [ ] 「状态」列取值为 `生效` / `已废弃`
-- [ ] 分册文件与端清单 + `common` 对应，无孤立文件
-- [ ] 旧单文件 `conventions.md` 已迁移（不存在，或已提示待清理）
-- [ ] 有入口壳时其标记与当前 toolkit 一致（落后或无标记可重跑 `toolkit init` 就地更新）、且未被 `.gitignore` 覆盖（否则 `check` / `conventions status` 告警）
-- [ ] 载体与任务区表格为紧凑形态（无列对齐填充；`toolkit conventions format` 可归一，`check` / `conventions status` 会检出）
-- [ ] 规范写入均经用户确认，且带「确立来源任务」
+# 规范载体规范（conventions）
+
+> 面向多人 + AI 协作，任何语言项目可直接使用，仅依赖文件读写能力。本文件为 SKILL.md 的配套规范，定义 `.tasks/conventions/` 的目录结构、归属分类、读写判定、内容修订与存量迁移；任务文件本身的规范见 `task-spec.md`。
+
+## 1. 载体结构
+
+```
+.tasks/
+├── active/                    # 进行中的任务
+├── archive/                   # 已终结任务归档
+└── conventions/               # 项目协作规范载体
+    ├── index.md               # Z1 常驻：唯一入口与唯一权威；首行为形态标记
+    ├── history.md             # Z3 归档：规范演进记录（只追加；写入与读取频次低）
+    ├── retired.md             # Z3 归档：已退休条目（按需创建）
+    ├── common.md              # Z2 按需：全端通用条文（按需创建）
+    ├── <端名>.md              # Z2 按需：各端专有条文（按需创建）
+    └── <分类标签>.md          # Z2 按需：按主题下沉的条文（按需创建）
+```
+
+- `index.md` 是唯一入口：端清单在此声明、每条活跃规范在此留一行指针（首列为稳定 ID），任务开始时只读它即可掌握规范全貌
+- `history.md` 是修订留痕：规则语义变更在此追加；与 `index.md` 分离，避免「每次语义变更追加」的写与「每次建档常驻读」的读两类频次互相陪绑
+- `retired.md` 是退休台账：条目作废即从索引迁出至此并冻结语义；与 `index.md` 分离，使废弃正文不再落入任何常规读面
+- 分册**按需创建**，判据是「该归属下有无需独立承载的条文」，不设条数阈值——溯源索引式项目可能始终只有 `index.md`
+- 目录与任务目录同在 `.tasks/` 根层，纯 Markdown 随 git 走；默认 `.tasks` 目录名可随任务区自定而变，内部结构不变
+- 非任务文件：`toolkit tasks` 各子命令不读其内容，`check` 不因内容告警；仅在**载体形态异常**时给软告警（旧单文件残留、缺 `index.md`、标记与结构不一致）；**入口层现场异常**（壳标记与当前 toolkit 不一致、壳被 gitignore 覆盖）另见下段入口壳
+
+### 1.1 三分区与不变量
+
+载体按**读面**分三区，这是全规范的中心约束——凡变更须先问「这条进不进常驻读面」：
+
+| 分区 | 文件 | 读面 | 承载 |
+| --- | --- | --- | --- |
+| Z1 常驻 | `index.md` | 每个任务开始时必读 | 端清单 + 活跃条目的索引行 |
+| Z2 按需 | `common.md` / `<端名>.md` / `<分类标签>.md` | 命中任务 `scope` 时读 | 活跃条文的正文 |
+| Z3 归档 | `history.md` / `retired.md` | 仅审计 / 恢复时读 | 语义演进留痕、已退休条目 |
+
+不变量（写入、修订与迁移时须恒真）：
+
+- **I1 分区唯一**：同一条目不得同时出现在 Z1/Z2 与 Z3。
+- **I2 常驻只含活跃**：Z1 索引不含任何已退休条目。
+- **I3 分册只含活跃条文**：Z2 分册不含已退休条文的正文。
+- **I4 条文只存一处**：同一条文正文只承载于一处（Z2 分册 或 外部单一事实源，二者其一）。
+- **I5 ID 永不回收**：`C-<n>` 只追加、不重排、不复用；退休后其 ID 仍在 `retired.md` 占位。
+- **I6 语义活性**：Z1「当前语义」是活的（随修订更新），Z3「退休时语义」是冻结的（退休后不再改）。
+- **I7 读面无废文**：凡会被常规读取的位置（Z1 + Z2）不得含废弃正文。
+
+> **元原则**：载体新增的任何字段、文件、表格，须能证明它**不进常驻读面**，方允许引入——常驻面每多一列、每多一行，都由全体任务平摊成本，而归档面只在小概率的审计 / 恢复场景被读到。
+
+载体可另配套**入口壳（一阶触发面）**：在**已存在的**项目级技能目录（`.agents/skills/`、`.trae/skills/`、`.trae-cn/skills/`、`.cursor/skills/`、`.claude/skills/`；多 agent 混用团队多个并存时**每处各写一份**、互不覆盖，一个都不存在时回落 `.agents/skills/`）下生成 `toolkit-conventions/SKILL.md`，目录名与 frontmatter `name` 同名（Agent Skills 标准要求）。壳只作入口、不承载条文，正文指回任务区 `conventions/index.md`；由 `toolkit init` 幂等生成（可安全删除，重跑补回；已存在壳按标记版本分流——标记不旧于当前版本保持不变，落后或无标记就地更新为当前版本），只在已有目录内落盘、不为使用者未安装的 agent 凭空建目录，本包源仓库自身不生成。壳标记版本**独立于载体版本**演进——当前为 `v2`，机制引入时即从 `v2` 起，从未有过 `v1` 壳（区别于载体「无标记即 v1」）。壳首部为 frontmatter，故其形态标记 `<!-- toolkit-conventions-entry: v2 -->` 退居其后、须全文件扫描（区别于载体标记只看首行）；壳标记与当前 toolkit 不一致、或被 `.gitignore` 覆盖时，`toolkit conventions status` 与 `toolkit tasks check` 软告警——标记不一致可重跑 `toolkit init` 就地更新为当前版本；同类告警在多落点并存时**合并为一条**并内联全部落点路径（仓库根相对路径），不按壳逐条重复。体检只扫上述 5 个内置候选目录（`findEntryShells`）：用户手工把壳拷到未收录目录（如 `.windsurf/skills`）不参与体检。⚠️ 同一批候选目录还承载**项目面技能薄壳**（`toolkit skills install --scope project` 在真源 `<仓库根>/.agents/skills/` 之外的其他已存在候选目录生成 `fxri-*` 薄壳），与 `toolkit-conventions/` 入口壳**不同名并存、互不覆盖**；两者机制独立——入口壳由 `toolkit init` 生成、技能薄壳由技能分发生成。
+
+规范触发面共三层，**任一层可用即可触达**：① 全局技能 `fxri-plan-to-task`（随包分发到各 agent 全局技能目录，其工作流第 1 步即要求读 `conventions/index.md`）——**不依赖项目内任何文件、恒在兜底**；② 上述项目级入口壳（用户不主动发问也能被 agent 读到）；③ `AGENTS.md` 指针块（仅在文件已存在时幂等追加，不存在不新建，跳过时提示仍有第 1 层可触达）。三层同时缺席的唯一情形：装包后未跑 `toolkit skills install`（或 agent 不加载全局技能），且项目既无 `AGENTS.md` 又未跑 `toolkit init`——`init` 检测到尚未安装全局技能时会在「下一步」中补一行 `toolkit skills install` 指引（已安装则不重复提示），把这一情形收敛为「用户忽略了 `init` 的提示」。
+
+## 2. index.md 结构
+
+首行为形态标记，其后三节固定顺序：端清单 → 索引 → 用法说明（演进记录已移出，见 §3.2）。
+
+### 2.0 首行标记
+
+```markdown
+<!-- toolkit-conventions: v3 -->
+# 项目协作规范索引
+```
+
+- 标记置 `index.md` **首行**；仅**破坏性结构变更**递增 `v<n>`，措辞修正不递增；无标记即「引入机制前的形态」（v1）
+- 标记不写包版本号——写包版本会让「发版即全员过时」
+- 载体标记只看首行，正文示例里的同形注释不参与判定
+- **不得显式书写 `v1` 标记**：v1 的定义即「无标记」，若把首行写成版本段为 `v1` 的形态标记会被判为未知版本（形态异常）；需要停用时用现行标记（`v2` / `v3`）表达，不写 `v1`
+
+### 2.1 端清单（唯一权威）
+
+```markdown
+## 一、端清单
+
+> 端名与任务 frontmatter 的 `scope` 取值共用同一套词表；保留字 `index` / `common` 不得作端名。
+
+| 端名 | 说明 |
+| --- | --- |
+| web | 前端主站 |
+| server | 后端服务 |
+```
+
+单端项目写一行或留空表并注明「本项目单端，规范全归 common」。
+
+### 2.2 索引（首列稳定 ID）
+
+```markdown
+| ID | 规则 | 当前语义 | 归属 | 单一事实源 |
+| --- | --- | --- | --- | --- |
+| C-1 | 四级时间源 | 时间取证优先级：当场打点 > 聊天记录时间戳 > git 提交时间 > 系统时间兜底 | common | skills/<技能名>/references/task-spec.md（口径随版本走） |
+```
+
+- **列集合固定为五列**：`ID | 规则 | 当前语义 | 归属 | 单一事实源`，列名与次序均不得增减或调换——列集合即读接口，漂移会破坏机械读写；`toolkit tasks check` / `toolkit conventions status` 检出列集合偏离（列名 / 次序 / 列数不符）并软告警（只报不改，须人工确认后按本规范归一）
+- **ID**：`C-<n>`（`C` 表 conventions），**去补零、不带端前缀、只追加不重排不回收**；插入或重排不漂移，废弃条目不回收其 ID（容量不是问题，去补零取的是可读性）
+- **引用**：载体内部引用一律行内代码包裹（如 `` `C-17` ``），便于机械匹配；v1 遗留的裸「第 N 条」在升级时改写（见 §10.2）
+- **归属**：取值必须对应一个实际承接处——`common`、端清单中的端名、或载体目录下存在的分类标签分册名，否则为悬空指针（需修正）
+- **单一事实源**：条文正文去哪看。已指向项目现有规则层（AGENTS / 全局规则 / skills）时填指向；条文就在本载体分册内时填分册名（如 `common.md`）
+- **不含「状态」「确立来源任务」两列**（区别于 v2）：Z1 只收录活跃条目，故「状态」恒为活跃、不必占列；「确立来源任务」属留痕信息、交 git 历史承载，退休条目则记于 `retired.md`
+
+### 2.3 用法说明
+
+写明本项目采用哪种形态、读写判定要点、以及规则层源头变更时的同步纪律。骨架与写法见 §13（T2）；通用部分收敛为一句并指向本规范，不逐条复述规则正文。
+
+## 3. 分册与留痕文件
+
+### 3.1 分册结构
+
+```markdown
+# 全端通用规范（common）
+
+> 归属：common（所有端适用）。条文全文见本节，索引见 index.md。
+
+## C-1. 四级时间源
+
+（条文全文）
+```
+
+端分册同构，首部 `# {端名} 规范`、`> 归属：{端名}`；分类标签分册同构，首部 `# {标签} 规范`。小节标题用稳定 ID（`## C-<n>. {规则名}`），与 `index.md` 索引一致，便于互引。条文正文的子项与次序见 §13（T4）；分册内不写「确立来源」行——来源已由 `index.md` 索引列与 `history.md` 承载（见 §13）。
+
+### 3.2 history.md 结构
+
+演进记录独立成文件，**仅追加、不改旧行**：
+
+```markdown
+# 规范演进记录
+
+> 元规则：规则语义变更时不得覆盖旧语义直接丢史——在「演进记录」追加一条（规则 ID → 修订内容 → 修订来源任务；修订内容新立条目直接写其语义、语义变更写「旧语义」→「新语义」），`index.md` 索引表只保留当前语义；规则层源头变更（`AGENTS.md` / `docs/ai-rules.md` / skills 条文）随该变更同批落盘。
+> 表语义边界：本表只记**规范语义变更**；载体结构升级、入口壳生成 / 删除、条目退休均不入表（退休见 `retired.md`）。
+
+| ID | 修订内容 | 修订来源任务 |
+| --- | --- | --- |
+```
+
+- **首列记为行内代码包裹的裸 ID `C-<n>`，不写规则名**（规范名以 `index.md` 索引表为准；规则改名等沿革信息作前置括注记入「修订内容」列，如「（原名「X」）」）。此为硬性要求：`toolkit tasks check` 与 `toolkit conventions status` 检出非 ID 首列并软告警（只报不改——历史行只追加不改旧行的元规则下，补齐须人工确认）
+- **「修订内容」列只记该条自身语义**：新立条目直接写其语义；语义变更写「旧语义」→「新语义」（箭头两侧文本加全角引号）。两条禁令——不得写自指套话（如「（本次起入表）」「新立条目：」，表内每行本就是入表记录、自指零信息量）；不得复述 `index.md` 索引列信息（如「；条文全文落 `common.md`」与索引「单一事实源」列重复，违反 §1.1 不变量 I4）。规范名沿革作前置括注（如「（原名「增量判别」）」）。**措辞归一例外**：属 §9 同类的措辞层归一、非语义变更，可原地改写旧行、不入 `history.md` 留痕行。`toolkit tasks check` / `toolkit conventions status` 检出禁用语料并软告警（只报不改，改写须人工确认）
+- **表头固定**：须恰为 `ID | 修订内容 | 修订来源任务` 三列，逐格一致（含列名与次序）；`toolkit tasks check` / `toolkit conventions status` 检出表头偏离并软告警
+- **表语义边界写死**：载体结构升级（如 v1 / v2 → v3）、入口壳生成 / 删除、条目退休都不入表——表只记**规范语义**变更
+
+### 3.3 retired.md 结构
+
+退休台账独立成文件，**只增不改**（退休时语义一经冻结不再改动）：
+
+```markdown
+# 规范退休记录
+
+> 元规则：条目作废即从 `index.md` 迁出至本表并冻结退休时语义；编号不回收（见 §8）。本表属 Z3 归档、不进常规读面。
+
+| ID | 规则 | 退休时语义（冻结） | 归属 | 后继 | 退休来源任务 | 条文去向 |
+| --- | --- | --- | --- | --- | --- | --- |
+| C-7 | 旧示例规则 | （退休当时的语义原文） | web | `C-41` | 20261016-某任务 | 已删分册小节 `web.md` |
+```
+
+- **表头固定**：须恰为 `ID | 规则 | 退休时语义（冻结） | 归属 | 后继 | 退休来源任务 | 条文去向` 七列，逐格一致（含列名与次序）；`toolkit tasks check` / `toolkit conventions status` 检出表头偏离并软告警
+- **退休时语义（冻结）**：退休当时的语义原文，不再随修订变动（区别于 Z1 的活语义）
+- **后继**：替代它的新条目 ID；无则填 `—`
+- **退休来源任务**：执行这次退休的任务
+- **条文去向**：三层清理的落点记录（删除了哪处分册小节、外部单一事实源如何处理）
+
+## 4. 端名规则
+
+- **与任务 frontmatter `scope` 取值逐字一致**：两者共用同一套词表，读取时才能机械匹配（任务写 `scope: web+server` → 加载 `web.md` + `server.md`）
+- **形态约束**：非空、不含空格、不含路径分隔符（`/ \ : * ? " < > |`）
+- **保留字**：`index`、`common` 不得作端名
+- **分类标签**：`scope` 中既不在端清单、又非保留字的值视为分类标签；若载体目录下存在同名分册（如 `ui还原.md`）则按需加载，否则静默跳过（见 §5）。用途是把巨型 `common.md` 中按主题聚拢的条文下沉为平铺分册，使任务只加载相关主题——端清单不含分类标签，故不影响端归属判定
+- **风格**：随项目 `scope` 既有写法（`web` / `server` / `admin` / `前端` 均成立），无全局词表——工具无法预知项目端构成，故不硬编码取值
+- **跨仓归属**：跨仓库改造时任务 `scope` 只标本仓内的端 / 面，不写另一仓的端名——任务档是仓库自述（见 `SPEC.md` §0）
+
+## 5. 读取判定（分层）
+
+1. **常驻**：只读 `index.md`（端清单 + 活跃索引），成本与规范条数成线性、不随分册增大。`history.md` / `retired.md` 属 Z3 归档，**不进常驻读面**，仅审计 / 恢复时按需查阅
+2. **按需（叠加）**：取当前任务 `scope` 的每个值——命中端清单者加载对应端分册；未命中但载体目录下存在同名分册（分类标签分册，如 `ui还原.md`）者加载之；两者皆非则静默跳过、不报错。无论命中与否，**恒叠加 `common.md`**
+3. **空 scope**：只加载 `common.md`（保守，不臆测端归属）
+
+## 6. 写入判定（沉淀归属）
+
+1. 先问「这条是否**所有端都适用**」→ 是则归 `common`
+2. 否则逐端确认「适用于哪些端」→ 写入命中的端分册
+3. **禁止跨端合并归属**：不得出现「web+server 共识」这类跨端条目——真全端升 `common`，只适用几端则各端各记一条
+4. `common` 语义锁死为「所有端都适用」，**不得用作「不确定归哪端」的暂存区**，否则会退化为垃圾桶
+5. `common.md` 过大时（如恒叠加面已拖累每个任务的读面），可把其中**按主题自成一类**的条目下沉为分类标签分册（如 `ui还原.md`），并在用法说明与任务 `scope` 中约定标签；此为按需裁剪手段，不改变条目的端归属
+6. 写入前须经用户确认；一次性决策不升格为规范，留在任务正文
+
+## 7. 两种形态
+
+形态差异体现在分册是否存在与「单一事实源」列取值，**不是结构二选一**：
+
+| 形态 | 适用 | 表现 |
+| --- | --- | --- |
+| 溯源索引式 | 项目已有规则层（AGENTS / 全局规则 / skills） | 不复制条文，索引行「当前语义」写简版语义、「单一事实源」写指向；可能只有 `index.md` |
+| 条文式 | 无其他规则文件的项目 | 条文全文写入对应归属分册，本载体即项目唯一规范载体 |
+
+同一项目内可混用：部分规则指向外部规则层、部分条文落在本载体。
+
+## 8. 内容修订
+
+- 新立条目：在 `history.md` 追加一行（「修订内容」列直接写其语义），同时在 `index.md` 追加索引行、必要时在分册写入条文
+- 语义变更：先在 `history.md` 追加一行（规则 ID → 修订内容 → 修订来源任务；修订内容新立条目直接写其语义、语义变更写「旧语义」→「新语义」），再更新 `index.md` 索引行「当前语义」；条文在分册内的同步改分册
+- **规则作废（迁出 + 三层清理）**：一条规则不再成立时，**不是**把状态改个标记留在原位（那会让废弃正文继续留在读面），而是把它整条迁出常规读面：
+  1. **索引层**：从 `index.md` 索引表**删除**该行，改写入 `retired.md`（冻结退休时语义，记后继与条文去向）
+  2. **载体分册层**：物理删除 Z2 分册内该条的小节正文（不留占位、不留言「已废弃」）
+  3. **外部单一事实源层**：若「单一事实源」指向外部规则层，同步删除或修正该处条文
+  记录边界：退休留痕入 `retired.md`、**不入 `history.md`**（二者分工——history 记「语义怎么变的」，retired 记「哪条退休了、去哪了」）
+- 规则层源头变更（AGENTS / 全局规则 / skills 条文改了）：同步检查索引对应行当前语义是否需更新，随该变更同批落盘
+- **内部引用一律写 ID**：载体内部互引（用法说明、分册配套说明等）写 `` `C-<n>` ``，不写「第 N 条」——序号随插入重排漂移，ID 不会
+
+## 9. 表格形态（紧凑为规范形态）
+
+载体内所有表格（`index.md` 端清单与索引表、`history.md` 演进记录、`retired.md` 退休记录、各分册与任务文件表格）一律采用**紧凑形态**：单元格之间只留一个空格（`| 值 | 值 |`），不做列对齐填充。理由：填充出的空白层在渲染预览时不显示，却在纯文本阅读时把表格撑成难读的宽行——紧凑形态在渲染与源码两侧都最易读。
+
+- **填充态来源**：宿主仓库若对任务区跑 prettier，GFM 表格会被**列对齐填充**——按列内最宽单元格补空格，分隔行（`| --- |`）的横线也一并被补长到列宽——格式化器的刻意行为，非本工具写入
+- **判据**：内容行——任一行去缩进后若 `行 !== "| " + 各单元格以 " | " 相连 + " |"` 即为填充态；分隔行——横线被补长（超出规范形 `---`）亦属填充态，归一目标即 `---`（保留对齐标记 `:---` / `---:` / `:---:`）。同一判据既用于归一写入、也用于体检检出（`src/conventions/compact.ts`）
+- **列数自洽**：任一张表的表头行与紧随其后的分隔行列数须相等——列数脱节是表结构损坏（多列提示漏删分隔格、少列提示漏补），渲染与解析都会错位；`toolkit tasks check` / `toolkit conventions status` 对载体各文件（`index.md`、分册、`history.md`、`retired.md`）检出并软告警，跳过 fenced code block（块内表为示例、不参与检测）
+- **写入纪律**：手工建档、沉淀、归档时写表一律用紧凑形态，**不为对齐空格手工补齐**；工具自身写入的表格（`init` 骨架、`upgrade` 改写、`archive` 归档块）本就紧凑
+- **豁免托管**：`toolkit init` 检测到宿主疑似用 prettier 时幂等托管 `.prettierignore`、把任务区**整目录**排除，从源头不再被填充（本包源仓库自身、任务区在仓库外或即仓库根、无 prettier 迹象三种情形跳过；末者报告提示「项目启用 prettier 后重跑 `toolkit init` 会自动补上」）
+- **存量归一**：`toolkit conventions format` 把已存在的填充收敛回紧凑形态——只动单元格间距、分隔行横线长度与列对齐填充、**不改语义**，跳过 fenced code block（代码块内原样保留），保留对齐标记（`:---` / `---:`）与行尾符，**幂等**（已紧凑时原样返回并报 `already-compact`），`--dry-run` 只预览行号不写盘；范围为任务区全部 md（载体各文件 + `active/` + `archive/`）。**归一不入 `history.md`**——属形态变更、非规范语义变更
+- **检出告警**：`toolkit conventions status` 与 `toolkit tasks check` 对填充态软告警（前者聚合为一条、后者逐文件一条），指向上述两种处置；只报形态、不阻断（`status` 退出码恒 0、`check` 计 warn）
+
+## 10. 存量迁移
+
+### 10.1 旧单文件 → 目录形态（v0 → v1）
+
+触发：`toolkit tasks check` 报旧 `conventions.md` 存在；或用户直接要求迁移。
+
+**三段式**（可中断，中途停下不丢内容）：
+
+1. **机器搬骨架**：建 `conventions/`，旧文件**整体**搬为 `index.md`（原文一字不丢），删除旧文件——此刻 `index.md` 是原文快照，功能上与旧文件等价
+2. **AI 提归属建议**：读原有条目，逐条给出「`common` / 某端」建议与理由（旧文件无端信息，语义分流无法机械完成），形成待确认清单
+3. **用户逐条确认**：确认后写索引行 + 把条文全文拆入对应分册；**未确认的条目保持原样留在 `index.md`**，不强推
+
+补充要求：
+
+- 迁移与内容重排分开做：先完成形态迁移（结构到位），再谈条目归属调整，避免一次变更混合两种风险
+- 端清单在迁移时同步建立：从项目已有 `scope` 取值与实际子项目构成归纳，经用户确认写入端清单节
+- 旧文件已不存在时不重复迁移
+
+### 10.2 v1 → v2 结构升级
+
+触发：`toolkit conventions status` 报「需升级」；`toolkit tasks check` 报形态告警（标为 v2 缺 `history.md` 或索引表首列非 `ID`；有 `history.md` 但首列仍是 `#`）；或用户直接要求升级。
+
+优先用 `toolkit conventions upgrade`（纯机械，可 `--dry-run` 预演），动作序：
+
+1. **发 ID**：按现有条序 `1..n` 发 `C-1..C-n`，索引表首列由 `#` 改 `ID`
+2. **切 `history.md`**：原 `index.md`「演进记录」节整表平移为独立 `history.md`（表头首格归一为 `ID`），`index.md` 撤该节；标题归一 `# 项目协作规范索引`，首行补形态标记（版本段写 `v2`）
+3. **改内部引用**：裸「第 N 条」（仅 N ≤ 索引表最大序号者）改写为 `` `C-<n>` ``；带外部文档限定词前缀的引用（如 `AGENTS.md` 质量门第 5 条、`SPEC.md` 协作模型第 3 条、`task-spec.md` 第 6 节）一律不动；改写清单进报告
+4. **分册小节归一**：分册小节标题改 `## C-<n>. {规则名}`
+
+补充要求：
+
+- **ID 映射不落盘**：映射由 `upgrade` 输出（实跑与 `--dry-run` 均打印）；真值可由 git 历史复现（迁移提交的父提交即 v1 原件），故不落盘代价近零
+- **先判后写**：遇形态异常（标记与结构不一致）拒绝执行并给非 0 退出码，**不写任何文件**，提示人工确认
+- `upgrade` 幂等：已是 v2（或更高）时原样返回，不做二次改写
+- **手工迁 v2 与工具升级的落点不同**：手工迁移按本节在首行写版本段为 `v2` 的形态标记、停在 v2；用 `toolkit conventions upgrade` 升级则不落 v2——工具从 v1 输入链式直达 v3（`v1 → v2 → v3`，见 §10.3），仅手工路径停在 v2
+- 手动迁移时按同一动作序执行
+
+### 10.3 v2 → v3 结构升级
+
+触发：`toolkit conventions status` 报「需升级」；`toolkit tasks check` 报形态告警（标为 v3 缺 `history.md` 或索引表首列非 `ID`；有 `history.md` 但首列仍是 `#`）；或用户直接要求升级。
+
+优先用 `toolkit conventions upgrade`（纯机械，可 `--dry-run` 预演；v1 输入将链式升级 v1 → v2 → v3），动作序：
+
+1. **索引表删两列**：删「状态」「确立来源任务」两列
+2. **`history.md` 表头归一**：v2 存量 `history.md` 沿用「规则 ID / 名称」旧表头，首格归一为稳定 ID `ID`（与索引表首列同归一）
+3. **退休条目迁出**：把原状态为 `已废弃` 的行迁入 `retired.md`（首部补 `# 规范退休记录`、元规则与 7 列表头），并从 Z1 索引表删除；同步删除 Z2 分册内对应小节（三层清理的索引 + 分册两层）
+4. **`retired.md` 按需建**：无退休条目则不创建该文件
+5. **来源 / ID 补录报告**：`history.md` 中 ID 列仍用规则名者、来源列含多任务者，输出人工复核报告——**不做全自动改写**（历史行只追加不改旧的元规则下，改写须人工确认）
+6. **用法说明 / 写入纪律复核**：`index.md` 表外的自由文本（用法说明、写入纪律）若仍残留 v2 措辞（如「填『确立来源任务』」「把『状态』改为『已废弃』」），输出人工复核报告——升级只机械归一索引表列结构，不改写描述该表的自由文本
+7. **标记升 v3**：`index.md` 首行改为 `<!-- toolkit-conventions: v3 -->`
+
+补充要求：
+
+- **先判后写**：遇形态异常（标记与结构不一致）拒绝执行并给非 0 退出码，**不写任何文件**，提示人工确认
+- **dry-run 迁移报告**：`--dry-run` 打印将删的列、将迁出的条目与将删的分册小节、待人工复核项，供人工确认后再实跑
+- `upgrade` 幂等：已是 v3 时原样返回，不做二次改写
+- 手动迁移时按同一动作序执行
+
+## 11. 兼容读（迁移期）
+
+读取时先找 `conventions/index.md`；不存在再看旧单文件 `conventions.md`，存在则按旧单文件内容读取并**在对话中提示可迁移**。两者并存时以目录形态为准，并提示旧文件待清理。v1 / v2 / v3 都按目录形态正常读取，形态判据见 §10.3（`index.md` 首行标记：无标记为 v1，`v2` 且含 `history.md` 与首列 `ID` 为 v2，`v3` 且含 `history.md` 与首列 `ID` 为 v3）。
+
+## 12. 自查清单
+
+- [ ] `index.md` 首行为形态标记（v3 为 `<!-- toolkit-conventions: v3 -->`）
+- [ ] `conventions/` 存在时必有 `index.md`（缺则为形态异常）
+- [ ] 索引表首列为 `ID`，取值为 `C-<n>`：去补零、无重复、退休条目不复用其 ID
+- [ ] v3 形态必有 `history.md`，表头为 `ID | 修订内容 | 修订来源任务`，首列均为行内代码包裹的裸 ID `` `C-<n>` ``，且不改旧行（表头首格非 `ID` 时 `toolkit tasks check` / `toolkit conventions status` 检出并软告警）
+- [ ] `history.md`「修订内容」列无禁用语料：自指套话（「（本次起入表）」「新立条目：」）、重复索引列的条文去向（「条文全文落 X」）；`toolkit tasks check` / `toolkit conventions status` 检出并软告警（见 §3.2）
+- [ ] `index.md` 索引表列集合恰为五列 `ID | 规则 | 当前语义 | 归属 | 单一事实源`，列名与次序均无增删调换（`toolkit tasks check` / `toolkit conventions status` 检出并软告警）
+- [ ] 索引表不含「状态」「确立来源任务」两列（属 v2 遗留，升级时删除；`toolkit tasks check` / `toolkit conventions status` 检出并软告警）
+- [ ] 索引表无已退休条目（退休条目已迁入 `retired.md`，其分册小节已删）
+- [ ] `retired.md` 若存在，表头为 `ID | 规则 | 退休时语义（冻结） | 归属 | 后继 | 退休来源任务 | 条文去向`
+- [ ] 载体各文件（`index.md`、分册、`history.md`、`retired.md`）每张表的表头行与紧随分隔行列数一致（`toolkit tasks check` / `toolkit conventions status` 检出并软告警，跳过 fenced code block）
+- [ ] 载体内部引用均为 `` `C-<n>` ``，无残留裸「第 N 条」
+- [ ] 端清单非空且不含保留字 `index` / `common`
+- [ ] 索引表「归属」列取值为 `common`、端清单端名或已存在的分类标签分册名（无悬空指针）
+- [ ] 分册文件与端清单 + `common` + 分类标签对应，无孤立文件
+- [ ] 旧单文件 `conventions.md` 已迁移（不存在，或已提示待清理）
+- [ ] 有入口壳时其标记与当前 toolkit 一致（落后或无标记可重跑 `toolkit init` 就地更新）、且未被 `.gitignore` 覆盖（否则 `check` / `conventions status` 告警）
+- [ ] 载体与任务区表格为紧凑形态（无列对齐填充、无按列宽补长的分隔行横线；`toolkit conventions format` 可归一，`check` / `conventions status` 会检出）
+- [ ] 规范写入均经用户确认，来源可溯：活跃条目记于写入任务文件正文，退休条目记入 `retired.md` 的「退休来源任务」列
+- [ ] 分册内无「确立来源」行（来源由 `index.md` 索引列与 `history.md` / `retired.md` 承载；`toolkit tasks check` / `toolkit conventions status` 检出并软告警，见 §13）
+
+## 13. 载体文风与模板
+
+§1–§3 规定结构层，本节规定**文风与模板层**。多个仓库的载体在结构上早已一致，分歧集中在头注、用法说明骨架、引用写法、条文格式、规范词与标点这些原先未规定的层面；以下 T1–T6 为**唯一形态**，新载体照此起步、存量载体照此归一，偏离由 `toolkit conventions status` / `toolkit tasks check` 按可机械判定者软告警（只报不改，交人工确认）。
+
+### T1 index 头注固定两行
+
+`index.md` 首行形态标记之后、端清单之前，头注**恰为两行**，各一句 blockquote：
+
+```markdown
+<!-- toolkit-conventions: v3 -->
+# 项目协作规范索引
+
+> 本文件为规范载体唯一入口与唯一权威；规范全貌见下方索引，条文见各分册。
+> 读面纪律：`history.md` / `retired.md` 属归档面，仅在审计 / 恢复时读，不在常规读面。
+```
+
+- 第 1 行说明载体定位（唯一入口 + 条文去向），第 2 行说明归档面读面纪律
+- 头注只承载「读什么、去哪读」；检测面细则、维护步骤、指向 spec 等**不进头注**——它们是写作者须知、非每次建档必读，进了常驻面即违反 §1.1 元原则
+
+### T2 用法说明固定骨架
+
+`index.md`「用法说明」节固定三段，段名与次序为 载体形态 → 本项目约定（可选）→ 读写与维护；通用部分收敛为一句 + 指向本规范，不逐条复述规则正文：
+
+```markdown
+- **载体形态**：本项目采用「溯源索引式」（条文在外部规则层，本载体只索引）/「条文式」（条文在本载体分册）。
+- **本项目约定**：（可选，如 `scope` 分类标签、分册命名等本仓特例；无则整段省略）
+- **读写与维护**：读面与读写判定、写入归属、语义修订与退休流程一律见 `skills/<技能名>/references/conventions-spec.md`，本载体不另述。
+```
+
+- 「载体形态」取值即 §7 两种形态（可混用，需逐条说明时在括号内补述）
+- 「读写与维护」指向 spec，不在此复述 §5 / §6 / §8 的规则正文
+
+### T3 「单一事实源」列写法二分
+
+索引表「单一事实源」列的写法按指向目标二分：
+
+- **载体内分册**（条文就在本载体）→ 相对链接：`[common.md](./common.md)`、`[web.md](./web.md)`
+- **载体外文件**（条文在项目规则层）→ 行内代码：`docs/ai-rules.md`、`AGENTS.md`、`skills/<技能名>/references/task-spec.md`
+- 同格需补充说明时，链接 / 代码之后接短述（如 `skills/<技能名>/references/task-spec.md（口径随版本走）`）
+
+理由：两类指向的可点击性不同——载体内相对链接点击即达；载体外路径跨仓后不可靠，故不作链接、只作行内代码指路。
+
+### T4 分册条文模板
+
+分册内每条条文固定为 小节标题 + 一句当前语义 + 四类子项，**子项次序固定为 要求 → 反例 → 理由 → 配套**：
+
+```markdown
+## C-<n>. {规则名}
+
+{一句当前语义}。
+
+- **要求**：{须做什么 / 不得做什么}。
+- **反例**：{常见的错误做法}。
+- **理由**：{为什么这样规定}。
+- **配套**：{与索引 `C-<n>`、外部载体等的联动关系；无则省略本子项}。
+```
+
+- 子项名与次序固定；`配套` 无内容时整条省略
+- 子项以 `- **{名}**：` 起头（全角冒号），内容用规范词（见 T5）
+- **分册内不得写「确立来源」子项**：来源已由 `index.md` 索引行（活跃条目）与 `history.md` / `retired.md`（留痕与退休）承载，分册内重复即违反 §1.1 不变量 I4；`toolkit conventions status` / `toolkit tasks check` 对残留行软告警（跳过 fenced code block）
+
+### T5 规范词分级
+
+条文正文用统一强弱词，对标 RFC 2119 的 MUST / SHOULD / MAY：
+
+| 词 | 强度 | 含义 |
+| --- | --- | --- |
+| `须` | 强制 | 必须遵守，违反即偏离 |
+| `应` | 推荐 | 通常遵守，例外须有理由 |
+| `可` | 可选 | 允许但不强制 |
+| `不得` | 禁止 | 必须避免 |
+
+同一强度不混用多种措辞——不用「必须」「应该」「不可以」「禁止」等近义词替代上表四词。
+
+### T6 标点与代码
+
+- 标识符、文件路径、文件名、命令、配置项、规则 ID 一律用**行内代码**包裹（如 `C-17`、`index.md`、`toolkit conventions status`、`scope`）
+- 中文引述、术语、举例名用全角直角引号「」，不用英文引号或书名号
+- 中英文混排的空格处理随仓库既有排版习惯，不作硬性要求