@fxri/toolkit 1.11.1 → 1.11.2

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

@@ -1,202 +1,202 @@
-# 规范载体规范（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`）不参与体检。
-
-规范触发面共三层，**任一层可用即可触达**：① 全局技能 `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 条」在升级时改写（见 §9.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` / `前端` 均成立），无全局词表——工具无法预知项目端构成，故不硬编码取值
-
-## 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. 存量迁移
-
-### 9.1 旧单文件 → 目录形态（v0 → v1）
-
-触发：`toolkit tasks check` 报旧 `conventions.md` 存在；或用户直接要求迁移。
-
-**三段式**（可中断，中途停下不丢内容）：
-
-1. **机器搬骨架**：建 `conventions/`，旧文件**整体**搬为 `index.md`（原文一字不丢），删除旧文件——此刻 `index.md` 是原文快照，功能上与旧文件等价
-2. **AI 提归属建议**：读原有条目，逐条给出「`common` / 某端」建议与理由（旧文件无端信息，语义分流无法机械完成），形成待确认清单
-3. **用户逐条确认**：确认后写索引行 + 把条文全文拆入对应分册；**未确认的条目保持原样留在 `index.md`**，不强推
-
-补充要求：
-
-- 迁移与内容重排分开做：先完成形态迁移（结构到位），再谈条目归属调整，避免一次变更混合两种风险
-- 端清单在迁移时同步建立：从项目已有 `scope` 取值与实际子项目构成归纳，经用户确认写入端清单节
-- 旧文件已不存在时不重复迁移
-
-### 9.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 时原样返回，不做二次改写
-- 手动迁移时按同一动作序执行
-
-## 10. 兼容读（迁移期）
-
-读取时先找 `conventions/index.md`；不存在再看旧单文件 `conventions.md`，存在则按旧单文件内容读取并**在对话中提示可迁移**。两者并存时以目录形态为准，并提示旧文件待清理。v1 与 v2 都按目录形态正常读取，形态差异见 §9.2 的判据（`index.md` + `history.md` + 首列 `ID` 为 v2，否则 v1）。
-
-## 11. 自查清单
-
-- [ ] `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` 告警）
-- [ ] 规范写入均经用户确认，且带「确立来源任务」
+# 规范载体规范（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`）不参与体检。
+
+规范触发面共三层，**任一层可用即可触达**：① 全局技能 `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 条」在升级时改写（见 §9.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` / `前端` 均成立），无全局词表——工具无法预知项目端构成，故不硬编码取值
+
+## 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. 存量迁移
+
+### 9.1 旧单文件 → 目录形态（v0 → v1）
+
+触发：`toolkit tasks check` 报旧 `conventions.md` 存在；或用户直接要求迁移。
+
+**三段式**（可中断，中途停下不丢内容）：
+
+1. **机器搬骨架**：建 `conventions/`，旧文件**整体**搬为 `index.md`（原文一字不丢），删除旧文件——此刻 `index.md` 是原文快照，功能上与旧文件等价
+2. **AI 提归属建议**：读原有条目，逐条给出「`common` / 某端」建议与理由（旧文件无端信息，语义分流无法机械完成），形成待确认清单
+3. **用户逐条确认**：确认后写索引行 + 把条文全文拆入对应分册；**未确认的条目保持原样留在 `index.md`**，不强推
+
+补充要求：
+
+- 迁移与内容重排分开做：先完成形态迁移（结构到位），再谈条目归属调整，避免一次变更混合两种风险
+- 端清单在迁移时同步建立：从项目已有 `scope` 取值与实际子项目构成归纳，经用户确认写入端清单节
+- 旧文件已不存在时不重复迁移
+
+### 9.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 时原样返回，不做二次改写
+- 手动迁移时按同一动作序执行
+
+## 10. 兼容读（迁移期）
+
+读取时先找 `conventions/index.md`；不存在再看旧单文件 `conventions.md`，存在则按旧单文件内容读取并**在对话中提示可迁移**。两者并存时以目录形态为准，并提示旧文件待清理。v1 与 v2 都按目录形态正常读取，形态差异见 §9.2 的判据（`index.md` + `history.md` + 首列 `ID` 为 v2，否则 v1）。
+
+## 11. 自查清单
+
+- [ ] `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` 告警）
+- [ ] 规范写入均经用户确认，且带「确立来源任务」

package/skills/fxri-release-changelog/SKILL.md

@@ -3,14 +3,14 @@ name: fxri-release-changelog
 description: 基于 changesets 的发版与多语言 CHANGELOG 维护流程：创建变更集、消费发版、把分组标题与条目转为项目语言风格、清理变更集、打标签发布；无 changesets 的项目提供同格式手工模式。当用户表达发版或记录变更意图——含创建变更集、changeset、发版、version、CHANGELOG 格式化等说法及其口语近义表达（如发一版、出个版本、记一下这次改动、生成更新日志）时使用。⚠️ 注意区分：用户说「提交个版本 / 先提交一版 / commit」通常指 git 提交当前改动（走任务收尾后提交），**不是发版**。不用于日常 commit message 撰写、git 提交操作或与发版无关的文档修改。
 license: MIT
 metadata:
-  version: "1.1.3"
+  version: "1.1.4"
   author: fxri
   source: https://github.com/fxri-net/toolkit
 ---
 
 # 发版与 CHANGELOG
 
-> 本技能版本 1.1.3（随 @fxri/toolkit 同批分发）。被问版本时即报此值——不读磁盘、不跑 CLI：报出的值就是本会话上下文里已加载内容的版本，可与 `toolkit skills status` 打印的磁盘基准值对照，不一致即说明会话上下文已过期，开新会话即可。
+> 本技能版本 1.1.4（随 @fxri/toolkit 同批分发）。被问版本时即报此值——不读磁盘、不跑 CLI：报出的值就是本会话上下文里已加载内容的版本，可与 `toolkit skills status` 打印的磁盘基准值对照，不一致即说明会话上下文已过期，开新会话即可。
 
 ## 何时使用
 

package/skills/fxri-release-changelog/references/changelog-format.md

@@ -43,8 +43,8 @@
 | `依赖：` / 源文本 `- Updated dependencies` | `deps` | `### 🔗 依赖变更` | `### 🔗 Dependency Updates` |
 | 无前缀兜底 | `other` | `### 📦 其他变更` | `### 📦 Other` |
 
-**无前缀条目的兜底规则**：按条目**所属源组标题**声明的影响级别归组——`### Major Changes` → `breaking`、`### Minor Changes` → `added`、`### Patch Changes` → `other`；不从版本号推导。
-
+**无前缀条目的兜底规则**：按条目**所属源组标题**声明的影响级别归组——`### Major Changes` → `breaking`、`### Minor Changes` → `added`、`### Patch Changes` → `other`；不从版本号推导。
+
 **缺前缀的检测入口**：`toolkit tasks check` 扫 `.changeset/` 下待发布变更集（`.md` 且非 `README.md`）的**顶层条目**，逐文件报出缺前缀条目数与首条行号（归档前的早期自查）；发版时 changelog 侧另有兜底告警。前缀识别取全局表与各配置语言 `prefixes` 的并集（自定义语言不误报），依赖源条目归 `deps` 不计缺前缀，缩进续行随父条目迁属、不参与识别。
 
 **追溯历史块的兜底规则**（`--history`）：历史块没有英文源组标题，改按**所属既有组标题**查槽位——先查当前语言组标题，再查历史组标题表（如 `### 🐛 补丁修复` → `fixed`）；两处都识别不出则整组连同标题保留、不臆造归属。
@@ -53,8 +53,8 @@
 
 **归类后剥离类型前缀**：条目归入槽位后，其已被识别的 `类型：` 前缀被剥离（`- 修复：xxx` → `- xxx`）——前缀只是归类信号，类型已由分组标题承接，留在明细里属冗余。未识别的前缀（如正文里的 `说明：`）与依赖源条目原样保留，剥离后文本为空也不改动。默认模式与 `--history` 追溯模式同此规则。
 
-同一槽位来自多个源块时合并为单组，组内保持条目原出现顺序；缩进续行随父条目整体迁移。
-
+同一槽位来自多个源块时合并为单组，组内保持条目原出现顺序；缩进续行随父条目整体迁移。
+
 **归类只搬移、不删内容**：归类只重组「纯条目分组」——分组标题下若在首个条目之前出现非空正文，判据不成立，整块保持原样以免丢内容；未参与归位的分组连同标题按原相对顺序附于块末，不臆造归属、不静默丢弃。CLI 在归类前后做条目数自检，减少即告警（正常合并发生在自检之后、不误报）。
 
 **类型 → 建议 bump**（撰写变更集时按此选影响级别）：
@@ -65,6 +65,13 @@
 | `新增：` / `修改：` | minor |
 | `优化：` / `修复：` / `清理：` / `文档：` | patch |
 
+**级别例外口径**（仅涉 `新增：` / `修改：`；人工裁决、无自动门禁）：
+
+- 类型前缀为 `新增：` / `修改：` 的改动，仅当属「**配套修补型**」——即补原作本应具备的配套（既有能力缺失的配套命令 / 参数 / 忽略规则等），而非独立的新能力——方可按 patch 判定
+- 「**版本号取舍型**」（为凑版本号而记，或主观降级的独立新能力）不适用本口径，仍按上表类型字典的默认级别（`新增：` / `修改：` → minor）
+- 采用例外时须在任务档显式申报「已知与惯例相左」，事后可追溯；对外（变更集正文、CHANGELOG）不写判定依据，只登记变更本身
+- 条目须**分条登记用户可感知的变更**——新增命令 / 参数分开列，不写抽象能力名（否则用户升级后不知多了什么）
+
 ## 3. 多语言扩展
 
 每种语言约定四段结构：