@fxri/toolkit 1.12.2 → 1.12.4

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # 方弦工具集
 
+## 1.12.4
+
+> 2026-10-19 发布
+
+### ✨ 新增功能
+
+- `docs/ai-rules.md` 补「规划先行」「逐仓逐任务建档」「按序交付、逐任务提交」三条稳定纪律，多任务方案先出纯展示计划表再逐仓逐任务建档
+
+### 🔧 功能调整
+
+- `fxri-plan-to-task` 新增任务分解与展示型计划表步骤，建档改为逐仓逐任务，交付改为按序推进、逐任务提交；任务粒度判据与反例下沉 `task-spec.md`
+- `fxri-session-recap` 收尾时按仓逐任务建档，恢复时按任务正文的顺序线索重建执行顺序
+
+### ⚡ 优化改进
+
+- `fxri-plan-to-task` 的 references 改为按场景读取，普通建档不再提前加载迁移与模板细则
+- `fxri-plan-to-task` 1.9.0 压缩正文，`conventions-spec.md` 拆出存量迁移（`conventions-migration.md`）与文风模板（`conventions-templates.md`）两份按需加载 references，日常只读主文件
+- `fxri-session-recap` 1.5.0 合并重复纪律，规范载体细节改为指针，不再复述 `conventions-spec.md` 内容
+- `fxri-release-changelog` 1.2.0 精简触发词与失败模式说明，`changelog-format.md` 自查说明改为指向检测入口
+- `fxri-session-recap` 1.6.0 将模式二（恢复上下文）与模式三（历史时间修正）下沉为 `references/mode-2-recovery.md` / `mode-3-time-fix.md` 按需加载，主文件只留概要、关键护栏与读取指针，常用且高风险的模式一仍内联
+- `fxri-plan-to-task` 1.9.1 与 `fxri-session-recap` 的存量迁移、载体升级细节压缩为触发条件 + 指针，细则只在 `conventions-migration.md` 维护
+
+### 🐛 问题修复
+
+- 修正文档触达面清单的过期枚举，改为遍历 docs 全量页面，避免新增页面漏检
+- `fxri-release-changelog` 1.2.1 修正 `changelog-format.md` 文件结构示例仍带类型前缀、与「归类后剥离前缀」规则冲突
+
+### 📝 文档更新
+
+- `SPEC.md`、`README.md`、`docs/getting-started.md`、`docs/handbook.md`、`docs/guide.md` 同步开工门槛与逐任务交付口径
+- 移除全局规则页中重复的升级说明措辞
+- 明确不要把 SKILL.md 链接为常驻规则，并修正兄弟技能 references 的引用纪律
+- `skills/README.md`、`docs/guide.md` 技能版本表随各技能内容改动同步（当前 1.9.2 / 1.2.1 / 1.6.0）
+- `skills/README.md`、`docs/guide.md`、`docs/faq.md` 澄清技能加载口径——`description` 常驻用于匹配触发、正文触发时加载、`references/` 按需读取，不再声称「零上下文占用」「未声明不会自动介入」
+- 发布核对清单与单元测试新增加载体积守卫——主干 `SKILL.md` 不超过 8,000 字符
+
+### 🧹 清理移除
+
+- `AGENTS.md` 发版链路删除与「验收方式」重复的步骤定义指针，`docs/ai-rules.md` 删除与「规划先行」重复的稳定纪律条目
+
+## 1.12.3
+
+> 2026-10-18 发布
+
+### 📝 文档更新
+
+- 明确 T5 规范词适用范围覆盖 history 留痕行
+
 ## 1.12.2
 
 > 2026-10-16 发布

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright © 2026 唐启云
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright © 2026 唐启云
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -1,9 +1,9 @@
-@fxri/toolkit
-Copyright © 2026 唐启云. All rights reserved.
-
-出品方：方弦研究所（唐启云个人项目品牌，非独立法人实体）
-
-商标声明：
-"方弦®"为第42类注册商标（注册号89648411），核定服务项目：计算机出租、计算机软件设计、为他人研究和开发新产品、计算机软件维护、把有形的数据或文件转换成电子媒体、为他人创建和维护网站、网络服务器出租、提供互联网搜索引擎、托管计算机站（网站）、云计算。
-本开源许可（MIT License）不授予商标使用权。
-详见 TRADEMARK.md 了解完整商标信息。
+@fxri/toolkit
+Copyright © 2026 唐启云. All rights reserved.
+
+出品方：方弦研究所（唐启云个人项目品牌，非独立法人实体）
+
+商标声明：
+"方弦®"为第42类注册商标（注册号89648411），核定服务项目：计算机出租、计算机软件设计、为他人研究和开发新产品、计算机软件维护、把有形的数据或文件转换成电子媒体、为他人创建和维护网站、网络服务器出租、提供互联网搜索引擎、托管计算机站（网站）、云计算。
+本开源许可（MIT License）不授予商标使用权。
+详见 TRADEMARK.md 了解完整商标信息。

package/README.md

@@ -31,7 +31,7 @@ pnpm exec toolkit init
 pnpm exec toolkit tasks
 ```
 
-之后：方案确认后登记为 `.tasks/` 任务文件 → `pnpm exec toolkit tasks check` 校验 → 完成后 `pnpm exec toolkit tasks archive` 归档并做规范沉淀。完整步骤见 [新手指南](./docs/getting-started.md)。
+之后：方案确认后登记为 `.tasks/` 任务文件 → `pnpm exec toolkit tasks check` 校验 → 完成后 `pnpm exec toolkit tasks archive` 归档并做规范沉淀。多任务 / 多仓方案先出纯展示计划表，再逐仓逐任务建档、按序逐个交付提交。完整步骤见 [新手指南](./docs/getting-started.md)。
 
 ## ✨ 能力矩阵
 
@@ -71,7 +71,7 @@ pnpm dlx skills add fxri-net/toolkit                  # 也可用上游安装器
 
 技能随包分发（真源为包内 `skills/`），与 CLI 同一发布批次（技能内容版本独立编号）；`toolkit skills install` 默认软链，链接创建失败自动降级副本，`toolkit skills status` 查现场，`toolkit skills remove` 卸载。`--scope project` 换项目面——真源落 `<仓库根>/.agents/skills/`、其余候选目录落入口薄壳，随 git 入库后队友 clone 靠 `toolkit init` 写入的 `prepare` 钩子自动补齐。
 
-- [fxri-plan-to-task](./skills/fxri-plan-to-task/SKILL.md)：方案确认后落盘为任务文件（动手前建档评估、check、归档 + 任务级规范沉淀为强制终点）
+- [fxri-plan-to-task](./skills/fxri-plan-to-task/SKILL.md)：方案确认后落盘为任务文件（任务分解与纯展示计划表、逐仓逐任务建档、check、归档 + 任务级规范沉淀为强制终点）
 - [fxri-release-changelog](./skills/fxri-release-changelog/SKILL.md)：发版时创建变更集、格式化多语言 CHANGELOG
 - [fxri-session-recap](./skills/fxri-session-recap/SKILL.md)：会话收尾全量沉淀、新会话三层恢复、历史任务时间批量修正（1.7.0 新增技能）
 

package/SPEC.md

@@ -1,6 +1,6 @@
 # 任务文件规范（SPEC）
 
-> 规范更新时间 2026-10-16 16:57。本规范内容变更时以变更时刻更新此值，实现方与规范快照据此对照是否失同步。
+> 规范更新时间 2026-10-19 15:35。本规范内容变更时以变更时刻更新此值，实现方与规范快照据此对照是否失同步。
 
 > 本规范**全语言支持**，面向**多人 + AI 跨项目协作**，定义任务文件的目录结构、文件格式与归档规则。任何编程语言均可按本规范实现读写；@fxri/toolkit 的 `tasks` 域仅为参考实现。
 >
@@ -12,9 +12,10 @@
 
 1. **先查后写**：新建、更新或归档任务前，先 `toolkit tasks` 查看 active 总览，并核对 archive 是否已有同主题任务；active 已有同主题任务则更新原文件，禁止重复建档；已分叉成不同范围时问用户（拆新任务 or 合并更新）。archive 已有同主题任务（已归档完成）时按**改动判别**：本次不产生仓库文件改动（重复提议 / 重复执行）则不重复建档，仅提示「同主题任务已归档于 {日期}」；本次产生仓库文件改动（延续 / 扩展 / 重新实现）则重新建档，并在正文首行标注来源链 `延续 {原归档任务名}（见 archive/{YYYYMM}/{YYYYMMDD}.md）`；仅修正旧记录的时间或内容走历史修正（fxri-session-recap 模式三），不建档。**仓库文件改动口径**：需写入版本控制的工作区文件的增 / 改 / 删（源码、配置、文档、技能、任务区自身均计入），纯读取、纯执行、纯汇报不计入；拿不准时列出差异问用户，不猜。**归档块不可变**：已归档块不追加新的工作内容，延续需求一律走新任务；唯一例外是**事实更正**——后续核实推翻原块结论、或协作口径变更导致历史事实字段需更正时，在其正文末尾追加「修订记录」（保留原结论、附更正时刻与依据）；口径变更类更正可改受影响的**事实字段**（如 `scope`），但唯一键 / 完成时间 / 状态 / 负责人仍冻结。
 2. **任务唯一键**：`{YYYYMMDD}-{用户名}-{任务简述}` 唯一标识一个任务；多人对同一需求不得各自建档，应共用同一文件。
-3. **收尾边界到沉淀**：强制约束到「归档 + 规范沉淀」为止——终结态任务归档后做任务级规范沉淀（写入 conventions 载体），归档 + 沉淀即流程终点；提交、发版、推送不是必经步骤，是否执行取决于用户的全局 / 个人 / 项目规则。**动作不算，改动才算**：任务 = 已确认的方案 + 它落地的仓库文件改动；收尾动作（提交、发版、推送、部署）本身及其固有产物（版本号、更新日志、标签）不构成任务、不单独建档，但当这些动作过程中出现需改仓库文件才能解决的缺陷（如打包配置错误、发布渠道错误）时，该修复按普通任务建档。若提交代码，先归档与沉淀、后提交，任务记录与代码变更落在同一 git 提交。
+3. **收尾边界到沉淀**：强制约束到「归档 + 规范沉淀」为止——终结态任务归档后做任务级规范沉淀（写入 conventions 载体），归档 + 沉淀即流程终点；提交、发版、推送不是必经步骤，是否执行取决于用户的全局 / 个人 / 项目规则。**动作不算，改动才算**：任务 = 已确认的方案 + 它落地的仓库文件改动；收尾动作（提交、发版、推送、部署）本身及其固有产物（版本号、更新日志、标签）不构成任务、不单独建档，但当这些动作过程中出现需改仓库文件才能解决的缺陷（如打包配置错误、发布渠道错误）时，该修复按普通任务建档。若提交代码，先归档与沉淀、后提交，任务记录与代码变更落在同一 git 提交。**逐任务交付**：一个任务至少一次提交、允许多次；不得把多个任务攒成一个提交，也不得为凑一次提交塞入无关改动。
 4. **可执行项必须落地为任务**：方案正文里的「待办 / 待实施 / 待核对」等子项，应拆分为独立 active 任务，不留游离待办；`toolkit tasks check` 会扫描此类未闭合标记。
 5. **跨仓库改动各自归档**：任务档是**仓库自述**，只记本仓的改动与动机；跨仓库是**会话属性而非仓库属性**，同一会话涉及多仓时各仓各自建档归档，不在一仓记录里承载另一仓的工作痕迹。判据取**视角**（描述的是不是本仓的改动与动机），非词表——依赖包名 / 被调接口名等属本仓事实者照写。故 `scope` 只标本仓内的端 / 面（见第 2 节）。通用裁剪版见技能包 `task-spec.md`。
+6. **开工门槛与任务分解**：方案确认后、动手前先做任务分解——一个任务 = 可独立验收、可独立回滚、单独提交后仓库自洽的最小交付单元，且不跨仓库。涉及两个及以上任务时，先给出一张**纯展示的开发计划表**（跨端、跨仓同表，标明所属仓库与执行先后）；表只作展示与排序，不落档、不写入任务正文。随后**逐仓逐任务建档**：每个将产生仓库文件改动的仓库按任务清单各自独立建档，只读参与的仓库不建档，全部建档后再改第一处文件。按表顺序推进，前置未完成或阻塞未解除时下游不开工；计划调整先更新展示表再继续。任务粒度判据、表结构与反例见技能包 `task-spec.md`；状态以任务 frontmatter 为唯一真源。
 
 ## 1. 目录结构
 

package/TRADEMARK.md

@@ -1,41 +1,41 @@
-# 商标声明
-
-## 基本信息
-
-| 项目 | 内容 |
-|---|---|
-| 商标名称 | 方弦® |
-| 商标类型 | 文字商标 |
-| 商标说明 | 商标由文字"方弦"组成 |
-| 商标类别 | 第42类（共10项） |
-| 注册号 | 89648411 |
-| 申请人 | 唐启云 |
-| 递交商标局 | 2026-01-12 |
-| 版本 | 基础版 |
-
-## 第42类服务项目
-
-计算机出租；计算机软件设计；为他人研究和开发新产品；计算机软件维护；把有形的数据或文件转换成电子媒体；为他人创建和维护网站；网络服务器出租；提供互联网搜索引擎；托管计算机站（网站）；云计算。
-
-## 权利状态
-
-"方弦®"商标（注册号89648411）已获中国国家知识产权局商标局核准注册，核定使用于第42类上述服务项目，现为注册商标。
-
-## 授权范围
-
-本仓库的开源许可证（MIT License）仅授予代码的使用、修改和分发权利，**不构成对任何商标、服务标记或品牌名称的授权许可**。
-
-任何派生作品、修改版本、商业产品均不得使用"方弦"名称、Logo 或相关标识，除非获得书面授权。
-
-## 使用规范
-
-- 在开源社区讨论、文档引用中提及本项目时，可使用"方弦®"指代本项目名称
-- 未经书面授权，不得在任何商业产品、服务或宣传材料中使用"方弦"标识
-
-## 获取授权
-
-如需将"方弦"商标用于商业用途，请联系：唐启云 <tqy@fxri.net>
-
-## 侵权处理
-
-如发现未经授权使用"方弦®"商标的行为，请通过上述联系方式举报。
+# 商标声明
+
+## 基本信息
+
+| 项目 | 内容 |
+|---|---|
+| 商标名称 | 方弦® |
+| 商标类型 | 文字商标 |
+| 商标说明 | 商标由文字"方弦"组成 |
+| 商标类别 | 第42类（共10项） |
+| 注册号 | 89648411 |
+| 申请人 | 唐启云 |
+| 递交商标局 | 2026-01-12 |
+| 版本 | 基础版 |
+
+## 第42类服务项目
+
+计算机出租；计算机软件设计；为他人研究和开发新产品；计算机软件维护；把有形的数据或文件转换成电子媒体；为他人创建和维护网站；网络服务器出租；提供互联网搜索引擎；托管计算机站（网站）；云计算。
+
+## 权利状态
+
+"方弦®"商标（注册号89648411）已获中国国家知识产权局商标局核准注册，核定使用于第42类上述服务项目，现为注册商标。
+
+## 授权范围
+
+本仓库的开源许可证（MIT License）仅授予代码的使用、修改和分发权利，**不构成对任何商标、服务标记或品牌名称的授权许可**。
+
+任何派生作品、修改版本、商业产品均不得使用"方弦"名称、Logo 或相关标识，除非获得书面授权。
+
+## 使用规范
+
+- 在开源社区讨论、文档引用中提及本项目时，可使用"方弦®"指代本项目名称
+- 未经书面授权，不得在任何商业产品、服务或宣传材料中使用"方弦"标识
+
+## 获取授权
+
+如需将"方弦"商标用于商业用途，请联系：唐启云 <tqy@fxri.net>
+
+## 侵权处理
+
+如发现未经授权使用"方弦®"商标的行为，请通过上述联系方式举报。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fxri/toolkit",
-  "version": "1.12.2",
+  "version": "1.12.4",
   "description": "专为多人 + AI 跨项目协作打造：任务管理 + 多语言 CHANGELOG。",
   "license": "MIT",
   "author": {

package/skills/README.md

@@ -8,9 +8,9 @@
 
 | 技能 | 版本 | 用途 |
 | --- | --- | --- |
-| [fxri-plan-to-task](./fxri-plan-to-task/SKILL.md) | 1.8.7 | 方案落盘：建档评估（先查后写）→ 建档 → 校验 → 归档 → 任务级规范沉淀（能力终点）；规范载体迁移与升级 |
-| [fxri-release-changelog](./fxri-release-changelog/SKILL.md) | 1.1.9 | changesets 发版与多语言 CHANGELOG 维护 |
-| [fxri-session-recap](./fxri-session-recap/SKILL.md) | 1.4.1 | 会话收尾全量沉淀 + 规范沉淀 / 新会话三层恢复 / 历史任务时间批量修正 |
+| [fxri-plan-to-task](./fxri-plan-to-task/SKILL.md) | 1.9.2 | 方案落盘：任务分解与纯展示计划表 → 逐仓逐任务建档 → 校验 → 归档 → 任务级规范沉淀（能力终点）；规范载体迁移与升级 |
+| [fxri-release-changelog](./fxri-release-changelog/SKILL.md) | 1.2.1 | changesets 发版与多语言 CHANGELOG 维护 |
+| [fxri-session-recap](./fxri-session-recap/SKILL.md) | 1.6.0 | 会话收尾全量沉淀 + 规范沉淀 / 新会话三层恢复 / 历史任务时间批量修正 |
 
 版本号取自各 SKILL.md 的 frontmatter `metadata.version`（`toolkit skills status` / `skills install` 打印的真源版本），与正文首部版本声明双写一致。
 
@@ -66,7 +66,7 @@ pnpm dlx skills add fxri-toolkit --global       # npm 用户把 pnpm dlx 换成
 
 - 已安装 `@fxri/toolkit` 的项目可直接使用包内自带的技能目录：`node_modules/@fxri/toolkit/skills/`，复制或软链到 agent 的 skills 目录即可
 - 复制或软链技能目录到 agent 的 skills 目录（如 Claude Code 的 `.claude/skills/`）
-- 支持自定义 rules 的工具（如 Trae）：链接 SKILL.md 为规则
+- 支持自定义 rules 的工具（如 Trae）：**不要把 SKILL.md 链接为规则**——规则会常驻上下文，等于绕过按需加载；应放入技能目录（`toolkit skills install` 已覆盖 Trae 技能目录）。仅当确需该技能每轮常驻时，才考虑链接为规则。
 - 通用兜底：在项目根 `AGENTS.md` 中引用本目录路径
 
 复制副本以 frontmatter `metadata.version` 判断是否需要同步上游（`metadata.source` 指向本仓库）。
@@ -82,7 +82,7 @@ pnpm dlx skills add fxri-toolkit --global       # npm 用户把 pnpm dlx 换成
 
 ## 与其他 skills 共存
 
-每个技能是独立目录、独立激活单元：agent 按 `description` 匹配任务按需加载，不用到的技能零上下文占用。唯一约束是目录名（即 `name`）不重复；`description` 已含反向排除，与常见通用技能重叠概率低。
+每个技能是独立目录、独立激活单元：兼容 agent 会把各技能的 `description` 常驻上下文用于匹配触发，正文仅在触发时加载、`references/` 按需读取——不触发的技能只占 `description` 这一层，不占正文体积。唯一约束是目录名（即 `name`）不重复；`description` 已含反向排除，与常见通用技能重叠概率低。
 
 ## 命名约定
 
@@ -94,9 +94,9 @@ pnpm dlx skills add fxri-toolkit --global       # npm 用户把 pnpm dlx 换成
 - [ ] name：kebab-case、与目录名一致、≤64 字符
 - [ ] description：≤1024 字符，含做什么 + 何时用 + 正向触发词 + 反向排除
 - [ ] metadata.version：内容变更即递增，且与正文首部版本声明一致
-- [ ] 主干 SKILL.md < 200 行，细节下沉 `references/`，可复制资产放 `assets/`
+- [ ] 主干 SKILL.md < 200 行且 ≤ 8,000 字符，细节下沉 `references/`，可复制资产放 `assets/`
 - [ ] 引用的 references / assets 相对路径有效
 - [ ] 技能用途描述已同步 docs/guide 技能表与本文「技能列表」表（含版本标注）
-- [ ] 涉规范载体（conventions）的改动：`fxri-session-recap/SKILL.md` 的 R3 压缩要点已与 `fxri-plan-to-task/references/conventions-spec.md` 同步（跨 skill 不可引用，只能受控重复，两处不一致即失一致）
+- [ ] 涉规范载体（conventions）的改动：`fxri-session-recap/SKILL.md` 的 R3 压缩要点已与 `fxri-plan-to-task/references/conventions-spec.md` 同步（引用兄弟技能 references 时须用相对路径并给出包内真源兜底，两处不一致即失一致）
 - [ ] 涉规范载体（conventions）的改动：`src/init.ts` 的 `index.md` / `history.md` 骨架模板与入口壳版本分流、`src/tasks/validate.ts` 的形态告警口径、`src/conventions/` 的形态识别与升级链路、`src/conventions/entry.ts` 的入口壳生成与版本告警已同步（CLI 侧与 skills 细则同源）
 - [ ] 变更已走本仓库质量门：三方一致 + tasks check + pnpm test

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

@@ -1,16 +1,16 @@
 ---
 name: fxri-plan-to-task
-description: 将已确认的实施方案落盘为标准任务文件并跟踪至归档：动手前建档评估（查 active/archive 判同主题）、按模板建档、状态机更新、四级时间源取证、自查校验、任务级规范沉淀与手工归档。当用户确认方案后表达「开始落地/登记记录」的意图，或即将动手改仓库文件时使用——含建档、任务登记、落盘、归档、任务校验、规范载体迁移与升级（conventions 单文件升目录形态、v1 / v2 升 v3）等说法及其口语近义表达（如按这个做吧、记一下、建个任务跟踪）均触发。不用于方案未确认的对话、会话收尾整场沉淀（fxri-session-recap 模式一）、与任务记录无关的普通 TODO、issue 管理或日常提交信息撰写。
+description: 将已确认的实施方案分解为可独立交付的任务并给出计划表，再落盘为标准任务文件并跟踪至归档：建档评估（查 active/archive 判同主题）、按模板建档、状态机更新、四级时间源取证、自查、任务级规范沉淀与归档。方案确认后表达「开始落地/登记记录」的意图，或即将改仓库文件时使用——含任务分解、建档、任务登记、落盘、归档、任务校验、规范载体迁移与升级（conventions 单文件升目录、v1 / v2 升 v3）等说法及口语近义表达（如按这个做吧、记一下、建个任务跟踪）均触发。不用于方案未确认的对话、会话收尾整场沉淀（fxri-session-recap 模式一）、与任务记录无关的普通 TODO、issue 管理或日常提交信息撰写。
 license: MIT
 metadata:
-  version: "1.8.7"
+  version: "1.9.2"
   author: fxri
   source: https://github.com/fxri-net/toolkit
 ---
 
 # 方案落盘：任务建档与归档
 
-> 本技能版本 1.8.7（随 @fxri/toolkit 同批分发）。被问版本时即报此值——不读磁盘、不跑 CLI：报出的值就是本会话上下文里已加载内容的版本，可与 `toolkit skills status` 打印的磁盘基准值对照，不一致即说明会话上下文已过期，开新会话即可。
+> 本技能版本 1.9.2（随 @fxri/toolkit 同批分发）。被问版本时即报此值（不读磁盘、不跑 CLI）；与 `toolkit skills status` 的磁盘值不一致即说明会话上下文已过期，开新会话即可。
 
 ## 何时使用
 
@@ -21,7 +21,7 @@ metadata:
 
 ## 核心约定
 
-任务文件规范（目录结构、命名、frontmatter 字段、归档格式、手工归档步骤、自查清单）全部以 `references/task-spec.md` 为准；规范载体（conventions）的三分区结构、形态标记与稳定 ID、归属判定、分层读写判定、内容修订（含作废的三层清理）、表格形态（紧凑）、存量迁移与 v1 / v2→v3 升级、分类标签分册、入口壳以 `references/conventions-spec.md` 为准。本文件只写流程。执行任何写操作前先读它们。
+任务文件规范（目录结构、命名、frontmatter、归档格式、手工归档步骤、自查清单）以 `references/task-spec.md` 为准；规范载体（conventions）的结构、形态标记与稳定 ID、归属判定、分层读写、内容修订（含作废三层清理）、表格紧凑形态以 `references/conventions-spec.md` 为准。本文件只写流程，细则按场景读取——写任务文件前读 `task-spec.md`；读写或修订规范载体前读 `conventions-spec.md`；涉存量迁移、形态升级时读 `conventions-migration.md`；落笔条文、模板或文风偏离时才读 `conventions-templates.md`。不涉对应场景不读。
 
 ## 核心规则
 
@@ -40,11 +40,20 @@ metadata:
 
 ## 工作流
 
+### 0. 任务分解与展示型计划表（方案确认后、建档前；两个及以上任务才出）
+
+- 先按任务粒度拆解：一个任务 = 可独立验收、可独立回滚、单独提交后仓库自洽的最小交付单元，且不跨仓库（判据、判定顺序与反例见 `references/task-spec.md` 协作约定）
+- 两个及以上任务时，在对话中给出唯一一张顺序计划表：列为「序号 | 仓库 | 任务 | 前置」，跨端、跨仓同表，按执行先后排列；单任务方案不出表
+- 表只作展示与排序：不落档、不写入任务正文、不设状态列（状态以任务 frontmatter 为唯一真源）；计划调整时先更新该表再继续
+- 串行先后写在展示表与各任务正文的「批次 / 计划位置 / 前置」行，不写 `depends_on`（`depends_on` 只用于仍 active 的并行依赖）
+
 ### 1. 动手前置：建档评估（先查后写的流程落点，所有仓库文件改动前必做，防漏建档/重复建档）
 
 - 无 `.tasks/` 任务区时先执行 `toolkit init` 建骨架（幂等，已存在不覆盖）
+- **逐仓逐任务建档**：本次方案涉及多个仓库时，每个将产生仓库文件改动的仓库按展示表的任务清单各自独立建档，全部建档后再改第一处文件；只读参与的仓库不建档
+- **触发建档的改动不含任务区自身**：`.tasks/` 下的读写不单独构成建档理由（避免建档本身成为改动依据、形成自证循环）；archive 同主题判别仍按下方「仓库文件改动口径」（任务区自身计入）
 - 列出任务目录 `active/` 下全部 `.md`（含一层 `{YYYYMM}/` 月份子目录），并核对 `archive/` 是否已有同主题任务
-- 读 conventions 载体（存在时）：先找 `.tasks/conventions/index.md`，不存在再看旧单文件 `.tasks/conventions.md`（兼容期读取，并在对话中提示可迁移）；常驻只读 `index.md`（`history.md` / `retired.md` 属归档面、各分册按需读），再按本任务 `scope` 命中加载端分册 / 分类标签分册并**恒叠加 `common`**（形态识别与分层读写判定见 `references/conventions-spec.md`）——载体也可能经项目级技能入口壳（如 `.agents/skills/toolkit-conventions/`）把 agent 引到此处；项目协作规范在建档与执行时须遵守；规范载体本身不属于任务，不为其建档
+- 读 conventions 载体（存在时）：常驻只读 `.tasks/conventions/index.md`，再按本任务 `scope` 加载端分册 / 分类标签分册并**恒叠加 `common`**；`history.md` / `retired.md` 属归档面、按需读；旧单文件 `.tasks/conventions.md` 兼容读取并提示可迁移（分层判定见 `references/conventions-spec.md`）。载体也可能经项目级技能入口壳（如 `.agents/skills/toolkit-conventions/`）引到此处；项目协作规范在建档与执行时须遵守；载体本身不属于任务，不为其建档
 - **同主题判别表**（建档前必须按此决策）：
   | 现状 | 本次是否产生仓库文件改动 | 处理 |
   | --- | --- | --- |
@@ -54,10 +63,10 @@ metadata:
   | active 无、archive 有 | 是（延续 / 扩展 / 重新实现） | **重新建档**，正文首行标注来源链 `延续 {原归档任务名}（见 archive/{YYYYMM}/{YYYYMMDD}.md）` |
   | active 无、archive 有 | 否，仅修正旧记录的时间/内容 | 走 fxri-session-recap 模式三（历史修正），**不是建档** |
   | active 与 archive 均无 | — | **建档后再动手**（硬前置，不建档不许改文件） |
-- **仓库文件改动口径**（客观判据，不靠感觉）：需写入版本控制的工作区文件的增 / 改 / 删（源码、配置、文档、技能、任务区自身均计入）；纯读取、纯执行、纯汇报不计入；拿不准 → 列出差异问用户，不猜
-- **动作不算，改动才算**：收尾动作（提交、发版、推送、部署）本身及其固有产物（版本号、更新日志、标签）不构成任务、不作为建档对象；这些动作过程中若出现需改仓库文件才能解决的缺陷（如打包配置错误、发布渠道错误），该修复按普通任务建档
-- **跨仓库改动各自归档（本仓自述）**：任务档是仓库自述，只记本仓的改动与动机；跨仓库是会话属性而非仓库属性，同一会话涉及多仓时各仓各自建档归档，不在一仓记录里承载另一仓的工作痕迹。判据取**视角**（描述的是不是本仓的改动与动机），非词表——依赖包名 / 被调接口名等属本仓事实者照写
-- **归档块不可变**：已归档块不追加新的工作内容（追加新工作内容会破坏完成时间/范围的可信度）；延续需求一律走新任务。唯一例外是**事实更正**：后续核实推翻原块结论、或协作口径变更导致历史事实字段需更正时，在其正文末尾追加「修订记录」（保留原结论、附更正时刻与依据）；口径变更类更正可改受影响的**事实字段**（如 `scope`），但唯一键 / 完成时间 / 状态 / 负责人仍冻结
+- **仓库文件改动口径**：需写入版本控制的工作区文件的增 / 改 / 删计入（源码、配置、文档、技能、任务区自身），纯读取 / 执行 / 汇报不计入；拿不准 → 列出差异问用户，不猜
+- **动作不算，改动才算**：提交、发版、推送、部署等收尾动作及其固有产物（版本号、更新日志、标签）不构成任务、不单独建档；过程中若出现需改仓库文件才能解决的缺陷（如打包 / 发布渠道配置错误），该修复按普通任务建档
+- **跨仓库改动各自归档（本仓自述）**：任务档只记本仓的改动与动机，同一会话涉及多仓时各仓各自建档归档；判据取**视角**（描述的是不是本仓的改动与动机），非词表——依赖包名 / 被调接口名等本仓事实照写
+- **归档块不可变**：已归档块不追加新的工作内容（否则破坏完成时间 / 范围的可信度），延续需求走新任务。唯一例外是**事实更正**：后续核实推翻原块结论、或协作口径变更导致历史事实字段需更正时，正文末尾追加「修订记录」（保留原结论、附更正时刻与依据），可改受影响的事实字段（如 `scope`），但唯一键 / 完成时间 / 状态 / 负责人仍冻结
 - 任务唯一键：`{YYYYMMDD}-{用户名}-{任务简述}`；多人对同一需求共用一个文件
 
 ### 2. 建档
@@ -91,13 +100,15 @@ metadata:
 - 变更已有规范语义时，先在 `history.md` 追加一行留痕，再更新索引行「当前语义」（细则见 `references/conventions-spec.md`）
 - **规则作废**：走「迁出 + 三层清理」——索引行删除并迁入 `retired.md`（冻结语义）、物理删除分册内该条小节、外部单一事实源同步删改；不把状态改个标记留在原位
 - 一次性决策不进规范，留在任务正文
-- **存量迁移与升级**：发现旧单文件 `conventions.md` 时按迁移三段式执行（建目录搬原文 → 逐条提归属建议 → 用户确认后拆分册）；载体为 v1 / v2 或 `check` / `toolkit conventions status` 报形态告警时，按 `references/conventions-spec.md` 的 v1 / v2→v3 链路升级（优先 `toolkit conventions upgrade`，可 `--dry-run` 预演）；均可中断不丢内容
+- **存量迁移与升级**：发现旧单文件 `conventions.md`，或载体为 v1 / v2、`check` / `toolkit conventions status` 报形态告警时，按 `references/conventions-migration.md` 的迁移与升级链路处置（可中断不丢内容）
 
 ### 6. 收尾边界（硬约束到沉淀）
 
 **归档 + 规范沉淀即本技能流程终点**（先归档、后沉淀）。提交、发版、推送不是必经步骤，是否执行取决于用户的全局 / 个人 / 项目规则；若提交代码，按「归档与沉淀 → 跑项目验收命令 → 提交」的顺序执行，任务归档文件与规范载体变更、代码变更落在**同一个 git 提交**（顺序不可颠倒），避免任务完成却滞留 `active/` 未归档，或归档单独成一条提交。
 
-⚠️ **验收须晚于归档**：归档会改写 `.tasks/`（写归档文件、删 active 源文件、清理空月份目录），而归档本身不做阻断式校验——早于归档跑验收就覆盖不到终态，归档产物等于无人校验。同理，归档块「完成情况」只记改动事实与所用验证命令，不逐条抄写验收输出。
+**逐任务交付**：按展示表顺序推进，前置未完成或阻塞未解除时下游不开工；每个任务完成即走完本仓的「归档 → 验收 → 提交」再进入下一个，不跨任务攒批（一个任务至少一次提交、允许多次；不得混入无关改动）。
+
+⚠️ **验收须晚于归档**：归档会改写 `.tasks/`（写归档文件、删 active 源文件、清理空月份目录），而归档本身不做阻断式校验——早于归档跑验收就覆盖不到终态。同理，归档块「完成情况」只记改动事实与所用验证命令，不抄验收输出。
 
 ## 失败模式
 
@@ -106,18 +117,21 @@ metadata:
 | active 下出现同名任务文件 | 重复建档，合并为一个后删除多余 |
 | completed 日期与文件名创建日不一致 | 核对是否填错；确为跨天完成则以 completed 日期归档 |
 | depends_on 引用的任务已归档 | 正常，依赖随之解除；引用拼写错误则修正 |
-| 并发写归档文件互相覆盖 | 归档前确认无其他写者同时操作；多人同天归档 `pull` 后归档文件残留 git 冲突标记时，跑 `toolkit tasks normalize --fix` 按并集去重 + 完成时间降序**确定性**解决（保留两侧任务块、丢弃 diff3 的 `\|\|\|\|\|\|\|` base 段与全部标记行） |
+| 并发写归档文件互相覆盖 | 归档前确认无其他写者同时操作；多人同天归档 `pull` 后残留 git 冲突标记时，跑 `toolkit tasks normalize --fix` 按并集去重 + 完成时间降序**确定性**解决（保留两侧任务块、丢弃 diff3 base 段与全部标记行） |
 | completed 填了收尾时刻而非真实完成时刻 | 按四级时间源重新取证（git log / 聊天记录时间戳） |
+| 一个方案只建了一个任务档，其余任务无记录 | 按展示表的任务清单逐仓逐任务补建，再继续执行 |
+| 下游任务先于上游开工 | 以展示表顺序为准，前置未完成或阻塞未解除时暂停下游，先解除阻塞 |
+| 把展示型计划表写进任务正文或 `.tasks/` | 计划表只在对话展示、不落档；任务正文只保留「批次 / 计划位置 / 前置」一行 |
 
 ## 可选加速（不构成依赖）
 
-⚠️ 工具探测顺序（先项目内、后全局）：先 `pnpm exec toolkit --help`（项目 devDependency，npm 项目等价 `npx toolkit`），失败再 `toolkit --help`（全局安装）；两者都不可用即工具未安装，按各步手工继续，**不安装、不阻塞**。探测成功后用对应前缀执行下列命令：
+⚠️ 先项目内后全局探测：`pnpm exec toolkit --help`（npm 项目用 `npx toolkit`）→ `toolkit --help`；都不可用即未安装，按各步手工继续，**不安装、不阻塞**。探测成功后用对应前缀执行：
 
-- `toolkit tasks`：查 active 总览（替代第 1 步人工翻目录）
+- `toolkit tasks`：active 总览（替代第 1 步翻目录）
 - `toolkit tasks check`：自动校验（替代第 4 步自查清单）
-- `toolkit tasks archive`：自动归档（替代第 5 步，含排他锁防并发；可 `--dry-run` 预演）
-- `toolkit tasks normalize`：归档后核验归档块（元数据完整性/日期漂移/排序/git 冲突标记），可 `--fix` 自动修复（含按并集去重 + 降序解决冲突标记）
-- `toolkit conventions status`：只读体检载体形态与入口壳现场（替代第 1 步人工判形态、第 5.5 步沉淀前后自查）
-- `toolkit conventions upgrade`：v1 / v2 → v3 结构升级（第 5.5 步，纯机械、幂等；可 `--dry-run` 预演）
-- `toolkit conventions format`：表格形态归一为紧凑形态（手工写表后自查；只动空白层与分隔行横线长度、不改语义；幂等、跳过代码块；可 `--dry-run` 预演）
+- `toolkit tasks archive`：自动归档（替代第 5 步，排他锁防并发；`--dry-run` 预演）
+- `toolkit tasks normalize`：归档后核验（元数据 / 日期漂移 / 排序 / 冲突标记），`--fix` 自动修复
+- `toolkit conventions status`：只读体检载体形态与入口壳（替代第 1 步判形态、第 5.5 步沉淀前后自查）
+- `toolkit conventions upgrade`：v1 / v2 → v3 升级（第 5.5 步，纯机械、幂等；`--dry-run` 预演）
+- `toolkit conventions format`：表格归一为紧凑形态（只动空白层、不改语义；幂等、跳过代码块；`--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-migration.md

@@ -0,0 +1,59 @@
+# 规范载体存量迁移
+
+> 本文件为 `conventions-spec.md` 的配套规范，承载载体存量的形态迁移（v0 → v1、v1 → v2、v2 → v3）。仅在迁移存量载体或排查形态异常时加载；日常结构、读写判定与自查见 `conventions-spec.md`。
+
+## 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 时原样返回，不做二次改写
+- 手动迁移时按同一动作序执行