@fxri/toolkit 1.11.8 → 1.12.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # 方弦工具集
 
+## 1.12.0
+
+> 2026-10-16 发布
+
+### ✨ 新增功能
+
+- 规范载体升 v3——`.tasks/conventions/` 按读面拆「常驻索引 / 按需分册 / 归档」三分区，新增 `retired.md` 退休台账承载作废条目（冻结退休时语义并记录后继与条文去向），条目作废走三层清理（索引行迁出、分册小节物理删除、外部单一事实源同步收敛），从源头抑制常驻读面的规范膨胀
+  新增：`toolkit conventions upgrade` 支持 v1 / v2 → v3 链式升级——v2 升级自动删除索引表「状态」「确立来源任务」两列、把作废条目迁入 `retired.md` 并物理删除分册对应小节，`--dry-run` 可预演
+  新增：载体支持分类标签分册（如 `build.md` 等非端分册），归属取已存在的分册名即合法
+  修改：`toolkit conventions status` 新增校验——退休台账可定位性、退休 ID 与活跃 ID 重叠、common 归属却语义提及端名
+  修改：任务 `scope` 字段校验新增路径分隔符软告警（`/` 与 `\`）
+  优化：跨平台兼容补强——新增 macOS CI job、统一路径大小写归一口径（覆盖 macOS）、补 `.gitattributes` 统一换行符
+  修复：`toolkit conventions upgrade` 与 `status` 判定稳定 ID 时容忍行内代码包裹（`` `C-4` `` 不再误判为「首列仍为规则名」「不合稳定 ID 形态」）——对齐规范「引用一律行内代码包裹」的合法写法
+  修复：`toolkit conventions status` 的 common 下沉提示改为大小写不敏感、判据收窄为「语义含端限定语（仅 / 只 / 专属 / 适用于）且提及端名」，消除举例式提及的假阳性并补上大写端名的漏报
+  修改：`toolkit conventions upgrade` 新增 `index.md` 正文 v2 措辞复核——表外自由文本残留「确立来源任务」「状态改为已废弃」等表述时列入 `reviews`（只报不改）
+  修改：`toolkit tasks check` 与 `toolkit conventions status` 新增演进记录首列形态校验——v3 载体的 `history.md` 数据行首列须记为行内代码包裹的稳定 ID `C-<n>`，检出规则名等非 ID 首列时软告警（只报不改，历史行只追加故补齐须人工确认）
+  修改：规范载体三表表头统一为稳定 ID `ID`——索引表（`| ID | 规则 | 当前语义 | 归属 | 单一事实源 |`）、`history.md`（`| ID | 修订内容 | 修订来源任务 |`）、`retired.md` 首格同归一；表头与分隔行由列名常量单源派生，杜绝列集合形态漂移
+  修复：`toolkit init` 生成的 `conventions/index.md` 骨架此前残留 v2 列结构，改为按 v3 五列生成
+  修改：`toolkit conventions upgrade` 的 v2→v3 升级新增 `history.md` 表头首格归一为稳定 ID `ID`
+  修改：`toolkit tasks check` 与 `toolkit conventions status` 新增表形态速检——v3 载体索引表残留 v2 独有列（「状态」「确立来源任务」）或 `history.md` / `retired.md` 表头首格非 `ID` 时软告警（只报不改）
+  修改：表形态校验从「速检」升级为完整比对——v3 索引表列集合须恰为 `ID | 规则 | 当前语义 | 归属 | 单一事实源` 五列（列名与次序逐格一致，多列 / 少列 / 换序均检出）、`history.md` / `retired.md` 表头整行逐格比对、载体各文件（`index.md`、分册、`history.md`、`retired.md`）表头行与紧随分隔行列数须相等（跳过 fenced code block）；检出统一为软告警（只报不改，须人工确认后按规范归一）
+  文档：`conventions-spec` 补齐形态与迁移措辞——索引表五列固定、`history.md` / `retired.md` 表头固定逐格一致、表列数自洽、入口壳版本沿革（壳标记独立演进、当前 `v2`、从未有过 `v1` 壳）、不得显式书写 `v1` 标记、手工迁 v2 与 `toolkit conventions upgrade` 链式直达 v3 的落点差异
+  新增：`conventions-spec` 新增 §13「载体文风与模板」（T1–T6）——索引头注固定两行、用法说明固定「载体形态 → 本项目约定（可选）→ 读写与维护」三段骨架、「单一事实源」列按载体内 / 外二分写法（载体分册用相对链接、载体外文件用行内代码）、分册条文固定「要求 → 反例 → 理由 → 配套」四子项且不写「确立来源」、规范词按 `须` / `应` / `可` / `不得` 分级、标识符与路径一律行内代码
+  修改：`toolkit tasks check` 与 `toolkit conventions status` 新增分册残留「确立来源」子项检测——v3 载体的分册（`index.md` 除外）内出现行首「确立来源」子项时软告警（跳过 fenced code block、只报不改）
+  修改：`conventions-spec` 补齐演进记录措辞规则——§3.2 规定「修订内容」列只记该条自身语义（新立条目直接写其语义、语义变更写「旧语义」→「新语义」），禁自指套话（如「（本次起入表）」「新立条目：」）与重复 `index.md` 索引列的条文去向（如「条文全文落 X」，违反不变量 I4），并确立「措辞归一例外」（属 §9 同类的措辞层归一可原地改写旧行、不入留痕）；§8 补新立条目写法、§12 自查清单同步新增一项
+  修改：`toolkit tasks check` 与 `toolkit conventions status` 新增演进记录「修订内容」列禁用语料检测——v3 载体的 `history.md` 该列出现自指套话或重复索引列的条文去向时软告警（报首个命中行与「另有 N 处」、只报不改，改写须人工确认）
+  修改：`toolkit init` / `toolkit conventions upgrade` 写入 `history.md` 的元规则引语同步为「修订内容新立条目直接写其语义、语义变更写『旧语义』→『新语义』」，与 `conventions-spec` §3.2 模板同源
+  修改：规范载体文风模板（§13）微调——T6 中英文混排空格由硬性要求放宽为随仓库既有排版习惯；样板与索引内引用的 skill 路径由短名改为完整路径（样板处用 `skills/<技能名>/references/…` 占位）；检测实现注释里的表形态检测代号由 `T1–T5` 收敛为 `S1–S5`，与文风模板编号 `T1–T6` 区分（仅注释，无行为变化）
+
 ## 1.11.8
 
 > 2026-10-08 发布

package/SPEC.md

@@ -1,128 +1,129 @@
-# 任务文件规范（SPEC）
-
-> 规范更新时间 2026-10-08 00:15。本规范内容变更时以变更时刻更新此值，实现方与规范快照据此对照是否失同步。
-
-> 本规范**全语言支持**，面向**多人 + AI 跨项目协作**，定义任务文件的目录结构、文件格式与归档规则。任何编程语言均可按本规范实现读写；@fxri/toolkit 的 `tasks` 域仅为参考实现。
->
-> 本文件是规范内容的**单一事实源**；派生载体有文档站 [完整攻略 · 任务文件规范](https://fxri-net.github.io/toolkit/guide.html#任务文件规范)（供交互式阅读与逐条校验）与技能包 `task-spec.md`（面向非 toolkit 项目的通用裁剪版），与本文件冲突时一律以本文件为准。
-
-## 0. 协作模型
-
-任务区是**多写者共享**的：同一 `.tasks/` 可能被多人或多个 AI 参与。为避免互相覆盖，归档、归一化修复等工具内部写操作以排他锁（`.archive.lock`）防并发覆盖；人 / AI 的直接编辑遵循「先查后写」约定。约定：
-
-1. **先查后写**：新建、更新或归档任务前，先 `toolkit tasks` 查看 active 总览，并核对 archive 是否已有同主题任务；active 已有同主题任务则更新原文件，禁止重复建档；已分叉成不同范围时问用户（拆新任务 or 合并更新）。archive 已有同主题任务（已归档完成）时按**改动判别**：本次不产生仓库文件改动（重复提议 / 重复执行）则不重复建档，仅提示「同主题任务已归档于 {日期}」；本次产生仓库文件改动（延续 / 扩展 / 重新实现）则重新建档，并在正文首行标注来源链 `延续 {原归档任务名}（见 archive/{YYYYMM}/{YYYYMMDD}.md）`；仅修正旧记录的时间或内容走历史修正（fxri-session-recap 模式三），不建档。**仓库文件改动口径**：需写入版本控制的工作区文件的增 / 改 / 删（源码、配置、文档、技能、任务区自身均计入），纯读取、纯执行、纯汇报不计入；拿不准时列出差异问用户，不猜。**归档块不可变**：已归档块不追加新的工作内容，延续需求一律走新任务；唯一例外是**事实更正**——后续核实推翻原块结论、或协作口径变更导致历史事实字段需更正时，在其正文末尾追加「修订记录」（保留原结论、附更正时刻与依据）；口径变更类更正可改受影响的**事实字段**（如 `scope`），但唯一键 / 完成时间 / 状态 / 负责人仍冻结。
-2. **任务唯一键**：`{YYYYMMDD}-{用户名}-{任务简述}` 唯一标识一个任务；多人对同一需求不得各自建档，应共用同一文件。
-3. **收尾边界到沉淀**：强制约束到「归档 + 规范沉淀」为止——终结态任务归档后做任务级规范沉淀（写入 conventions 载体），归档 + 沉淀即流程终点；提交、发版、推送不是必经步骤，是否执行取决于用户的全局 / 个人 / 项目规则。**动作不算，改动才算**：任务 = 已确认的方案 + 它落地的仓库文件改动；收尾动作（提交、发版、推送、部署）本身及其固有产物（版本号、更新日志、标签）不构成任务、不单独建档，但当这些动作过程中出现需改仓库文件才能解决的缺陷（如打包配置错误、发布渠道错误）时，该修复按普通任务建档。若提交代码，先归档与沉淀、后提交，任务记录与代码变更落在同一 git 提交。
-4. **可执行项必须落地为任务**：方案正文里的「待办 / 待实施 / 待核对」等子项，应拆分为独立 active 任务，不留游离待办；`toolkit tasks check` 会扫描此类未闭合标记。
-5. **跨仓库改动各自归档**：任务档是**仓库自述**，只记本仓的改动与动机；跨仓库是**会话属性而非仓库属性**，同一会话涉及多仓时各仓各自建档归档，不在一仓记录里承载另一仓的工作痕迹。判据取**视角**（描述的是不是本仓的改动与动机），非词表——依赖包名 / 被调接口名等属本仓事实者照写。故 `scope` 只标本仓内的端 / 面（见第 2 节）。通用裁剪版见技能包 `task-spec.md`。
-
-## 1. 目录结构
-
-```
-.tasks/
-├── active/                    # 实时任务（未完成）
-│   └── {YYYYMM}/              # 按月分目录，如 202609
-│       └── {YYYYMMDD}-{用户名}-{任务简述}.md
-├── archive/                   # 任务归档（已完成）
-│   └── {YYYYMM}/
-│       └── {YYYYMMDD}.md      # 某天归档
-└── conventions/               # 项目协作规范载体（可选）：从任务提炼的规范沉淀地，非任务文件
-    ├── index.md               # 唯一入口与唯一权威（常驻读）：首行为形态标记；端清单 + 每条规范一行指针（首列为稳定 ID）
-    ├── history.md             # 规范演进记录（只追加、不改旧行；按需读）
-    ├── common.md              # 全端通用条文（按需创建）
-    └── {端名}.md              # 各端专有条文，端名 = 任务 scope 取值（按需创建）
-```
-
-`conventions/` 由 AI 协作流程（fxri-plan-to-task 归档时 / fxri-session-recap 收尾时）维护，写入前需用户确认；tasks 命令不读其内容、check 不因内容告警（仅在载体形态异常时软告警）。载体结构分两版：v1（无首行形态标记、索引表首列为序号 `#`、演进记录与索引同文件）与 v2（首行形态标记、索引表首列改为稳定 ID `C-<n>`、演进记录抽独立 `history.md`），v1 存量可用 `toolkit conventions upgrade` 升 v2。端名与任务 `scope` 取值共用同一套词表、逐字一致，`index.md` 顶端的端清单是端的唯一权威（不扫目录）；分册按需创建，判据是「该归属下有无需独立承载的条文」。旧版单文件 `conventions.md` 兼容读取，检测到残留时软告警提示迁移。
-
-## 2. active 任务文件
-
-### 2.1 命名
-
-`{YYYYMMDD}-{用户名}-{任务简述}.md`，示例 `20260902-唐启云-忘记密码.md`
-
-- `YYYYMMDD` = 任务创建日，直接拼接（不加 `-`）
-- `用户名` = git 用户名
-- `任务简述` = 简短短语（不加空格；建议团队统一语言）
-
-### 2.2 内容
-
-文件顶部为 frontmatter（两行 `---` 包裹的 YAML 键值块），随后为正文。
-
-```markdown
----
-owner: 唐启云
-status: 进行中
-created: 20260902
-updated: 20260902
-completed: ''
-depends_on: []
-scope: app
----
-
-# 任务标题
-```
-
-| 字段 | 类型 | 说明 |
-| --- | --- | --- |
-| owner | string | 负责人（git 用户名）；缺失时 `check` 软告警 |
-| status | enum | `待办` / `进行中` / `已完成` / `阻塞` / `已放弃` |
-| created | string | 创建日 `YYYYMMDD`，应等于文件名日期前缀；缺失/不一致/格式错误时 `check` 软告警 |
-| updated | string | 更新日 `YYYYMMDD` |
-| completed | string | 完成时间 `YYYY-MM-DD HH:mm`，`status` 为 `已完成`/`已放弃` 时必填；按四级时间源取证：当场打点（任务完成时取真实时间，首选）/ 聊天记录准确时间戳 / 任务改动 git 提交时间 / 系统当前时间兜底（须标注「收尾补记」）；纯日期写法（`YYYY-MM-DD`）会被补齐 `00:00`，仅日期未补全完整时间会软告警 |
-| depends_on | array | 依赖任务文件名，引用可带 `.md` 扩展名（校验时自动归一为不含扩展名的 basename） |
-| scope | string | 影响范围；只标本仓内的端 / 面（跨仓库改造时不含另一仓），一任务多归属时以半角加号分隔（如 `web+server`），标签内不使用加号，顿号/逗号列表写法会被 check 软告警、`normalize --fix` 自动归一 |
-
-## 3. archive 归档文件
-
-### 3.1 命名
-
-`{YYYYMMDD}.md`，按任务**完成时间**的日期划分。
-
-### 3.2 内容
-
-同一天完成的任务整合进同一文件，**按完成时间降序排序**（最新在前），任务之间用 `---` 分隔。每个任务块必须含**元数据行**（`> ` 开头，四字段：负责人 / 状态 / 范围 / 完成时间），缺失或不完整时可由 `toolkit tasks normalize --fix` 补齐：
-
-```markdown
-# 20260902 归档
-
-## 20260902-唐启云-忘记密码
-
-> 负责人：唐启云　状态：已完成　范围：app　完成时间：2026-09-02 14:30
-
-# 忘记密码
-（正文）
-
----
-
-## 20260902-唐启云-其他任务
-
-> 负责人：唐启云　状态：已完成　范围：-　完成时间：2026-09-02 15:00
-
-（正文）
-```
-
-## 4. 归档规则
-
-1. 归档触发是**人工 / 事件驱动**，非定时任务；常见触发时机为任务完成、相关变更提交版本控制之前，此时应先行归档再提交。
-2. **任务级归档**：`status ∈ {已完成, 已放弃}` 且带 `completed` 的任务可归档。
-3. `待办` / `进行中` / `阻塞` 均不归档。
-4. 归档文件按 `completed` 的日期（`YYYYMMDD`）划分。
-5. 归档文件内任务按 `completed` **降序**排序（最新在前，`YYYY-MM-DD HH:mm` 定宽字符串比较即时间序）。
-6. **完成时间口径**：`completed` 只填真实收工时间（四级时间源取证），日期应与归档文件日期一致；不一致属「日期漂移」，`toolkit tasks normalize` 会检出，`--fix` 自动把漂移块迁移到对应日期文件（迁移前可用 `normalize` 只读检查）；归档文件放错月份目录（如 `archive/202608/20260903.md`）时 `--fix` 会将其移动到正确月份目录。⚠️ 补档 / 历史时间修正场景下，归档块的完成时间早于归档动作时间是正常的——修正块时间后执行 `normalize --fix` 即完成迁移。
-7. **任务块边界与疑似任务块**：任务块边界以块间 `---` 分隔符为唯一权威边界，`## 标题` 与 `> 元数据` 行仅作校验项（缺失或不全时仍解析为块，由 `normalize` 检出并提示）；正文内部形如 `{YYYYMMDD}-{负责人}-{简述}` 的 `## ` 标题会被视为疑似任务块并在 `normalize` 检出提示人工确认（不自动修复）。
-8. **并发归档防护**：归档采用排他锁（`.archive.lock`），检测到并发归档时跳过并告警；`--dry-run` 可预演归档动作而不落盘。锁须具备自愈语义——持有进程已退出，或锁龄超过实现约定的绝对上限（兜底 pid 复用导致的「假存活」）时，后续写操作接管该锁而非永久阻塞；正常的并发写者仍按跳过处理。
-9. **冲突标记归一（多写者同天归档）**：多人同日归档时，`pull` 可能在按完成日期聚合的归档文件上留下 git 冲突标记；`toolkit tasks normalize` 检出此类标记，`--fix` 按并集去重 + 完成时间降序**确定性**解决——保留冲突两侧任务块、丢弃 diff3 风格的 `|||||||` base 段与全部标记行，无需人工逐块合并。
-
-## 5. 其他语言实现要点
-
-按本规范实现时，需覆盖：
-
-1. **frontmatter 解析**：读取文件顶部 `---` 之间的 `key: value` 行。
-2. **目录遍历**：`active/` 下仅一层年月子目录，收集 `.md` 文件。
-3. **完成时间提取**：从 frontmatter 的 `completed` 字段读取。
-4. **归档合并**：读取已有归档文件的任务块，与新任务合并后按 `completed` 排序，重写归档文件。
-5. **任务块分隔**：归档文件内任务以块间 `---` 为唯一权威边界（`## 标题` 与 `> 元数据` 行仅作校验项），勿将正文内部的 `## ` 小节误判为任务边界。
-6. **敏感信息脱敏（可选）**：如需保护隐私，可在写归档前对正文自由文本做掩码；`owner` 等结构化字段保留原值。
-7. **校验（check）**：校验 active 任务 frontmatter 合法性（status 枚举、completed 必填与格式）、跨文件重名、`depends_on` 依赖存在性与成环、范围字段形态软告警（顿号/逗号/括号）。
-8. **归一化（normalize）**：校验归档块元数据四字段完整性、完成时间与归档日期一致性、降序排序、范围字段形态（顿号/逗号疑似多值分隔可 `--fix` 归一为半角加号，括号疑似注释仅提示人工）、git 冲突标记（多写者同天归档的 `pull` 冲突可 `--fix` 按并集去重 + 降序确定性解决）；`--fix` 可补齐缺失元数据并重排。
+# 任务文件规范（SPEC）
+
+> 规范更新时间 2026-10-16 16:57。本规范内容变更时以变更时刻更新此值，实现方与规范快照据此对照是否失同步。
+
+> 本规范**全语言支持**，面向**多人 + AI 跨项目协作**，定义任务文件的目录结构、文件格式与归档规则。任何编程语言均可按本规范实现读写；@fxri/toolkit 的 `tasks` 域仅为参考实现。
+>
+> 本文件是规范内容的**单一事实源**；派生载体有文档站 [完整攻略 · 任务文件规范](https://fxri-net.github.io/toolkit/guide.html#任务文件规范)（供交互式阅读与逐条校验）与技能包 `task-spec.md`（面向非 toolkit 项目的通用裁剪版），与本文件冲突时一律以本文件为准。
+
+## 0. 协作模型
+
+任务区是**多写者共享**的：同一 `.tasks/` 可能被多人或多个 AI 参与。为避免互相覆盖，归档、归一化修复等工具内部写操作以排他锁（`.archive.lock`）防并发覆盖；人 / AI 的直接编辑遵循「先查后写」约定。约定：
+
+1. **先查后写**：新建、更新或归档任务前，先 `toolkit tasks` 查看 active 总览，并核对 archive 是否已有同主题任务；active 已有同主题任务则更新原文件，禁止重复建档；已分叉成不同范围时问用户（拆新任务 or 合并更新）。archive 已有同主题任务（已归档完成）时按**改动判别**：本次不产生仓库文件改动（重复提议 / 重复执行）则不重复建档，仅提示「同主题任务已归档于 {日期}」；本次产生仓库文件改动（延续 / 扩展 / 重新实现）则重新建档，并在正文首行标注来源链 `延续 {原归档任务名}（见 archive/{YYYYMM}/{YYYYMMDD}.md）`；仅修正旧记录的时间或内容走历史修正（fxri-session-recap 模式三），不建档。**仓库文件改动口径**：需写入版本控制的工作区文件的增 / 改 / 删（源码、配置、文档、技能、任务区自身均计入），纯读取、纯执行、纯汇报不计入；拿不准时列出差异问用户，不猜。**归档块不可变**：已归档块不追加新的工作内容，延续需求一律走新任务；唯一例外是**事实更正**——后续核实推翻原块结论、或协作口径变更导致历史事实字段需更正时，在其正文末尾追加「修订记录」（保留原结论、附更正时刻与依据）；口径变更类更正可改受影响的**事实字段**（如 `scope`），但唯一键 / 完成时间 / 状态 / 负责人仍冻结。
+2. **任务唯一键**：`{YYYYMMDD}-{用户名}-{任务简述}` 唯一标识一个任务；多人对同一需求不得各自建档，应共用同一文件。
+3. **收尾边界到沉淀**：强制约束到「归档 + 规范沉淀」为止——终结态任务归档后做任务级规范沉淀（写入 conventions 载体），归档 + 沉淀即流程终点；提交、发版、推送不是必经步骤，是否执行取决于用户的全局 / 个人 / 项目规则。**动作不算，改动才算**：任务 = 已确认的方案 + 它落地的仓库文件改动；收尾动作（提交、发版、推送、部署）本身及其固有产物（版本号、更新日志、标签）不构成任务、不单独建档，但当这些动作过程中出现需改仓库文件才能解决的缺陷（如打包配置错误、发布渠道错误）时，该修复按普通任务建档。若提交代码，先归档与沉淀、后提交，任务记录与代码变更落在同一 git 提交。
+4. **可执行项必须落地为任务**：方案正文里的「待办 / 待实施 / 待核对」等子项，应拆分为独立 active 任务，不留游离待办；`toolkit tasks check` 会扫描此类未闭合标记。
+5. **跨仓库改动各自归档**：任务档是**仓库自述**，只记本仓的改动与动机；跨仓库是**会话属性而非仓库属性**，同一会话涉及多仓时各仓各自建档归档，不在一仓记录里承载另一仓的工作痕迹。判据取**视角**（描述的是不是本仓的改动与动机），非词表——依赖包名 / 被调接口名等属本仓事实者照写。故 `scope` 只标本仓内的端 / 面（见第 2 节）。通用裁剪版见技能包 `task-spec.md`。
+
+## 1. 目录结构
+
+```
+.tasks/
+├── active/                    # 实时任务（未完成）
+│   └── {YYYYMM}/              # 按月分目录，如 202609
+│       └── {YYYYMMDD}-{用户名}-{任务简述}.md
+├── archive/                   # 任务归档（已完成）
+│   └── {YYYYMM}/
+│       └── {YYYYMMDD}.md      # 某天归档
+└── conventions/               # 项目协作规范载体（可选）：从任务提炼的规范沉淀地，非任务文件
+    ├── index.md               # 唯一入口与唯一权威（常驻读）：首行为形态标记；端清单 + 每条规范一行指针（首列为稳定 ID）
+    ├── history.md             # 规范演进记录（只追加、不改旧行；按需读）
+    ├── retired.md             # 退休台账：已作废规范的冻结语义（按需创建；属归档面、按需读）
+    ├── common.md              # 全端通用条文（按需创建）
+    └── {端名}.md              # 各端专有条文，端名 = 任务 scope 取值（按需创建）
+```
+
+`conventions/` 由 AI 协作流程（fxri-plan-to-task 归档时 / fxri-session-recap 收尾时）维护，写入前需用户确认；tasks 命令不读其内容、check 不因内容告警（仅在载体形态异常时软告警）。载体结构分三版：v1（无首行形态标记、索引表首列为序号 `#`、演进记录与索引同文件）、v2（首行标记 `v2`、索引表首列改稳定 ID `C-<n>`、演进记录抽独立 `history.md`、索引表含「状态」「确立来源任务」两列）与 v3（首行标记 `v3`、索引表为 `ID | 规则 | 当前语义 | 归属 | 单一事实源` 五列、退休条目迁入 `retired.md`），v1 / v2 存量可用 `toolkit conventions upgrade` 升 v3。端名与任务 `scope` 取值共用同一套词表、逐字一致，`index.md` 顶端的端清单是端的唯一权威（不扫目录）；分册按需创建，判据是「该归属下有无需独立承载的条文」。旧版单文件 `conventions.md` 兼容读取，检测到残留时软告警提示迁移。
+
+## 2. active 任务文件
+
+### 2.1 命名
+
+`{YYYYMMDD}-{用户名}-{任务简述}.md`，示例 `20260902-唐启云-忘记密码.md`
+
+- `YYYYMMDD` = 任务创建日，直接拼接（不加 `-`）
+- `用户名` = git 用户名
+- `任务简述` = 简短短语（不加空格；建议团队统一语言）
+
+### 2.2 内容
+
+文件顶部为 frontmatter（两行 `---` 包裹的 YAML 键值块），随后为正文。
+
+```markdown
+---
+owner: 唐启云
+status: 进行中
+created: 20260902
+updated: 20260902
+completed: ''
+depends_on: []
+scope: app
+---
+
+# 任务标题
+```
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| owner | string | 负责人（git 用户名）；缺失时 `check` 软告警 |
+| status | enum | `待办` / `进行中` / `已完成` / `阻塞` / `已放弃` |
+| created | string | 创建日 `YYYYMMDD`，应等于文件名日期前缀；缺失/不一致/格式错误时 `check` 软告警 |
+| updated | string | 更新日 `YYYYMMDD` |
+| completed | string | 完成时间 `YYYY-MM-DD HH:mm`，`status` 为 `已完成`/`已放弃` 时必填；按四级时间源取证：当场打点（任务完成时取真实时间，首选）/ 聊天记录准确时间戳 / 任务改动 git 提交时间 / 系统当前时间兜底（须标注「收尾补记」）；纯日期写法（`YYYY-MM-DD`）会被补齐 `00:00`，仅日期未补全完整时间会软告警 |
+| depends_on | array | 依赖任务文件名，引用可带 `.md` 扩展名（校验时自动归一为不含扩展名的 basename） |
+| scope | string | 影响范围；只标本仓内的端 / 面（跨仓库改造时不含另一仓），一任务多归属时以半角加号分隔（如 `web+server`），标签内不使用加号，顿号/逗号列表写法会被 check 软告警、`normalize --fix` 自动归一 |
+
+## 3. archive 归档文件
+
+### 3.1 命名
+
+`{YYYYMMDD}.md`，按任务**完成时间**的日期划分。
+
+### 3.2 内容
+
+同一天完成的任务整合进同一文件，**按完成时间降序排序**（最新在前），任务之间用 `---` 分隔。每个任务块必须含**元数据行**（`> ` 开头，四字段：负责人 / 状态 / 范围 / 完成时间），缺失或不完整时可由 `toolkit tasks normalize --fix` 补齐：
+
+```markdown
+# 20260902 归档
+
+## 20260902-唐启云-忘记密码
+
+> 负责人：唐启云　状态：已完成　范围：app　完成时间：2026-09-02 14:30
+
+# 忘记密码
+（正文）
+
+---
+
+## 20260902-唐启云-其他任务
+
+> 负责人：唐启云　状态：已完成　范围：-　完成时间：2026-09-02 15:00
+
+（正文）
+```
+
+## 4. 归档规则
+
+1. 归档触发是**人工 / 事件驱动**，非定时任务；常见触发时机为任务完成、相关变更提交版本控制之前，此时应先行归档再提交。
+2. **任务级归档**：`status ∈ {已完成, 已放弃}` 且带 `completed` 的任务可归档。
+3. `待办` / `进行中` / `阻塞` 均不归档。
+4. 归档文件按 `completed` 的日期（`YYYYMMDD`）划分。
+5. 归档文件内任务按 `completed` **降序**排序（最新在前，`YYYY-MM-DD HH:mm` 定宽字符串比较即时间序）。
+6. **完成时间口径**：`completed` 只填真实收工时间（四级时间源取证），日期应与归档文件日期一致；不一致属「日期漂移」，`toolkit tasks normalize` 会检出，`--fix` 自动把漂移块迁移到对应日期文件（迁移前可用 `normalize` 只读检查）；归档文件放错月份目录（如 `archive/202608/20260903.md`）时 `--fix` 会将其移动到正确月份目录。⚠️ 补档 / 历史时间修正场景下，归档块的完成时间早于归档动作时间是正常的——修正块时间后执行 `normalize --fix` 即完成迁移。
+7. **任务块边界与疑似任务块**：任务块边界以块间 `---` 分隔符为唯一权威边界，`## 标题` 与 `> 元数据` 行仅作校验项（缺失或不全时仍解析为块，由 `normalize` 检出并提示）；正文内部形如 `{YYYYMMDD}-{负责人}-{简述}` 的 `## ` 标题会被视为疑似任务块并在 `normalize` 检出提示人工确认（不自动修复）。
+8. **并发归档防护**：归档采用排他锁（`.archive.lock`），检测到并发归档时跳过并告警；`--dry-run` 可预演归档动作而不落盘。锁须具备自愈语义——持有进程已退出，或锁龄超过实现约定的绝对上限（兜底 pid 复用导致的「假存活」）时，后续写操作接管该锁而非永久阻塞；正常的并发写者仍按跳过处理。
+9. **冲突标记归一（多写者同天归档）**：多人同日归档时，`pull` 可能在按完成日期聚合的归档文件上留下 git 冲突标记；`toolkit tasks normalize` 检出此类标记，`--fix` 按并集去重 + 完成时间降序**确定性**解决——保留冲突两侧任务块、丢弃 diff3 风格的 `|||||||` base 段与全部标记行，无需人工逐块合并。
+
+## 5. 其他语言实现要点
+
+按本规范实现时，需覆盖：
+
+1. **frontmatter 解析**：读取文件顶部 `---` 之间的 `key: value` 行。
+2. **目录遍历**：`active/` 下仅一层年月子目录，收集 `.md` 文件。
+3. **完成时间提取**：从 frontmatter 的 `completed` 字段读取。
+4. **归档合并**：读取已有归档文件的任务块，与新任务合并后按 `completed` 排序，重写归档文件。
+5. **任务块分隔**：归档文件内任务以块间 `---` 为唯一权威边界（`## 标题` 与 `> 元数据` 行仅作校验项），勿将正文内部的 `## ` 小节误判为任务边界。
+6. **敏感信息脱敏（可选）**：如需保护隐私，可在写归档前对正文自由文本做掩码；`owner` 等结构化字段保留原值。
+7. **校验（check）**：校验 active 任务 frontmatter 合法性（status 枚举、completed 必填与格式）、跨文件重名、`depends_on` 依赖存在性与成环、范围字段形态软告警（顿号/逗号/括号）。
+8. **归一化（normalize）**：校验归档块元数据四字段完整性、完成时间与归档日期一致性、降序排序、范围字段形态（顿号/逗号疑似多值分隔可 `--fix` 归一为半角加号，括号疑似注释仅提示人工）、git 冲突标记（多写者同天归档的 `pull` 冲突可 `--fix` 按并集去重 + 降序确定性解决）；`--fix` 可补齐缺失元数据并重排。