@fxri/toolkit 1.11.0 → 1.11.1

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # 方弦工具集
 
+## 1.11.1
+
+> 2026-09-27 发布
+
+### 🔧 功能调整
+
+- 三处未来时间告警文案（`tasks check` / `tasks normalize` / `tasks archive`）补明「晚于当前系统时间 14 小时以上」阈值，与跨时区容差口径一致
+
+### 🐛 问题修复
+
+- 未来时间检测改用跨时区容差（UTC+14），UTC 运行环境下不再把本地墙上时间误报为未来时间
+
+### 📝 文档更新
+
+- `SPEC.md` 与技能配套规范 `task-spec.md` 声明主从关系，规范内容以 `SPEC.md` 为单一事实源
+- 收敛全局规则页机制细节表述，改由技能包文档承载
+
 ## 1.11.0
 
 > 2026-09-27 发布

package/SPEC.md

@@ -1,17 +1,17 @@
 # 任务文件规范（SPEC）
 
-> 规范更新时间 2026-09-26 16:56。本规范内容变更时以变更时刻更新此值，实现方与规范快照据此对照是否失同步。
+> 规范更新时间 2026-09-27 02:35。本规范内容变更时以变更时刻更新此值，实现方与规范快照据此对照是否失同步。
 
 > 本规范**全语言支持**，面向**多人 + AI 跨项目协作**，定义任务文件的目录结构、文件格式与归档规则。任何编程语言均可按本规范实现读写；@fxri/toolkit 的 `tasks` 域仅为参考实现。
 >
-> 本文是**摘要**。字段说明、示例与各语言实现要点不变，交互式阅读与逐条校验说明见文档站 [完整攻略 · 任务文件规范](https://fxri-net.github.io/toolkit/guide.html#任务文件规范)；规范内容的单一事实源即本文件。
+> 本文件是规范内容的**单一事实源**；派生载体有文档站 [完整攻略 · 任务文件规范](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 模式三），不建档。**仓库文件改动口径**：需写入版本控制的工作区文件的增 / 改 / 删（源码、配置、文档、技能、任务区自身均计入），纯读取、纯执行、纯汇报不计入；拿不准时列出差异问用户，不猜。**归档块不可变**：已归档块不追加新的工作内容，延续需求一律走新任务；唯一例外是**事实更正**——后续核实推翻原块结论时，在其正文末尾追加「修订记录」（保留原结论、不动元数据行、附更正时刻与依据）。
-2. **任务唯一键**：`{年月日}-{用户名}-{任务简述}` 唯一标识一个任务；多人对同一需求不得各自建档，应共用同一文件。
+2. **任务唯一键**：`{YYYYMMDD}-{用户名}-{任务简述}` 唯一标识一个任务；多人对同一需求不得各自建档，应共用同一文件。
 3. **收尾边界到沉淀**：强制约束到「归档 + 规范沉淀」为止——终结态任务归档后做任务级规范沉淀（写入 conventions 载体），归档 + 沉淀即流程终点；提交、发版、推送不是必经步骤，是否执行取决于用户的全局 / 个人 / 项目规则。**动作不算，改动才算**：任务 = 已确认的方案 + 它落地的仓库文件改动；收尾动作（提交、发版、推送、部署）本身及其固有产物（版本号、更新日志、标签）不构成任务、不单独建档，但当这些动作过程中出现需改仓库文件才能解决的缺陷（如打包配置错误、发布渠道错误）时，该修复按普通任务建档。若提交代码，先归档与沉淀、后提交，任务记录与代码变更落在同一 git 提交。
 4. **可执行项必须落地为任务**：方案正文里的「待办 / 待实施 / 待核对」等子项，应拆分为独立 active 任务，不留游离待办；`toolkit tasks check` 会扫描此类未闭合标记。
 
@@ -20,11 +20,11 @@
 ```
 .tasks/
 ├── active/                    # 实时任务（未完成）
-│   └── {年月}/                # YYYYMM，如 202609
-│       └── {年月日}-{用户名}-{任务简述}.md
+│   └── {YYYYMM}/              # 按月分目录，如 202609
+│       └── {YYYYMMDD}-{用户名}-{任务简述}.md
 ├── archive/                   # 任务归档（已完成）
-│   └── {年月}/
-│       └── {年月日}.md        # 某天归档
+│   └── {YYYYMM}/
+│       └── {YYYYMMDD}.md      # 某天归档
 └── conventions/               # 项目协作规范载体（可选）：从任务提炼的规范沉淀地，非任务文件
     ├── index.md               # 唯一入口与唯一权威（常驻读）：首行为形态标记；端清单 + 每条规范一行指针（首列为稳定 ID）
     ├── history.md             # 规范演进记录（只追加、不改旧行；按需读）
@@ -38,9 +38,9 @@
 
 ### 2.1 命名
 
-`{年月日}-{用户名}-{任务简述}.md`，示例 `20260902-唐启云-忘记密码.md`
+`{YYYYMMDD}-{用户名}-{任务简述}.md`，示例 `20260902-唐启云-忘记密码.md`
 
-- `年月日` = 任务创建日，`YYYYMMDD` 直接拼（不加 `-`）
+- `YYYYMMDD` = 任务创建日，直接拼接（不加 `-`）
 - `用户名` = git 用户名
 - `任务简述` = 简短短语（不加空格；建议团队统一语言）
 
@@ -76,7 +76,7 @@ scope: app
 
 ### 3.1 命名
 
-`{年月日}.md`，按任务**完成时间**的日期（`YYYYMMDD`）划分。
+`{YYYYMMDD}.md`，按任务**完成时间**的日期划分。
 
 ### 3.2 内容
 
@@ -109,7 +109,7 @@ scope: app
 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` 检出并提示）；正文内部形如 `{年月日}-{负责人}-{简述}` 的 `## ` 标题会被视为疑似任务块并在 `normalize` 检出提示人工确认（不自动修复）。
+7. **任务块边界与疑似任务块**：任务块边界以块间 `---` 分隔符为唯一权威边界，`## 标题` 与 `> 元数据` 行仅作校验项（缺失或不全时仍解析为块，由 `normalize` 检出并提示）；正文内部形如 `{YYYYMMDD}-{负责人}-{简述}` 的 `## ` 标题会被视为疑似任务块并在 `normalize` 检出提示人工确认（不自动修复）。
 8. **并发归档防护**：归档采用排他锁（`.archive.lock`），检测到并发归档时跳过并告警；`--dry-run` 可预演归档动作而不落盘。锁须具备自愈语义——持有进程已退出，或锁龄超过实现约定的绝对上限（兜底 pid 复用导致的「假存活」）时，后续写操作接管该锁而非永久阻塞；正常的并发写者仍按跳过处理。
 
 ## 5. 其他语言实现要点