@fxri/toolkit 1.10.5 → 1.11.1

package/skills/fxri-plan-to-task/SKILL.md

@@ -1,27 +1,27 @@
 ---
 name: fxri-plan-to-task
-description: 将已确认的实施方案落盘为标准任务文件并跟踪至归档：动手前建档评估（查 active/archive 判同主题）、按模板建档、状态机更新、四级时间源取证、自查校验、任务级规范沉淀与手工归档。当用户确认方案后表达「开始落地/登记记录」的意图，或即将动手改仓库文件时使用——含建档、任务登记、落盘、归档、任务校验、规范载体迁移（conventions 单文件升目录形态）等说法及其口语近义表达（如按这个做吧、记一下、建个任务跟踪）均触发。不用于方案未确认的对话、会话收尾整场沉淀（fxri-session-recap 模式一）、与任务记录无关的普通 TODO、issue 管理或日常提交信息撰写。
+description: 将已确认的实施方案落盘为标准任务文件并跟踪至归档：动手前建档评估（查 active/archive 判同主题）、按模板建档、状态机更新、四级时间源取证、自查校验、任务级规范沉淀与手工归档。当用户确认方案后表达「开始落地/登记记录」的意图，或即将动手改仓库文件时使用——含建档、任务登记、落盘、归档、任务校验、规范载体迁移与升级（conventions 单文件升目录形态、v1 升 v2）等说法及其口语近义表达（如按这个做吧、记一下、建个任务跟踪）均触发。不用于方案未确认的对话、会话收尾整场沉淀（fxri-session-recap 模式一）、与任务记录无关的普通 TODO、issue 管理或日常提交信息撰写。
 license: MIT
 metadata:
-  version: "1.3.2"
+  version: "1.4.4"
   author: fxri
   source: https://github.com/fxri-net/toolkit
 ---
 
 # 方案落盘：任务建档与归档
 
-> 本技能版本 1.3.2（随 @fxri/toolkit 同批分发）。被问版本时即报此值——不读磁盘、不跑 CLI：报出的值就是本会话上下文里已加载内容的版本，可与 `toolkit skills status` 打印的磁盘基准值对照，不一致即说明会话上下文已过期，开新会话即可。
+> 本技能版本 1.4.4（随 @fxri/toolkit 同批分发）。被问版本时即报此值——不读磁盘、不跑 CLI：报出的值就是本会话上下文里已加载内容的版本，可与 `toolkit skills status` 打印的磁盘基准值对照，不一致即说明会话上下文已过期，开新会话即可。
 
 ## 何时使用
 
-- 用户确认实施方案后，表达开始落地/登记记录的意图（语义触发，不要求字面一致）：建档 / 任务登记 / 落盘 / 归档 / 任务校验 / 规范载体迁移 / 按这个做吧 / 记一下 / 建个任务跟踪
+- 用户确认实施方案后，表达开始落地/登记记录的意图（语义触发，不要求字面一致）：建档 / 任务登记 / 落盘 / 归档 / 任务校验 / 规范载体迁移与升级 / 按这个做吧 / 记一下 / 建个任务跟踪
 - **即将动手改仓库文件前**（方案已确认、准备执行改动）也是本技能适用场景——动手前先做建档评估（见工作流第 1 步），避免跳过建档直接执行
 - 触发前置条件：**方案已确认**。用户说「开始/开工」但方案尚未确认时，先出方案等确认，不建档
 - **何时不使用**：方案未确认的对话；会话收尾的整场沉淀与归档（那是 fxri-session-recap 模式一）；收尾动作（提交、发版、推送、部署）本身——动作不算、改动才算（见工作流第 1 步）；与方案落盘无关的普通 TODO、issue 管理、日历待办、日常提交信息撰写
 
 ## 核心约定
 
-任务文件规范（目录结构、命名、frontmatter 字段、归档格式、手工归档步骤、自查清单）全部以 `references/task-spec.md` 为准；规范载体（conventions）的结构、端名规则、读写判定与存量迁移以 `references/conventions-spec.md` 为准。本文件只写流程。执行任何写操作前先读它们。
+任务文件规范（目录结构、命名、frontmatter 字段、归档格式、手工归档步骤、自查清单）全部以 `references/task-spec.md` 为准；规范载体（conventions）的结构、形态标记与稳定 ID、归属判定、读写判定、内容修订、存量迁移与 v1→v2 升级、入口壳以 `references/conventions-spec.md` 为准。本文件只写流程。执行任何写操作前先读它们。
 
 ## 核心规则
 
@@ -44,7 +44,7 @@ metadata:
 
 - 无 `.tasks/` 任务区时先执行 `toolkit init` 建骨架（幂等，已存在不覆盖）
 - 列出任务目录 `active/` 下全部 `.md`（含一层 `{YYYYMM}/` 月份子目录），并核对 `archive/` 是否已有同主题任务
-- 读 conventions 载体（存在时）：先找 `.tasks/conventions/index.md`，不存在再看旧单文件 `.tasks/conventions.md`（兼容期读取，并在对话中提示可迁移）；常驻只读 `index.md`，再按本任务 `scope` 命中加载 `common` 与端分册（判定见 `references/conventions-spec.md`）；项目协作规范在建档与执行时须遵守；规范载体本身不属于任务，不为其建档
+- 读 conventions 载体（存在时）：先找 `.tasks/conventions/index.md`，不存在再看旧单文件 `.tasks/conventions.md`（兼容期读取，并在对话中提示可迁移）；常驻只读 `index.md`（`history.md` 与各分册按需读），再按本任务 `scope` 命中加载 `common` 与端分册（形态识别与读写判定见 `references/conventions-spec.md`）——载体也可能经项目级技能入口壳（如 `.agents/skills/toolkit-conventions/`）把 agent 引到此处；项目协作规范在建档与执行时须遵守；规范载体本身不属于任务，不为其建档
 - **同主题判别表**（建档前必须按此决策）：
   | 现状 | 本次是否产生仓库文件改动 | 处理 |
   | --- | --- | --- |
@@ -57,7 +57,7 @@ metadata:
 - **仓库文件改动口径**（客观判据，不靠感觉）：需写入版本控制的工作区文件的增 / 改 / 删（源码、配置、文档、技能、任务区自身均计入）；纯读取、纯执行、纯汇报不计入；拿不准 → 列出差异问用户，不猜
 - **动作不算，改动才算**：收尾动作（提交、发版、推送、部署）本身及其固有产物（版本号、更新日志、标签）不构成任务、不作为建档对象；这些动作过程中若出现需改仓库文件才能解决的缺陷（如打包配置错误、发布渠道错误），该修复按普通任务建档
 - **归档块不可变**：已归档块不追加新的工作内容（追加新工作内容会破坏完成时间/范围的可信度）；延续需求一律走新任务。唯一例外是**事实更正**：后续核实推翻原块结论时，在其正文末尾追加「修订记录」（保留原结论、不动元数据行、附更正时刻与依据）
-- 任务唯一键：`{年月日}-{用户名}-{任务简述}`；多人对同一需求共用一个文件
+- 任务唯一键：`{YYYYMMDD}-{用户名}-{任务简述}`；多人对同一需求共用一个文件
 
 ### 2. 建档
 
@@ -86,9 +86,10 @@ metadata:
 
 - 读 conventions 载体（`index.md` 常驻 + 按本任务 `scope` 命中加载分册），判断本任务是否产出可升格规范：用户明示「以后都要这样」的规则、与已有规范重复印证的决策
 - **归属判定**：先问「是否**所有端都适用**」→ 是则归 `common`；否则逐端确认 → 写入命中的端分册（禁止跨端合并归属；`common` 不得用作「不确定归哪端」的暂存区）
-- 有候选 → 输出给用户确认 → 写索引行（带「确立来源任务」）并把条文归位；无候选 → **完全静默**
+- 有候选 → 输出给用户确认 → 写索引行（首列稳定 ID `C-<n>`、带「确立来源任务」）并把条文归位；无候选 → **完全静默**
+- 变更已有规范语义时，先在 `history.md` 追加一行留痕，再更新索引行「当前语义」（细则见 `references/conventions-spec.md`）
 - 一次性决策不进规范，留在任务正文
-- **存量迁移**：发现旧单文件 `conventions.md`（或用户要求迁移）时，按 `references/conventions-spec.md` 的迁移三段式执行（建目录搬原文 → 逐条提归属建议 → 用户确认后拆分册），可中断不丢内容
+- **存量迁移与升级**：发现旧单文件 `conventions.md` 时按迁移三段式执行（建目录搬原文 → 逐条提归属建议 → 用户确认后拆分册）；载体为 v1 或 `check` / `toolkit conventions status` 报形态告警时，按 `references/conventions-spec.md` 的 v1→v2 链路升级（优先 `toolkit conventions upgrade`，可 `--dry-run` 预演）；均可中断不丢内容
 
 ### 6. 收尾边界（硬约束到沉淀）
 
@@ -114,4 +115,6 @@ metadata:
 - `toolkit tasks check`：自动校验（替代第 4 步自查清单）
 - `toolkit tasks archive`：自动归档（替代第 5 步，含排他锁防并发；可 `--dry-run` 预演）
 - `toolkit tasks normalize`：归档后核验归档块（元数据完整性/日期漂移/排序），可 `--fix` 自动修复
+- `toolkit conventions status`：只读体检载体形态与入口壳现场（替代第 1 步人工判形态、第 5.5 步沉淀前后自查）
+- `toolkit conventions upgrade`：v1 → v2 结构升级（第 5.5 步，纯机械、幂等；可 `--dry-run` 预演）
 - 任务目录非默认 `.tasks` 时加 `--dir <path>`

package/skills/fxri-plan-to-task/assets/active-task-template.md

@@ -1,13 +1,13 @@
----
-owner: <负责人 git 用户名>
-status: 待办
-created: <创建日 YYYYMMDD>
-updated: <创建日 YYYYMMDD，随每次修改同步>
-completed: ''
-depends_on: []
-scope: <影响范围>
----
-
-# 任务标题
-
-（方案正文：背景、实施方案、影响范围、验证方式）
+---
+owner: <负责人 git 用户名>
+status: 待办
+created: <创建日 YYYYMMDD>
+updated: <创建日 YYYYMMDD，随每次修改同步>
+completed: ''
+depends_on: []
+scope: <影响范围>
+---
+
+# 任务标题
+
+（方案正文：背景、实施方案、影响范围、验证方式）

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

@@ -1,147 +1,202 @@
-# 规范载体规范（conventions）
-
-> 面向多人 + AI 协作，任何语言项目可直接使用，仅依赖文件读写能力。本文件为 SKILL.md 的配套规范，定义 `.tasks/conventions/` 的目录结构、归属分类、读写判定与存量迁移；任务文件本身的规范见 `task-spec.md`。
-
-## 1. 载体结构
-
-```
-.tasks/
-├── active/                    # 进行中的任务
-├── archive/                   # 已终结任务归档
-└── conventions/               # 项目协作规范载体
-    ├── index.md               # 唯一入口与唯一权威（常驻读）
-    ├── common.md              # 全端通用条文（按需创建）
-    └── <端名>.md              # 各端专有条文（按需创建）
-```
-
-- `index.md` 是唯一入口：端清单在此声明、每条规范在此留一行指针，读取时只读它即可掌握规范全貌
-- 分册**按需创建**，判据是「该归属下有无需独立承载的条文」，不设条数阈值——溯源索引式项目可能始终只有 `index.md`
-- 目录与任务目录同在 `.tasks/` 根层，纯 Markdown 随 git 走；默认 `.tasks` 目录名可随任务区自定而变，内部结构不变
-- 非任务文件：`toolkit tasks` 各子命令不读其内容，`check` 不因内容告警；仅在**载体形态异常**时给软告警（旧单文件残留、缺 `index.md`）
-
-## 2. index.md 结构
-
-四节固定顺序：端清单 → 索引 → 演进记录 → 用法说明。
-
-### 2.1 端清单（唯一权威）
-
-```markdown
-## 一、端清单
-
-> 端名与任务 frontmatter 的 `scope` 取值共用同一套词表；保留字 `index` / `common` 不得作端名。
-
-| 端名 | 说明 |
-| --- | --- |
-| web | 前端主站 |
-| server | 后端服务 |
-```
-
-单端项目写一行或留空表并注明「本项目单端，规范全归 common」。
-
-### 2.2 索引表
-
-```markdown
-| # | 规则 | 当前语义 | 归属 | 状态 | 确立来源任务 | 单一事实源 |
-| --- | --- | --- | --- | --- | --- | --- |
-| 1 | 四级时间源 | 时间取证优先级：当场打点 > 聊天记录时间戳 > git 提交时间 > 系统时间兜底 | common | 生效 | 20260906-会话收尾沉淀能力升级 | task-spec.md（口径随版本走） |
-```
-
-- **归属**：取值必须 ∈ {`common`} ∪ 端清单，否则为悬空指针（需修正）
-- **状态**：`生效` / `已废弃`；废弃不删行，改状态即可（与「归档任务不可变」同哲学：留痕优于抹除）
-- **单一事实源**：条文正文去哪看。已指向项目现有规则层（AGENTS / 全局规则 / skills）时填指向；条文就在本载体分册内时填分册名（如 `common.md`）
-
-### 2.3 演进记录（修订留痕）
-
-规则语义变更不覆盖丢史：先在演进记录追加一行（规则 → 旧语义 → 变更为 → 修订来源任务），再更新索引表当前语义。
-
-```markdown
-| 规则 | 修订内容 | 修订来源任务 |
-| --- | --- | --- |
-```
-
-### 2.4 用法说明
-
-写明本项目采用哪种形态、读写判定要点、以及规则层源头变更时的同步纪律。
-
-## 3. 分册结构
-
-```markdown
-# 全端通用规范（common）
-
-> 归属：common（所有端适用）。条文全文见本节，索引见 index.md。
-
-## 1. 四级时间源
-
-（条文全文）
-```
-
-端分册同构，首部 `# {端名} 规范`、`> 归属：{端名}`。
-
-## 4. 端名规则
-
-- **与任务 frontmatter `scope` 取值逐字一致**：两者共用同一套词表，读取时才能机械匹配（任务写 `scope: web+server` → 加载 `web.md` + `server.md`）
-- **形态约束**：非空、不含空格、不含路径分隔符（`/ \ : * ? " < > |`）
-- **保留字**：`index`、`common` 不得作端名
-- **风格**：随项目 `scope` 既有写法（`web` / `server` / `admin` / `前端` 均成立），无全局词表——工具无法预知项目端构成，故不硬编码取值
-
-## 5. 读取判定（分层）
-
-1. **常驻**：只读 `index.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. 内容修订
-
-- 语义变更：先在「演进记录」留痕，再更新索引表当前语义；条文在分册内的同步改分册
-- 规则作废：索引行状态改 `已废弃`，不删行、不删分册条目
-- 规则层源头变更（AGENTS / 全局规则 / skills 条文改了）：同步检查索引对应行当前语义是否需更新，随该变更同批落盘
-
-## 9. 存量迁移（旧单文件 → 目录形态）
-
-触发：`toolkit tasks check` 报旧 `conventions.md` 存在；或用户直接要求迁移。
-
-**三段式**（可中断，中途停下不丢内容）：
-
-1. **机器搬骨架**：建 `conventions/`，旧文件**整体**搬为 `index.md`（原文一字不丢），删除旧文件——此刻 `index.md` 是原文快照，功能上与旧文件等价
-2. **AI 提归属建议**：读原有条目，逐条给出「`common` / 某端」建议与理由（旧文件无端信息，语义分流无法机械完成），形成待确认清单
-3. **用户逐条确认**：确认后写索引行 + 把条文全文拆入对应分册；**未确认的条目保持原样留在 `index.md`**，不强推
-
-补充要求：
-
-- 迁移与内容重排分开做：先完成形态迁移（结构到位），再谈条目归属调整，避免一次变更混合两种风险
-- 端清单在迁移时同步建立：从项目已有 `scope` 取值与实际子项目构成归纳，经用户确认写入端清单节
-- 旧文件已不存在时不重复迁移
-
-## 10. 兼容读（迁移期）
-
-读取时先找 `conventions/index.md`；不存在再看旧单文件 `conventions.md`，存在则按旧单文件内容读取并**在对话中提示可迁移**。两者并存时以目录形态为准，并提示旧文件待清理。
-
-## 11. 自查清单
-
-- [ ] `conventions/` 存在时必有 `index.md`（缺则为形态异常）
-- [ ] 端清单非空且不含保留字 `index` / `common`
-- [ ] 索引表「归属」列取值 ∈ {`common`} ∪ 端清单（无悬空指针）
-- [ ] 「状态」列取值为 `生效` / `已废弃`
-- [ ] 分册文件与端清单 + `common` 对应，无孤立文件
-- [ ] 旧单文件 `conventions.md` 已迁移（不存在，或已提示待清理）
-- [ ] 规范写入均经用户确认，且带「确立来源任务」
+# 规范载体规范（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-plan-to-task/references/task-spec.md

@@ -1,6 +1,6 @@
 # 任务文件规范（通用版）
 
-> 面向多人 + AI 协作，任何语言项目可直接使用，仅依赖文件读写能力。本文件为 SKILL.md 的配套规范；fxri 生态内实现级权威版本见 toolkit 仓库 SPEC.md。
+> 面向多人 + AI 协作，任何语言项目可直接使用，仅依赖文件读写能力。本文件为 SKILL.md 的配套规范，是 @fxri/toolkit 仓库 `SPEC.md` 的通用裁剪版（去实现化，供非 toolkit 项目直接使用）；两者重叠段以 `SPEC.md` 为单一事实源，本文件新增或改动须回写 `SPEC.md`。
 
 ## 1. 目录结构
 
@@ -13,14 +13,17 @@
 │   └── {YYYYMM}/
 │       └── {YYYYMMDD}.md      # 按完成日期归组的归档文件
 └── conventions/               # 项目协作规范载体（可选，从任务提炼的规范沉淀地）
-    ├── index.md               # 唯一入口与唯一权威：端清单 + 每条一行指针
+    ├── index.md               # 唯一入口与唯一权威（首行为形态标记）：端清单 + 每条一行指针（首列稳定 ID）
+    ├── history.md             # 规范演进记录（仅追加、不改旧行；只记规范语义变更）
     ├── common.md              # 全端通用条文（按需创建）
     └── <端名>.md              # 各端专有条文，端名 = 任务 scope 取值（按需创建）
 ```
 
 目录名 `.tasks` 为默认约定，项目可自定（如集中式任务库按项目分子目录），内部子结构不变。
 
-`conventions/` 不是任务文件：tasks 各子命令不读其内容，check 不会因内容告警（仅在载体形态异常时软告警）；它只作为 AI 协作时的规范源，由 fxri-plan-to-task 归档时与 fxri-session-recap 收尾时维护（写入前需用户确认）。载体结构、端名规则、读写判定与存量迁移见 `conventions-spec.md`。
+`index.md` 首行为形态标记（`<!-- toolkit-conventions: v2 -->`），索引表首列是稳定 ID（`C-<n>`）；无标记的旧形态（v1）仍合法、`check` 不告警，可用 `toolkit conventions upgrade` 升级。载体结构、端名规则、读写判定与存量迁移见 `conventions-spec.md`。
+
+`conventions/` 不是任务文件：tasks 各子命令不读其内容，check 不会因内容告警（仅在载体形态异常与入口层现场异常时软告警，口径见 `conventions-spec.md`）；它只作为 AI 协作时的规范源，由 fxri-plan-to-task 归档时与 fxri-session-recap 收尾时维护（写入前需用户确认）。
 
 ## 2. active 任务文件
 
@@ -36,7 +39,7 @@
 ```yaml
 ---
 owner: 唐启云          # 负责人（git 用户名）
-status: 进行中         # 待办 / 进行中 / 阻塞 / 已完成 / 已放弃
+status: 进行中         # 待办 / 进行中 / 已完成 / 阻塞 / 已放弃
 created: 20260902     # 创建日 YYYYMMDD，须等于文件名日期前缀
 updated: 20260902     # 最近更新日 YYYYMMDD
 completed: ''         # 完成时间 YYYY-MM-DD HH:mm；仅终结态必填
@@ -51,7 +54,7 @@ scope: app            # 影响范围；多值以半角加号分隔（toolkit+lxg
   3. **任务改动 git 提交时间**：`git log --format="%h %ci" <file>` 按提交时间取证
   4. **系统当前时间兜底**：前三级皆不可得时当场取时，并在正文标注「时间为收尾补记」
   
-  工具对「完成时间晚于当前系统时间」会告警（时间源错误的典型症状）；完成时间恰为零点整（如 `2026-09-05 00:00`，只填日期被自动补零的典型特征）亦会告警，需人工核实。归档块完成时间早于归档动作时间属正常（补档/历史修正场景），迁移由 `normalize --fix` 自动完成
+  工具对「完成时间晚于当前系统时间」会告警（时间源错误的典型症状）——为免跨时区误报，工具留最大正偏移（UTC+14）容差，实则晚于当前时刻 14 小时以上才告警；完成时间恰为零点整（如 `2026-09-05 00:00`，只填日期被自动补零的典型特征）亦会告警，需人工核实。归档块完成时间早于归档动作时间属正常（补档/历史修正场景），迁移由 `normalize --fix` 自动完成
 - 正文以 `# 任务标题` 开头；游离待办子项必须拆为独立任务文件
 
 ## 3. 归档文件
@@ -61,7 +64,7 @@ scope: app            # 影响范围；多值以半角加号分隔（toolkit+lxg
 - 每个任务块：
 
 ```markdown
-## {年月日}-{用户名}-{任务简述}
+## {YYYYMMDD}-{用户名}-{任务简述}
 
 > 负责人：{owner}　状态：{status}　范围：{scope}　完成时间：{completed}
 

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.1"
+  version: "1.1.3"
   author: fxri
   source: https://github.com/fxri-net/toolkit
 ---
 
 # 发版与 CHANGELOG
 
-> 本技能版本 1.1.1（随 @fxri/toolkit 同批分发）。被问版本时即报此值——不读磁盘、不跑 CLI：报出的值就是本会话上下文里已加载内容的版本，可与 `toolkit skills status` 打印的磁盘基准值对照，不一致即说明会话上下文已过期，开新会话即可。
+> 本技能版本 1.1.3（随 @fxri/toolkit 同批分发）。被问版本时即报此值——不读磁盘、不跑 CLI：报出的值就是本会话上下文里已加载内容的版本，可与 `toolkit skills status` 打印的磁盘基准值对照，不一致即说明会话上下文已过期，开新会话即可。
 
 ## 何时使用
 
@@ -31,7 +31,7 @@ metadata:
 
 ## changesets 流程
 
-1. 记录变更：`npx changeset`（或项目包管理器等价脚本）——**变更描述一律以 `类型：` 前缀开头**（如 `新增：` / `修复：` / `优化：`），并按类型选影响级别（重大→major、新增/修改→minor、优化/修复/清理/文档→patch，完整对照见 `references/changelog-format.md`）
+1. 记录变更：`npx changeset`（或项目包管理器等价脚本）——**变更描述一律以 `类型：` 前缀开头**（如 `新增：` / `修复：` / `优化：`），并按类型选影响级别（重大→major、新增/修改→minor、优化/修复/清理/文档→patch，完整对照见 `references/changelog-format.md`）。写完可跑 `toolkit tasks check` 早期自查：它扫 `.changeset/` 下待发布变更集，逐文件报出缺前缀条目与条数（免得到发版、变更集源被消费删除后才由 changelog 侧兜底告警——那时已无从补写）
 2. 消费发版：`npx changeset version`——自动写版本号与 CHANGELOG
 3. 格式化：按 `references/changelog-format.md` 的语义分组规则归类条目、转换分组标题、润色为项目语言风格（中文示例：`### Patch Changes` 下的 `- 修复：xxx` → `### 🐛 问题修复` 下的 `- xxx`——归类后类型前缀被剥离，类型由分组标题承接）；分组维度与 bump 维度正交，条目归组只看类型前缀
 4. 归一：润色后跑一次 `toolkit changelog --history format`——人工润色（含补写历史块明细）容易在条目之间留空行，该命令按「同组顶层条目逐行相邻」重排历史块；项目另有更新日志镜像页（如 `docs/changelog.md`）时再跑一次同步脚本，否则镜像一致性校验会失败
@@ -53,8 +53,10 @@ metadata:
 | CHANGELOG 出现「- - 条目」双前缀伪影（变更集条目以 `- ` 开头） | `toolkit changelog version/format` 已自动还原为顶层条目；手工模式按 references 规则手动清理 |
 | 条目与仓库既有风格不一致 | 人工润色为项目语言与句式，勿保留机器直译 |
 | 变更集遗漏（发版后才发现功能未记录） | 补建变更集随下次发版；本次在发布说明中人工补充 |
+| `toolkit tasks check` 报「变更集条目缺类型前缀」 | 打开所列文件，给缺前缀的**顶层条目**按「类型：描述」补前缀（缩进续行随父条目迁属、无需加）；补前缀只改分类信号，不改变 bump 级别 |
 | 改动已发布却无归档记录（有提交、无任务档） | 先补归档（fxri-session-recap 模式一）再继续发布后续步骤；发版本身不补建档 |
 | 发版后历史块内出现多余空行（`自举一致性` 类零改动用例失败） | 跑 `toolkit changelog --history format` 归一（**必须带 `--history`**，默认模式不动历史块），再补跑一次镜像页同步脚本 |
+| 格式化时 stderr 报「归类后条目数由 N 降为 M，疑似丢失内容」 | 归类只应搬移条目，减少即疑似丢内容：核对该版本块是否含非纯条目分组（标题下先出现正文）或被保留分组；确认属正常去重可忽略，否则按 references 的归类规则修回 |
 
 ## 可选加速（不构成依赖）
 
@@ -65,5 +67,6 @@ metadata:
 - `toolkit changelog format`：仅格式化既有 CHANGELOG
 - `toolkit changelog --history format`：连带追溯改写历史版本块（用户主动要求修正历史块时才加，默认不动）
 - `toolkit changelog --lang <语言> …`：切换输出语言（内置 zh / en，其余可配置扩展）
+- `toolkit tasks check`：扫 `.changeset/` 下待发布变更集并逐文件报出缺前缀条目（流程第 1 步的早期自查入口，归档前的 `tasks check` 即含此项）
 - ⚠️ `changelog` 域开了选项透传，自有选项（`--lang` / `--history` / `--redact` / `--warn`）必须写在子命令**之前**：`toolkit changelog --history format` 生效，写成 `toolkit changelog format --history` 会被 changesets 静默忽略（表现为「无 CHANGELOG 需要更新」）
 - `toolkit skills install` / `toolkit skills status`：把本包 fxri-* 技能分发到各 agent 全局技能目录 / 查看链接与副本现场（技能随包同源分发，与 CLI 同一发布批次；技能内容版本独立编号，`skills status` 会打印各技能真源版本）

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

@@ -43,15 +43,19 @@
 | `依赖：` / 源文本 `- 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`）；两处都识别不出则整组连同标题原样保留。
+**追溯历史块的兜底规则**（`--history`）：历史块没有英文源组标题，改按**所属既有组标题**查槽位——先查当前语言组标题，再查历史组标题表（如 `### 🐛 补丁修复` → `fixed`）；两处都识别不出则整组连同标题保留、不臆造归属。
 
 **依赖条目不走前缀解析**：源组标题 `### Dependent Changes` 整块，以及源文本 `- Updated dependencies`（含缩进子项）一律归入 `deps` 槽位。
 
 **归类后剥离类型前缀**：条目归入槽位后，其已被识别的 `类型：` 前缀被剥离（`- 修复：xxx` → `- xxx`）——前缀只是归类信号，类型已由分组标题承接，留在明细里属冗余。未识别的前缀（如正文里的 `说明：`）与依赖源条目原样保留，剥离后文本为空也不改动。默认模式与 `--history` 追溯模式同此规则。
 
-同一槽位来自多个源块时合并为单组，组内保持条目原出现顺序；缩进续行随父条目整体迁移。
+同一槽位来自多个源块时合并为单组，组内保持条目原出现顺序；缩进续行随父条目整体迁移。
+
+**归类只搬移、不删内容**：归类只重组「纯条目分组」——分组标题下若在首个条目之前出现非空正文，判据不成立，整块保持原样以免丢内容；未参与归位的分组连同标题按原相对顺序附于块末，不臆造归属、不静默丢弃。CLI 在归类前后做条目数自检，减少即告警（正常合并发生在自检之后、不误报）。
 
 **类型 → 建议 bump**（撰写变更集时按此选影响级别）：