@fxri/toolkit 1.9.5 → 1.10.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # 方弦工具集
 
+## 1.10.0
+
+> 2026-09-16 发布
+
+### ✨ 新增功能
+
+- 规范载体目录化与端分类——`.tasks/conventions.md` 单文件升级为 `.tasks/conventions/` 目录形态（`index.md` 唯一入口 + `common.md` 全端通用条文 + `<端名>.md` 各端专属条文，分册按需创建），端名与任务 `scope` 取值逐字一致、`index.md` 顶部端清单为端的唯一权威，读取分层为「常驻只读 index + 按 scope 命中加载分册与 common」
+- 存量迁移支持——旧单文件可整体搬为 `index.md` 后逐条给归属建议、用户确认后拆分册，迁移三段式可中断不丢内容；新旧形态兼容读，两者并存时以目录形态为准
+- 内容修订路径——旧条目过时走「演进记录留痕 + index 行更新 + 状态置 `已废弃`」，不删行
+
+### 🔧 功能调整
+
+- `toolkit init` 预生成 `conventions/index.md` 骨架（含端清单模板）；`toolkit tasks check` 在旧单文件残留或 `conventions/` 缺 `index.md` 时给软告警，即迁移入口
+
+### ⚡ 优化改进
+
+- fxri-plan-to-task 升级 1.2.0（写入归属判定 + 存量迁移触发）、fxri-session-recap 升级 1.2.0（R3 落点、读取分层、内容修订与形态迁移分流）、fxri-release-changelog 升级 1.0.12（发版流程补「润色后跑一次 `changelog --history format` 归一历史块」步骤与失败模式，references 补格式化不动点口径）
+
+### 📝 文档更新
+
+- 补迁移教程——guide 新增「存量规范载体迁移」节，handbook 新增「四、规范载体迁移」节，faq 新增迁移问答
+- 修正文档承诺未实现——guide 原称 conventions.md「两种形态 skill 均支持」，实际 SPEC.md / task-spec.md / 两个 SKILL.md 均无「形态」概念，已按实际能力改写
+
 ## 1.9.5
 
 > 2026-09-16 发布
@@ -42,7 +65,6 @@
   - `toolkit changelog version/format` 新增 `--history`：历史版本块内条目按其类型前缀与既有组标题归位、组标题转写为当前语言口径；无法识别的分组连同标题原样保留，不臆造归属（不加该选项时仍不动历史块）
   - 条目类型前缀表补充 `技能：` / `skills：`（归入「优化改进」）与 `依赖：`（归入「依赖变更」），历史组标题（如 `补丁修复`）也能识别归位
   - 修复 Windows 检出（`core.autocrlf`）下 `pnpm sync:changelog-doc` 因 CRLF 误判「未发现版本块」而中止
-
 - CHANGELOG 归类后剥离条目已识别的类型前缀
 
   - 条目归入语义分组后，已识别的 `类型：` 前缀被剥离（`- 修复：xxx` → `- xxx`），类型由分组标题承接，明细不再与之重复
@@ -65,7 +87,6 @@
   - 修正 README 与 docs 中 11 处跨页锚点死链（标题改名后未同步，点击不跳转），涉及 `README.md`、`docs/cli.md`、`docs/faq.md`、`docs/getting-started.md`、`docs/guide.md`、`docs/handbook.md`
   - 文档一致性测试的锚点用例此前会跳过全部跨页链接（VitePress 把 `.md` 渲染为 `.html` 后被扩展名判断排除），现归一回 `.md` 并按所在目录相对解析
   - 扫描范围由 `docs/*.md` 扩至仓库根 `*.md` 与 `skills/**/*.md`，跨页锚点写错、标题改名漏同步均会拦下
-
 - 修复 Windows 检出环境下文档一致性测试的换行误判
 
   - 「更新日志镜像」用例比较前统一把 CRLF 归一为 LF，Windows 检出（`core.autocrlf`）不再把换行差异误报成「漏跑同步脚本或手改镜像页」
@@ -88,7 +109,6 @@
   - 文档补齐：内置脱敏规则清单（`docs/config.md`、`docs/guide.md`）、`--redact` / `--warn` 的域级作用域与 `tasks` 域选项表（`docs/cli.md`）、站点导航与更新日志入口
   - skills 状态检查新增版本双写位比对（frontmatter `metadata.version` 与正文声明值），不一致时软告警
   - 新增机器化质量门测试：脱敏规则清单 ↔ 文档一致、`docs/*.md` 内锚点可解析、`docs/changelog.md` 与 `CHANGELOG.md` 一致、`CheckIssue.line` 行号定位
-
 - 降低任务区随年限增长的全库线性扫描与整文件重写开销
 
   - `tasks check`：依赖索引改惰性构建（active 无 `depends_on` 时不再扫全量归档），重名检测与依赖命中改 `Set`、命中即早退
@@ -108,7 +128,6 @@
   - `skills/README.md`：技能表补版本列（取自各 SKILL.md 的 frontmatter `metadata.version`）
   - `toolkit tasks stats --format` 补取值校验：非法值告警并置退出码 1，与其余命令同口径
   - `AGENTS.md`：规则层锚点纪律明确 `SPEC.md` 无 fenced 包裹、整篇即快照，锚点位于正文首行即合规
-
 - 规则层锚点由数字版本号改为更新时刻，提交信息规则拆为独立页
 
   - 锚点由 `> 规范版本 x.y` / `> 规则版本 x.y` 改为 `> 规范更新时间 YYYY-MM-DD HH:mm`（`SPEC.md`）与 `> 规则更新时间 YYYY-MM-DD HH:mm`（`docs/ai-rules.md`、`docs/commit-rules.md`）——两个规则页锚点位于 fenced 可复制块内部首行，`SPEC.md` 无 fenced 包裹、整篇文件即快照，锚点位于正文首行；复制过旧规则的快照首行格式不同即说明需重新复制对应页面
@@ -130,7 +149,6 @@
   - 自定义语言新增可选 `groups`（`[{ slot, title, prefixes? }]`）声明本语言标题与自有前缀；未声明时退化为纯替换，既有配置无需改动
   - ⚠️ 对外契约变化：`--lang en` 的组标题文本变化（如 `### ✨ Minor Changes` → `### ✨ Added`）；`--warn` / `FX_CHECK_WARN` / `check.warnings` 适用范围由任务校验告警扩为「任务校验告警 + 变更集条目缺类型前缀告警」，同一开关一并开关闭；新增公共导出 `SLOT_PREFIXES` / `SemanticSlot`
   - 修复：发布日期行识别由硬编码「发布/released」改为「当前语言 `released` ∪ 全部内置语言 `released`」后缀集合——自定义语言（日文等）按自身 `released` 识别，内置 zh / en 互跑（如中文日志用 `--lang en` 输出）也不再重复追加日期行
-
 - 技能版本可视化，旧会话可自校验技能内容是否过期
 
   - `toolkit skills status` 常驻打印包内各技能真源版本，`--format json` 新增 `skillVersions` 字段与逐项 `version`，作为磁盘基准值；`toolkit skills install` 报告同样逐项带版本

package/SPEC.md

@@ -1,6 +1,6 @@
 # 任务文件规范（SPEC）
 
-> 规范更新时间 2026-09-14 15:17。本规范内容变更时以变更时刻更新此值，实现方与规范快照据此对照是否失同步。
+> 规范更新时间 2026-09-16 09:52。本规范内容变更时以变更时刻更新此值，实现方与规范快照据此对照是否失同步。
 
 > 本规范**全语言支持**，面向**多人 + AI 跨项目协作**，定义任务文件的目录结构、文件格式与归档规则。任何编程语言均可按本规范实现读写；@fxri/toolkit 的 `tasks` 域仅为参考实现。
 >
@@ -12,7 +12,7 @@
 
 1. **先查后写**：新建、更新或归档任务前，先 `toolkit tasks` 查看 active 总览，并核对 archive 是否已有同主题任务；active 已有同主题任务则更新原文件，禁止重复建档。archive 已有同主题任务（已归档完成）时按增量判别：无增量（重复提议）不建档、有增量（延续/扩展）则重新建档并在正文首行标注来源链 `延续 {原归档任务名}（见 archive/{YYYYMM}/{YYYYMMDD}.md）`、仅修正旧记录错误走历史修正（fxri-session-recap 模式三）不建档。**归档任务不可变**：已归档块是终结记录，不追加新内容，延续需求一律走新任务。
 2. **任务唯一键**：`{年月日}-{用户名}-{任务简述}` 唯一标识一个任务；多人对同一需求不得各自建档，应共用同一文件。
-3. **收尾边界到沉淀**：强制约束到「归档 + 规范沉淀」为止——终结态任务归档后做任务级规范沉淀（写入 conventions.md），归档 + 沉淀即流程终点；提交、发版、推送不是必经步骤，是否执行取决于用户的全局 / 个人 / 项目规则。若提交代码，先归档与沉淀、后提交，任务记录与代码变更落在同一 git 提交。
+3. **收尾边界到沉淀**：强制约束到「归档 + 规范沉淀」为止——终结态任务归档后做任务级规范沉淀（写入 conventions 载体），归档 + 沉淀即流程终点；提交、发版、推送不是必经步骤，是否执行取决于用户的全局 / 个人 / 项目规则。若提交代码，先归档与沉淀、后提交，任务记录与代码变更落在同一 git 提交。
 4. **可执行项必须落地为任务**：方案正文里的「待办 / 待实施 / 待核对」等子项，应拆分为独立 active 任务，不留游离待办；`toolkit tasks check` 会扫描此类未闭合标记。
 
 ## 1. 目录结构
@@ -25,10 +25,13 @@
 ├── archive/                   # 任务归档（已完成）
 │   └── {年月}/
 │       └── {年月日}.md        # 某天归档
-└── conventions.md             # 项目协作规范（可选）：从任务提炼的规范沉淀地，非任务文件
+└── conventions/               # 项目协作规范载体（可选）：从任务提炼的规范沉淀地，非任务文件
+    ├── index.md               # 唯一入口与唯一权威：端清单 + 每条规范一行指针
+    ├── common.md              # 全端通用条文（按需创建）
+    └── {端名}.md              # 各端专有条文，端名 = 任务 scope 取值（按需创建）
 ```
 
-`conventions.md` 由 AI 协作流程（fxri-plan-to-task 归档时 / fxri-session-recap 收尾时）维护，写入前需用户确认；tasks 命令不读取它、check 不因它告警。
+`conventions/` 由 AI 协作流程（fxri-plan-to-task 归档时 / fxri-session-recap 收尾时）维护，写入前需用户确认；tasks 命令不读其内容、check 不因内容告警（仅在载体形态异常时软告警）。端名与任务 `scope` 取值共用同一套词表、逐字一致，`index.md` 顶端的端清单是端的唯一权威（不扫目录）；分册按需创建，判据是「该归属下有无需独立承载的条文」。旧版单文件 `conventions.md` 兼容读取，检测到残留时软告警提示迁移。
 
 ## 2. active 任务文件