task-ledger 1.2.9 → 1.3.1

package/README.md

@@ -1,265 +1,49 @@
 # task-ledger
 
-> 这份文档**给人看**：它是什么、为什么这么设计、一次调用背后发生什么。
-> 给 agent 的执行说明在 `SKILL.md`，两者不重复；`SKILL.md` 里**没有**引用本文件，所以它不会进 agent 上下文、不占 token。
+> 给人看的概览与索引。给 agent 的执行说明在 `SKILL.md`（每次会话整份注入），两者不重复；本文件不进 agent 上下文、不占 token。
 
-## 一、它做什么
+## 它做什么
 
-管一个项目 / 工作区的任务进度（开发活、琐事、调研、备忘都算），一共三件东西：
+管一个工作区 / 项目的任务进度（开发活、琐事、调研、备忘都算），一共三件东西：
 
-| 管什么 | 落在哪 | 谁写 |
-|---|---|---|
-| 在办任务的状态 | `ledger/progress.json` | **只由脚本写** |
-| 每个任务的过程正文 | `ledger/worklog/<年月>/<日>-<时分>-<说明>-<随机码>.md` | **建档只由脚本按模板做**，之后正文 **agent 直接编辑** |
-| 已结案任务，一行一条（9 列：结案时间 / 创建时间 / 工作包 / 分类 / 标签 / owner / creator / 摘要 / 过程文档） | `ledger/history/<年月>.md`（按**结案时间**分月；存量 `ledger/PROGRESS-HISTORY.md` 只读兼容、永不重写） | **只由脚本写**；查询走 `history` 子命令 |
+- **谁在做、做到哪**：状态只在台账 JSON —— `ledger/pool.json`（公共池）+ 每人一份 `ledger/owners/<hash>.json` 分片，索引 `ledger/owners.json`。
+- **过程正文**：全在 `ledger/worklog/<年月>/<月日>-<时分>-<说明>-<码>.md`（六节），agent 直接编辑前五节，末节「执行记录」只由脚本写。
+- **已结案**：一行一条在 `ledger/history/<年月>.md`（9 列），只由脚本写。
 
-覆盖的动作：建任务、认领、交接、改状态、结案、查在办、查历史、体检。
+状态改动与正文重写分开、全部经脚本改 —— 不另建副本、不手改状态表和历史。覆盖动作：建任务、认领、释放、结案、查在办、查历史、标签归并、体检。
 
-典型场景：
+## 文件布局（脚本只写这些）
 
-- 问「现在该做什么 / 我还有什么没做完」→ 查在办
-- 说「新建一个任务 / 这活我领了 / 卡住了 / 转给某人 / 这活做完了」→ 改状态或结案
-- 问「某件老活是什么时候做的」「谁改过什么」「拉某人的工作日志」→ `history` 子命令（只读，可直接跑）
-
-## 二、为什么这么设计
-
-### 顶层目录为什么是 `ledger/`，不是 `docs/`
-
-`docs/` 是**项目自己的地盘** —— 项目的文档规范、设计、样例都住在那里，各有各的规矩。
-把进度三件套塞进 `docs/`，等于让「进度管理」去占用别人已经安排好的空间；
-换一个没有 `docs/` 的项目、或项目把 `docs/` 用作别的用途，就又得重新商量放在哪。
-
-所以本 skill 统一用**独立的 `ledger/` 目录**：任何项目、任何工作区都用同一个名字，
-既不依赖项目原有的 `docs/`，也不与它发生关系（项目原有 `docs/` 原样不动、不进本体系）。
-进度是「跨项目长一个样」的东西，就该有一个跨项目固定的家。
-
-### 状态用 JSON，不用 Markdown
-
-状态要频繁改（`open` → `doing` → 结案），Markdown 里改一个词很容易顺手改到别处。JSON 结构化、字段固定、一次只动一个值，改动面最小。
-
-### 状态与过程正文分离
-
-状态改动频繁、正文频繁重写，混在一个文件里必然互相踩。所以拆成两个文件：**JSON 只放数据，正文全在 `worklog/`**。JSON 里一个字的过程描述都不放 —— 一旦开始写段落，改动面就不可控了。
-
-唯一进 JSON 的「文档类」信息是过程文档的**路径**（`worklog` 字段，如 `worklog/202610/06-0000-doc-arch-review-7a3c.md`）。它不是描述而是索引：按月分目录之后文件名不再等于任务号，靠推算容易找错，记一笔最省事。
-
-### 历史层的 owner 是独立列
-
-「谁改过什么」「拉某人的工作日志」靠 `history --owner` **精确匹配**。owner 必须独立成列，不能缝在工作包标题里：缝进去就只能文本搜索，`a` 会命中 `a-11`；切分也只能靠「最后一个 ` @`」这种启发式，标题里出现 `@`（如 `rulemux@0.1.0`）就切错。独立列让按人查退化成列比较，与 `list --owner` 查在办是同一套精确语义。
-
-### 记录时间精确到秒，任务号 / 文件名只到分
-
-两者用途不同，精度也不同：**任务号、worklog 目录与文件名**只到分（`年月日-时分` / `YYYYMM`）—— 够排序、够肉眼定位，且短；**所有记录时间**（`progress.json` 的 `created` / `started` / `finished`、历史表的时间列、worklog 头部的创建 / 封卷行）到**秒** —— 按时间段检索、比对都靠它，分不够。
-
-写入前一律经 `normalize_time` 归一化：`2026-10-06`、`2026-10-06 14:30`、`2026-10-06 14:30:05` 都接受，缺的补 `00:00:00`。读旧数据时又**兼容只到分**的写法（老历史行照读不误），只有新写入的才带秒。
-
-### 历史表为什么带创建时间
-
-历史层的过滤口径是**创建时间**（`list` / `history` 的 `--since` / `--until` 都按它），因为「这活是什么时候建的」比「什么时候被结案」更常用、也更稳。所以历史行同时存**结案时间**（第一列）与**创建时间**（第二列）。升级旧行时创建时间先读它链接的 worklog 头部「创建」行，读不到用升级时刻 —— 不留空。
-
-### 历史层为什么按月归档
-
-`close` 每结案一行就往历史层追加，早期是单一文件 `ledger/PROGRESS-HISTORY.md`：项目一两年下来它无限增长，每次结案都要整文件读入、升级、重写 —— 结案成本随历史总量线性变差。
-
-现在按**结案时间**分月落 `ledger/history/<年月>.md`，与 worklog 的 `ledger/worklog/<年月>/` 同构：
-
-- **写入时分月，不做定时外挪** —— 外挪需要一个「谁定时触发」的角色，必然漂移；写入时分月零新增动作，且结案只碰当月小文件
-- **存量文件原地只读** —— 改造前的 `ledger/PROGRESS-HISTORY.md` 永不重写、永不删除，读侧 glob 兼容；它里面的旧格式行也不会被自动升级（读侧三格式兼容 + `validate` 提示已覆盖）
-- **文档链接跟着所在文件走** —— 行里的 worklog 链接相对该行所在的历史文件目录解析：存量文件里是 `worklog/…`，月文件里是 `../worklog/…`，两边都可点击、可定位
-- **查询无感** —— `history` / `validate` 合并全部来源，过滤、排序、`--json` 行为不变；行尾附所在历史文件，`--json` 记录带 `src` 字段
-
-### 状态文件只由脚本写
-
-两个人（或两个 agent）同时编辑同一个文件会互相覆盖。脚本的写入靠两层保证：
-
-1. **原子替换**：先写同目录的临时文件，再 `os.replace` —— 保证文件不会出现半截内容
-2. **写前复查指纹**：读的时候记下文件的**内容哈希**（sha256），写之前再比一次；变了就报错中止、要求重跑。
-   刻意不用 mtime+size —— 并发写入可能落在同一时间精度内、字节数又恰好相同，那样指纹不变，复查就形同虚设
-
-第 2 条是**发现并中止**，不是自动合并 —— 它把「静默覆盖别人」变成「明确报错让你重来一次」。所以并发下偶尔会遇到「被改动过，重跑」，这是设计如此，不是 bug。
-
-### worklog 头部只写不会变的东西
-
-原设计里 worklog 头部带 `状态：open · owner：（待认领）`，实测发现：**`claim` 之后头部还写着 `open`，成了过期副本**。删掉 —— 状态真源只有 `progress.json` 一个。
-
-现在头部只写两样**写入后就不再变**的：**创建时间 + 创建人**（`new` 建档时写）、**封卷时间 + 封卷人**（`close` 结案时追加）。会变的东西（状态、当前 owner）一律不写。
-
-### 任务号 = 创建时间 + 语义名 + 4 位随机码
-
-`登录接入 SSO`（2026-10-15 14:30 建的）→ `20261015-1430-登录接入-sso-1eed`。
-
-- 前置 `年月日-时分`：一眼看出这个任务是什么时候建的，也天然按时间排序
-- 中段语义名：一眼知道是什么任务（所以保留汉字，纯中文标题也能生成）
-- 后缀 4 位随机码：**必须保留** —— 任务号只在在办任务里去重，而 worklog 结案后仍留在磁盘上，去掉随机码会让新任务与已结案的过程文档同名、覆盖历史
-- 不用纯 UUID：文件名会变得完全不可读
-- 想自己指定就传 `--id`
-
-### owner 只认 git 身份，不做兜底
-
-`owner` 一律取 `git config user.name`。取不到就**直接报错退出**（提示「需要用户名才能执行」），没有默认值、没有备选标识、没有降级路径。
-
-理由：拿一个编造的身份去写"谁在做这个任务"，比写不进去危险得多。
-
-### 只能改自己的任务
-
-`set`、`close` 和 `log` 都先取身份，再校验「这个任务的 owner 是不是你」：**不是就拒绝**；任务还没人认领（`open`）也拒绝，提示先 `claim`。要接手就走 `set --owner` 交接 —— 一次显式动作。
-
-理由有两层：一是别人替你结案，你会失去对进度的掌控；二是如果只取了身份却不校验归属，`owner` 这个字段就只是个装饰品。
-
-### 不依赖任何框架注入的变量
-
-早先写成 `{baseDir}/scripts/progress.py` —— 那是某一家的注入变量，换个 harness 就没有。现在写成「本 SKILL.md 所在目录」这种不依赖注入的表述。
-
-同理，**项目位置必须由调用方用 `--repo` 传**：脚本只知道自己在哪，不可能知道你现在在哪个项目里干活。
-
-### 并发策略
-
-- 所有写命令（`init` / `new` / `claim` / `set` / `log` / `close`）走同一套：**读 → 改内存 → 复查指纹 → 原子写**
-- 临时文件名唯一（`mkstemp`），写完 `fsync` 再 `os.replace`，无论成败都清理临时文件
-- key 按字母序落盘，减少两人同时新增时的文本冲突
-- 冲突时**报错要求重跑**，不静默覆盖
-- 写入成功后脚本会**自动同步**：把本次改动的台账文件 `git add <精确文件>` + `commit`（消息 `chore(ledger): <命令> <提交者>`，即 conventional commits 格式，多数仓库装了 commitlint 也认）；当前分支有上游跟踪分支时再 `push`。全程确定性脚本，不依赖大模型
-- 仓库若装了自定义提交检查并拒了这条消息，脚本会**再用 `--no-verify` 提交一次**（台账是数据文件，不过 lint）；仍失败则把 git 的报错打到 stderr 并要求手动提交 —— **同步失败绝不静默**，但退出码保持 0（台账本身已写成功）
-- 写前会**定向取最新**：只刷新 `ledger/progress.json` 与 `ledger/history/`（这两个只由脚本写）；`ledger/worklog/` 里已有的正文一个字都不动，只在本地缺文件时补下远端的新文件（补下的文件随本次提交入库）。本地有未推送的台账提交、未提交改动、或未入库的同名文件时**中止**，不静默覆盖；命令随后失败时，写前刷下来的内容会回滚原样
-- 本地**没有未推送提交**时，写前会先 fast-forward 到上游（只快进、不产生合并提交）；有未推送提交就跳过，退回上面那条的定向刷新
-- 同一个 clone 里的写命令**排队**执行（仓级文件锁，最多等 60 秒），避免两个 agent 同时写时，一个把另一个刚写完还没提交的改动静默覆盖
-- 写后推送被拒时，工作树干净才自动 `rebase` 一次再推（各自改各自的任务时按行自动合并）；冲突立刻 `rebase --abort`，绝不 `--force`、绝不留 rebase 中间态
-- 无 git 仓库 / 无上游跟踪 / 被 `.gitignore` 排除 / 无实际变更 都会静默跳过；`--no-sync` 或环境变量 `TASK_LEDGER_NO_SYNC=1` 可同时关掉写前取最新与写后同步
-
-### 结案是原子操作
-
-`close` 一次完成三件事，**顺序是有意排的**：先写历史索引 → 再封卷过程文档 → **最后**才从状态表里移除。
-
-为什么是这个顺序：万一中途崩溃，最坏结果是「历史多了一行、状态表里任务还在」，重跑一次就对上了；反过来先删状态、后写历史，崩溃会让任务**既不在状态表、也不在历史** —— 记录凭空消失。
-
-落盘时任一步失败会**整体回滚**，并逐文件报告哪些恢复成功、哪些没成功（回滚本身失败时不会掩盖原始错误）。
-
-### 分类与标签为什么不设枚举
-
-本 skill 跨所有工作区使用（开发 / 运维 / 个人事务 / 调研备忘都算），任何固定枚举都覆盖不全、颗粒度难定；「让 Agent 判断会不准」也不能靠穷举分类消解。所以分两层、都自由：
-
-- **`category` 单值**：答「这事是什么类型」。一条一值，`count by` 干净，是人眼扫视和看板统计的轴
-- **`tags` 1~5 个**：答「这事涉及什么」（对象 / 领域 / 模块）。兜住长尾与新领域，写错了只影响一个切面
-
-两层都只硬校验**形态**（≤4 字 / 纯英文 ≤3 词 / ≤5 个），不校验语义 —— 语义 correctness 交给口径（SKILL.md 的归一化规则 + 正反示例）和巡检归并机制，不交给枚举。
-
-### category 精确匹配、tag 包含匹配
-
-两种查询语义不同是有意的：category 是统计轴，同值才能比较，必须精确；tag 是容错下钻，「bug」命中「bug修复」正是包含匹配要的效果 —— 它天然吃掉一部分同义变体，剩下的漂移靠 `tags --all` 暴露、`tags --rename` 归并。
-
-### 为什么只硬校验上限、不设标签数量下限
-
-设下限（如必须 3 个标签）会逼 Agent 凑数 —— 凑出来的正是噪声，与「容忍错误」的初衷相反。上限（≤5）与字数（≤4 字 / 英文 ≤3 词）是形态红线，必须硬校验；数量只引导、不强制。
-
-### 分类/标签进 history 列（2026-10-15 存量改造时加入）
-
-初版设计是「不进列、回链读」：history 解析写死 6 列，加列要迁移存量。用户评审时要求反转——已结案记录也要能按分类/标签查，于是升为 **8 列**（结案时间 / 创建时间 / 工作包 / 分类 / 标签 / owner / 摘要 / 过程文档）：
-
-- `close` 从 task 直写分类/标签终值（`--category`/`--tags` 覆盖过的用覆盖值）
-- 存量 4/5/6 列由 `upgrade_history` 升级为 8 列：分类/标签**回链该行 worklog 头部**读（`labels_for_log`，与 created 回填同一模式），读不到留空、不编造
-- 回链没有废弃：`history` 子命令对仍是 4/5/6 列的旧行（未升级文件）继续回链兜底，`cmd_history` 里「列空才回链」
-
-代价说清：加列动了 parse/upgrade/close 全链路，靠「逐行按自己列数判别 + 不敢升级就按原列数追加」的老机制兜底；冒烟覆盖了 8 列写入、6 列升级（owner 剥 @ 防 `@@`）、4 列升级、坏行退回四条路径。
-
-### rename 为什么不碰已封卷文档
-
-与「封卷即不可变」同一哲学：rename 只改状态表与在办 worklog 头部；已结案记录的旧标签留在原文档里。这类残留在 `tags --all` 的频次表里可见，看板侧自行归并 —— 台账只做记录，不做历史改写。
-
-### 「分类/标签」行为什么由 render 动态插入
-
-不占模板占位符 ⇒ `assets/worklog.md` 与 `FALLBACK_TEMPLATE` 都不用改，两个模板永远一致；空值（存量任务、Agent 没总结）自动不写行，向后兼容零成本。生成、解析、覆盖三处共用 `label_line` 一个格式定义，防漂移。
+| 文件 | 装什么 |
+|---|---|
+| `ledger/pool.json` | 公共池：未认领任务（owner 空） |
+| `ledger/owners.json` | 索引：git 邮箱身份 → 分片文件 |
+| `ledger/owners/<hash>.json` | 每人一份分片：自己认领的任务 |
+| `ledger/worklog/<年月>/*.md` | 任务正文（六节） |
+| `ledger/history/<年月>.md` | 已结案（一行一条，9 列） |
 
-## 三、运行逻辑
+## 为什么这么设计
 
-### 一次调用发生什么
+跨项目固定用 `ledger/`（不占项目的 `docs/`）；状态用 JSON 而非 Markdown（改动面最小）；状态与过程正文分离（互不踩）；一人一份分片把并发冲突面从整份文件缩到公共池里几行；台账数据时间存 UTC、过程文档里的日志行显示本地时间。
 
-```mermaid
-graph LR
-    U[用户说一句话] --> A[agent 读 SKILL.md 判断意图]
-    A -->|只读直接跑| R[list / show / validate / history]
-    A -->|写操作| W[init / new / claim / set / log / close]
-    W --> P[ledger/progress.json]
-    W --> H[ledger/history/年月.md]
-    W --> M[ledger/worklog/年月/日-时分-说明-码.md]
-    A -->|直接编辑| M
-    A -->|只读查询| H
-    W -->|返回该任务文档全文| A
-```
+## 怎么用（执行规则在 SKILL.md）
 
-### 状态机
+直接跑：
 
-```mermaid
-stateDiagram-v2
-    [*] --> open: new（不带 --self）
-    [*] --> doing: new --self
-    open --> doing: claim（认领，写 owner）
-    doing --> open: set --status open（释放认领，清空 owner）
-    doing --> [*]: close（进历史）
-    note right of doing
-        set --owner 交接：owner 换成别人
-        （只有当前 owner 能执行）
-        逾期 = 接任务满 14 天；停滞 = 最后更新满 3 天
-        积压 = 待认领满 30 天
-        （都由看板按时间算，不是状态）
-    end note
+```bash
+python3 <SKILL.md 所在目录>/scripts/progress.py <子命令> --repo <当前工作区>
 ```
 
-- `done` **只能由 `close` 产生**；`set --status done` 会被拒绝
-- **退回未认领**：owner 用 `set --status open` 把任务退回去，owner 清空、之后别人可以重新 `claim`；这条不能与 `--owner` 同时给
-- `set --owner <某人>` 是**交接**，由当前 owner 执行，执行后 owner 换成那个人。**该能力只为将来的 UI 保留**：SKILL.md 不向 agent 暴露它，换人一律走「释放 → 认领」，避免随便编一个名字挂上去
-- 状态表里不允许残留 `done`（`validate` 会报）
-
-### 命令一览
+子命令：`new` `claim` `set` `log` `close` `list` `history` `show` `tags` `validate`。命令参考（参数 / 一句话 / 举例）、任务生命周期、纪律（数据完整性 / 人类授权 / 故障处置）全在 `SKILL.md`；参数细节看 `<子命令> --help`（不要凭记忆编）。
 
-| 子命令 | 作用 | 需要 git 身份 | 会返回任务文档全文 |
-|---|---|---|---|
-| `init` | 建状态表 | 否 | 否 |
-| `new` | 建任务并建档 | **是**（记 creator） | 是 |
-| `claim` | 认领待认领任务 | **是** | 是 |
-| `set` | 改状态 / 交接 / 释放认领（`--status open`） | **是**（且必须是该任务的 owner） | 是 |
-| `log` | 往 worklog「执行记录」补一条 | **是**（且必须是该任务的 owner） | 否（只回一行确认） |
-| `close` | 结案归档 | **是**（且必须是该任务的 owner） | 否 |
-| `list` | 查在办任务 | 仅 `--mine` | 否 |
-| `history` | 查已结案任务（只读） | 仅 `--mine` | 否（只给过程文档链接） |
-| `show` | 单任务详情 | 否 | 是 |
-| `tags` | 分类/标签巡检（`--all` 只读）/ 归并（`--rename` 批量写） | 否 | 否 |
-| `validate` | 校验一致性 | 否 | 否 |
+## 深入参考（references/，按需读）
 
-参数细节看 `SKILL.md`，或直接跑 `<子命令> --help`。
-
-### 返回什么
-
-| 命令 | 返回 |
+| 文件 | 看什么 |
 |---|---|
-| `new` / `claim` / `set` / `show` | 状态行 + 该任务过程文档的**路径与全文** |
-| `log` | 一行确认（记了什么） |
-| `close` | 结案结果与摘要 |
-| `list` | 在办任务列表（不含正文，避免撑爆上下文） |
-| `history` | 已结案紧凑列表（默认不含摘要，避免撑爆上下文） |
-
-返回文档全文是有意的：agent 拿到就能直接编辑，不用再去找文件、拼路径。
-`history` 是唯一的例外：只回过程文档的**链接**，正文另读 —— 历史层摘要就是这套体系里唯一的「正文」，默认不吐。
-
-### 失败约定
-
-| 情况 | 行为 |
-|---|---|
-| 成功 | 退出码 0 |
-| 业务错误（参数值 / 状态 / 权限不对） | 输出到 stderr，**退出码 1**，消息以「错误：」开头 |
-| 命令行参数错误（argparse） | 退出码 2 |
-| 未预期的内部失败 | 输出到 stderr，**退出码 3**（与可纠正的业务错误区分开） |
-| 用户中断 | 退出码 130 |
-| 输出被下游截断（如 `\| head`） | 静默退出，退出码 0，不打 traceback |
-
-**报错就停下并原样报告，不要绕过脚本直接改 `ledger/progress.json` 或历史层（`ledger/history/<年月>.md`）。**
-
-## 四、已知边界与待办
-
-1. 本 skill 位于工作区 `_Skills/task-ledger/`；是否安装到全局 skill 目录由使用者决定 —— 未安装时其它项目不会自动触发。
-2. `scripts/progress.py` 里的 `FALLBACK_TEMPLATE` 是**无注释的最小骨架**，只在 `assets/worklog.md` 读不到时启用 —— 两处注释多寡不同不是缺陷，**正例只放模板文件**。
+| [`references/state-model.md`](references/state-model.md) | 状态机、时间口径（UTC / 本地、补录、筛选）、任务号、身份 |
+| [`references/log-note.md`](references/log-note.md) | 执行记录什么算一个节点、`--note` 怎么写（正 / 反例） |
+| [`references/troubleshooting.md`](references/troubleshooting.md) | 退出码、常见错误、硬约束、环境要求（git ≥ 2.27） |
 
-## 五、维护者须知
+## 本仓自己的台账
 
-- `SKILL.md` 的 frontmatter `version` 与 `package.json` 的 `version` 保持同值；发版时一起改，打 `skill-v<version>` tag。
-- **`SKILL.md` 是每次会话整份注入的**：只放「不做就会写错数据」的规则与路由，细节进 `references/`（按需读，索引在 SKILL.md 末尾）。加体积前先自问「脚本或 `--help` 能不能兜住」。
-- 改完跑 `cd packages/plugin && npm run verify`（build + typecheck + smoke）；`copy-skill` 会把 `scripts/` `assets/` `references/` 一并拷进插件内嵌副本，不要直接改那份拷贝。
+本仓库（`dsh-task-ledger`）也用 ledgerkit 管自己的活，台账数据在 `ledger/`；它和本 skill 源码 `packages/skill/` 是两回事 —— **改 skill 请别动 `ledger/`**。

package/SKILL.md

@@ -1,134 +1,219 @@
 ---
 name: task-ledger
-description: 本地任务台账，跨会话记录在办任务的归属、进度与起止。当用户要登记一件新的事（新建任务 / 建个坑 / 这活我领了）、记录已有任务的进展（接着做 / 记一条进展 / 这轮先记下）、查看任务状态或历史（现在该做什么 / 这活谁在做 / 上周做过什么）时加载；对某个具体任务要求结案或退回时，只认用户的明确指令；只是改代码、讨论方案时不要用。
-version: 1.2.9
-allowed-tools: Read,Write,Bash,Grep
+description: 本地任务台账，跨会话记录在办任务的归属、进度与起止。当用户要登记一件新的事（新建任务 / 建个坑 / 这活我领了）、记录已有任务的进展（接着做 / 记一条进展 / 这轮先记下）、查看任务状态或历史（现在该做什么 / 这活谁在做 / 上周做过什么）、给任务结案或退回（做完了 / 验收通过 / 不做了 / 退回待认领）、整理标签或检查台账一致性时加载；只是改代码、讨论方案时不要用。
+version: 1.3.0
+allowed-tools: Read,Edit,Bash,Grep
 ---
 
 # task-ledger
 
-台账只管三件事：**谁在做、做到哪、什么时候建 / 结**。状态只在 `progress.json`，叙事只在 worklog，**全部经脚本改**。
+管一个工作区的任务进度：**谁在做、做到哪、什么时候建 / 结**。
 
-## 三个文件
+- **数据落点与多人并行**：每个工作区下有一个 `ledger/` 目录，任务与进度以静态文件形式存放在里面。**多人协同必须有 git**；没有 git 只写本地，也能用。多人共用却没有 git，提醒用户。
+- **任务状态**：`待认领（open）` = 建了还没人认领；`进行中（doing）` = 已认领、在做；`已结案` = 用户明确说结束后由 `close` 产生，此后只读。
+- **操作方式**：台账的状态与归属只经命令改；唯一能手写的是过程文档前五节（见「手写边界」）。台账只记「建 / 做 / 结」和指向过程文档的链接；产出物本身按项目自己的约定落盘。
 
-| 文件 | 装什么 |
+## 手写边界
+
+- **唯一能手写的是任务的过程文档（worklog）前五节**（怎么写见「过程文档」节）；末节「执行记录」由脚本维护，**禁止手写、禁止手工添加**。
+- **其他所有文件一律不许手改**：修改 / 删除 / 任何操作都走命令；手改台账文件即数据损坏。
+- 台账看着不对劲（任务凭空少了、状态怪、分片对不上）⇒ **不要动手修**：让用户跑 `validate`（要连老月份和正文一起看就跑 `validate --deep`），把清单交给用户。
+
+## 命令参考
+
+九个子命令，前五个是写命令（`new`/`claim`/`set`/`log`/`close`），后四个全是查询类（`list` / `show` / `history` / `validate`）；何时用哪个见「任务生命周期」。参数语法看 `<子命令> --help`；下表说每个参数干什么、何时用。
+
+### new — 建任务
+
+| 参数 | 含义 |
 |---|---|
-| `ledger/progress.json` | 在办任务：标题 / owner / 状态 / 时间（`created` `started` `updated` `finished`）/ 分类标签 / 过程文档路径。**只由脚本写** |
-| `ledger/worklog/…md` | 任务正文，六节：背景 / 待办 / 下一步 / 过程 / 结论 / **执行记录**（末节） |
-| `ledger/history/<年月>.md` | 已结案，一行一条。**只由脚本写** |
+| `--title "…"` | 任务标题（必填）—— 写任务核心、一句话说清干啥；它用来生成任务号和过程文件名，建议 4~20 字 |
+| `--id` | 自定义任务号（一般不传；只能用小写字母、数字、汉字和连字符） |
+| `--created` | 给过去漏记的任务补建时，补录实际创建日期（`YYYY-MM-DD`） |
+| `--self` | 建并认领：直接归自己名下、状态「进行中」。仅当用户明确说「并开始做 / 并执行」时才用（判定见生命周期第 2 条） |
+| `--category` / `--tags` | 分类 / 标签，口径见本节末尾 |
 
-前五节你直接编辑；**末节「执行记录」只由脚本追加，一个字都不许手写**。
-不另建副本、不手改状态表和历史、不自己拼 worklog 文件名（`new` 会建好并给路径）。
-**台账 ≠ 产出物**：成果按所在项目自己的约定落盘，台账只放「建/做/结」和指向成果的链接。
+干什么：建任务、按模板建好过程文档。不加 `--self` = 只建，落公共池等认领；加 `--self` = 建并认领。
 
-## 什么时候用
+分类 / 标签口径（`new` 与 `close` 共用这组参数）：`--category` 答「是什么类型」，单值，中文 ≤4 字 / 纯英文 ≤3 词，吃不准写「其他」；`--tags` 答「涉及什么」，0~5 个、逗号分隔，写不出就不传（传空串等于没传）。tags 不许写 category 的同义词；查询用 tags（包含匹配，见 `list --tag`）。名词性短语、中文优先。**在办任务的分类 / 标签一旦写下就改不了**，只有结案时用 `close --category` / `--tags` 写终值。正例：`--category 缺陷修复 --tags "镜像拉取,超时重试"`；反例：`--category 已完成登录修复`、`--tags 修 bug`。
 
-❌ 项目没有 `ledger/` 且只是临时一次性的事 → 不要自动 `init`，先问。
-❌ 只想改某任务正文 → 用 `show` 拿路径与全文直接改，不要另建 md；已结案的用 `history` 找链接。
+举例：用户说「新建个任务：把发布流程走通」→ `new --title "把发布流程走通"`（只建，不认领）；用户明确说「新建个任务并开始做」→ `new --title "把发布流程走通" --self`。
 
-## 意图 → 命令
+### claim — 认领
 
-| 用户说 | 动作 |
+| 参数 | 含义 |
 |---|---|
-| 「现在该做什么」「我还有啥没做完」 | `list --mine` |
-| 「谁在做 X」「有哪些在办」 | `list`；在等认领的加 `--status open` |
-| 「这个任务到哪一步了」「这轮做了什么」 | `show --id`（任务 JSON + worklog 全文） |
-| 「某件老活什么时候做的」「谁做过哪些活」 | `history`（可按 `--owner` / `--since` 筛） |
-| 「哪些任务停太久」 | `list --json`：`updated` 满 3 天＝停滞、`started` 满 14 天＝逾期、`created` 满 30 天仍 `open`＝积压（看板算，别改状态） |
-| 「新建一个任务」 | `new`（`--self` = 建完即认领） |
-| 「这活我领了」 | `claim`（只对 `open` 有效） |
-| 「开始做 / 接着做 X」 | 还是 `open` 就先 `claim`；已是 `doing` 就直接改正文 + `log` |
-| 「继续做」「推进一下」 | 改「下一步 / 过程」，再 `log --note "本轮做了 X，下一步 Y"` |
-| 「记一下这轮」「这段做完了」 | `log --id <任务号> --note "…"`（agent 可主动做） |
-| 「卡住了」「先放一放」 | 写清卡在哪（不改状态），再 `log` |
-| 「退回待认领」「让别人接」 | `set --status open`（记 `release`），回待认领 |
-| 「转给某人」 | **skill 不换人**：你先释放，对方自己 `claim`；不许替用户写别人的名字 |
-| 「彻底不做了」「取消这个任务」 | `close --summary "放弃：原因"`（需用户明说） |
-| 「做完了」「验收通过」「结案」 | `close`（需用户明说，见红线） |
-| 「把某任务过程补一下」 | `show --id` → 改前五节 → `log` |
-| 项目还没有台账 / 状态表可疑 | `init`（先问）/ `validate` |
-| 「标签太乱」「两个标签一个意思」 | `tags --all` 看频次 → `tags --rename 旧 新` |
-
-## 命令怎么调
+| `--id <任务号>` | 认领哪个（必填） |
+
+干什么：把公共池里的任务认领到自己名下，状态变「进行中」。已经在别人名下的会拒绝；已在自己名下的会提示无需重复。
+
+举例：用户说「这活我领了」→ `claim --id 20261023-1117-把发布流程走通-7f3a`。
+
+### set — 释放任务（退回公共池）
+
+| 参数 | 含义 |
+|---|---|
+| `--id <任务号>` | 释放哪个（必填） |
+| `--owner ""` | 固定传空串 —— 释放 |
+| `--owner <别人>` | 把任务转交给对方（预留通道，**agent 不用**，见纪律） |
+
+干什么：把任务放回公共池、状态回「待认领」，别人即可认领；没有单独的「改状态」入口。
+
+举例：用户明确说「把这个任务退回去」→ `set --id <任务号> --owner ""`。
+
+### log — 记一条进展
+
+| 参数 | 含义 |
+|---|---|
+| `--id <任务号>` | 哪条任务（必填）—— 只能给自己名下的任务记，不在名下会直接被拒 |
+| `--note "…"` | 这条记录说什么（必填；一句话，含命令 / `文件:行号` / 符号名 / 结论之一） |
+
+干什么：刷任务的最后进度时间 + 在过程文档「执行记录」节追加一行。改正文必配一条 log（见纪律）。
+
+举例：一轮干完 → `log --id <任务号> --note "改了认领即 doing（claim.py:56）；下一步同步文档"`。
+
+### close — 结案
+
+| 参数 | 含义 |
+|---|---|
+| `--id <任务号>` | 结哪条（必填） |
+| `--summary "…"` | 结案摘要（必填；放弃写「放弃：原因」） |
+| `--finished` | 给漏记的旧任务补用时，补录实际结案时间（`YYYY-MM-DD[ HH:MM[:SS]]`） |
+| `--category` / `--tags` | 覆盖分类 / 标签终值（写进历史行） |
+
+干什么：结案并封卷过程文档、移出自己名下。**封卷后只读**（见生命周期第 8 条）。
+
+举例：用户明确说「把这个任务结束掉」→ `close --id <任务号> --summary "发布流程走通，验证 25 项全过"`。
+
+### list — 查在办
+
+| 参数 | 含义 |
+|---|---|
+| `--mine` | 只看自己名下的 |
+| `--pool` | 只看公共池（没人认领的） |
+| `--owner <邮箱>` | 看某个人的（精确匹配；邮箱在 `list --json` 里那个人名下的任务上能看到；没有 `me` 缩写） |
+| `--status open\|doing` | 按状态筛（逗号分隔可多选；合法值只有 `open` / `doing`） |
+| `--category` / `--tag` | 按分类（精确）/ 标签（包含）筛 |
+| `--since` / `--until` | 按创建时间筛（只给日期含当天） |
+| `--json` | 输出 JSON（`{任务号: 任务对象}`） |
+
+干什么：合并公共池 + 各人名下的任务，列出在办。**默认就是全量**，没有 `--all` 参数；收窄用 `--mine` / `--pool`。
+
+举例：「现在该做什么」→ `list --mine`；「有哪些没人认领的」→ `list --pool`。
+
+### show — 看一条任务
+
+| 参数 | 含义 |
+|---|---|
+| `--id <任务号>` | 看哪条（必填；谁名下的都能看） |
+| `--json` | 连过程文档全文一起给（人话模式只给路径） |
+
+干什么：拿任务 JSON + 过程文档路径 / 全文。改既有任务正文前，先用它拿路径。
+
+举例：「这个任务到哪一步了」→ `show --id <任务号> --json`。
+
+### history — 查已结案
+
+| 参数 | 含义 |
+|---|---|
+| `--owner <邮箱>` / `--mine` | 按 owner 筛 |
+| `--category` / `--tag` | 按分类 / 标签筛 |
+| `--since` / `--until` | 按**结案时间**筛（只给日期含当天） |
+| `--months N` | 最近 N 个自然月（与 `--since` / `--until` **互斥**，同传直接报错） |
+| `--limit N` | 最近 N 条 |
+| `--count-only` | 只输出 `{"count","capped"}`（与 `--json` 互斥） |
+| `--json` | JSON 输出 |
+
+干什么：按结案时间倒序排列，每条一行，只列结案时间、负责人、标题，其他都不在表格里；要摘要 / 分类 / 标签 / 完整时间加 `--json`。不给时间参数 = 最近 3 个自然月；最多 13 个月，超了直接报错。
+
+举例：「上周做过什么」→ `history --since <上周一日期>`；「今年都结掉哪些」→ `history --months 12`（超过 13 个月要分段查）。
+
+## 怎么调用
 
 ```bash
 python3 <本 SKILL.md 所在目录>/scripts/progress.py <子命令> --repo <当前工作区>
 ```
 
-子命令：`init` `new` `claim` `set` `log` `close` `list` `history` `show` `tags` `validate`。
-参数细节一律看 `<子命令> --help`（不要凭记忆编参数）。
-写类命令返回 worklog 路径 + 全文；`list` / `history` 只返回摘要，不吐正文。
+- 定位项目：`--repo <目录>` 给了就用；不给就从当前目录逐级向上找第一个含 `ledger/` 的目录。
+- `--no-sync`（放在子命令**前**）：用户明确要求「先别同步」时才用；之后自己 `git add ledger && commit && push`。
+- `--json` 只对只读命令（`list` / `show` / `history` / `validate`）有意义；写命令不接收 `--json`，传了是用法错。`--json` 里的时间字段是 UTC，人话输出是本地时间。
+- 命令回执只用来确认生效；任务状态以 `show` / `list` 为准。
 
-## 铁律
+## 任务生命周期
 
-- **状态只有 `open` / `doing`**；`done` 只能由 `close` 产生。**没有 `blocked` 状态**：逾期 = `started` 满 14 天、停滞 = `updated` 满 3 天、积压 = `created` 满 30 天且仍 `open`，都由看板按时间算，`progress.json` 里不存、不手改；卡在哪写进正文。
-- **`log` 就是刷新 `updated` 的动作**：该记不记，任务会被看板标成停滞。
-- **owner = 当前 `git config user.name`**，不能由外部传入；读不到就报错（先让用户配 git）。**只能动自己名下**的任务（`open` 的先 `claim`），不是你的直接拒绝 —— 不要绕过脚本改 JSON。
-- **换人只能「释放 → 认领」**：skill 不提供交接，随便写的名字都是假的。
-- **「执行记录」禁手改**：只由脚本按 `new / claim / set / release / log / close` 追加，只增不改；手写＝伪造时间线，且不刷新 `updated`。
-- **改正文必配一条日志**：只要动了 worklog 的正文（改一句、补一节、改标题、修错字都算），**必须立刻跑一次 `log`**。没有对应日志的正文改动 = 这轮没做完 —— 时间线上会留下你改过、但没人知道为什么改的空洞。
-- **升级前建的老 worklog 没有这一节**：不用你补，脚本第一次记时自动在文末补一节；文档丢失时 `log` 报错（`updated` 已刷新），用 `show` 查路径，**不要手写**。
-- **旧数据里的 `blocked`**：读侧当进行中；`list --status blocked` 可捞出，用 `set --status doing` 归位。
+用户要「做某件事」时按这条线走。
 
-细节见 `references/state-model.md`。
+1. **建（只建，不认领）—— 默认**：「新建一个任务」「新建个任务，我们来干 X」「新建个任务，我需要处理 Y」→ `new --title "…"`。落公共池、待认领。
+2. **建并认领 —— 仅限明确说法**：用户明确说「新建一个任务**并开始做 / 并执行**」这类带着「现在就开始」的话 → `new --title "…" --self`。直接归自己名下、「进行中」。**除这种明确说法，其他一律按第 1 条只建** —— 别替用户决定他要开始做；拿不定，问一句。
+3. **找已有的**：用户说「我们来做 X」→ 先 `list --mine` 找自己名下的，在做的直接接着做；没有 → `list --pool` 里找，找到先问用户：「X 还没认领，认领它吗？」→ 用户点头再 `claim`；哪儿都没有 → 按第 1/2 条的判定规则建。
+4. **认领**：`claim --id <任务号>` —— 认到自己名下，状态即「进行中」。
+5. **推进**：改 worklog 前五节 → 按「过程文档」节的收工三步记 `log`。卡住也 `log`（写清卡在哪，状态不动）；「先放一放」同理 —— 是暂停，不是释放。
+6. **交付待验收**：任务留「进行中」，「待办」写「待用户验收」，「下一步」写清验收看什么；照收工三步记一条 `log --note "已交付待验收：…"`。
+7. **释放**：仅当用户明确说「退回去 / 释放掉」→ `set --id <任务号> --owner ""`。任务回公共池，别人可认领。
+8. **结案**：仅当用户明确说「把这个任务结束掉 / close 掉」→ `close --id <任务号> --summary "…"`；说得含糊（「做完了」「验收通过」）先反问「是要结束这个任务吗？」。收尾顺序：**先补完正文 + 记 log，最后才 close** —— 关了就不能再写。
+9. **查询**：在办 `list` / 单条 `show` / 已结案 `history`（默认只近 3 个自然月，更早的要 `--months` / `--since`）。
 
 ## 过程文档
 
-1. **建档**：`new` 按模板建六节骨架并把路径写进状态表。
-2. **推进**：你直接编辑前五节，标题不许改名；**每改一轮正文就配一条日志**——同一次编辑动作里连改多处只记一条，改完立刻 `log --note "这轮做了什么"`。
-3. **交付（待验收）**：任务仍留 `doing`，「待办」写「待用户验收」，「下一步」写清验收该看什么；这轮**照样要走收工三步**。结论只写可验证事实，评价等用户验收。
-4. **封卷**：`close` 打封卷标记，此后不再改；文档靠 `history` 给的回链找回。
+`new` 按模板建好六节骨架，路径由 `show` 给出；前五节是本 skill 唯一允许手写的内容。
 
-细节见 `references/worklog.md`。
+| 节 | 写什么 |
+|---|---|
+| 背景 | 为什么做：触发它的原话 / 现象 / 链接 |
+| 待办 | 还没做的、没验证的、等别人给东西的 |
+| 下一步 | 下一个**具体动作**（文件:行号 级别），不写「继续推进」 |
+| 过程 | 踩坑与证据：带 revision + `文件:行号` 或符号名 |
+| 结论 | 做成了什么、留了什么坑；只写可验证事实，评价等用户验收 |
+| 执行记录 | 脚本维护，**禁止手写**（见「手写边界」） |
 
-## 每次收工必做（「收工」= 这一轮对用户有可见产出）
+规则：
 
-1. 改正文：这轮变化的事实都落笔，「下一步」写具体动作，不写「继续推进」。
-2. 跑 `log`：**这一轮只要改过正文就必须记**（一轮至少一条）；正文没变也能记一条推进，但要同时重写「下一步」。
-3. 回读末行（`tail -n 3 <路径>` 或 `show --id`）：时间 = 现在、说明 = 这轮的事。
+- 「执行记录」节名一个字都别动；老文档缺这一节也不用补。
+- 过程文档找不到时 `log` 只提示不失败；用 `show` 查路径，不要手写。
+- 头部只有创建时间 / 创建人、封卷标记、分类 / 标签行 —— **状态与归属以台账数据为准，别从头部读**。
+- 执行记录行格式 `- 本地时间 · 类型 · @谁 · 说明`，`@谁` 是这次动手的人、不是任务现归属；只追加、不改旧行。行首「类型」是脚本内部动作名（会见到 `release`，它就是 `set --owner ""`）；认不出就别当成新命令，按 `--help` 查。
+- 只改某条任务的正文：`show --id <任务号>` 拿路径直接改，不另建 md；已结案的用 `history --months 12`（或 `--since`）找回链接——默认只查近 3 个月，结案久了的要显式放大窗口；只读不改。
 
-交付前必须走完这三步；不走，这轮等于没发生，看板还会标停滞。
+### 收工三步（「收工」= 这一轮对用户有可见产出）
 
-**什么算一个节点**：明天你自己想不起来、或换个人接手会看不出的事，就记一条；一次状态/结论变化对应一条，不对应一次工具调用。
-`--note` 一句一条、约 60 字、含命令 / `文件:行号` / 符号名 / 结论之一。
-不记：读文件、跑 `list`、改错别字、依赖锁文件变更。
+1. 改正文：这轮变化的事实都落笔，「下一步」写具体动作。
+2. 跑 `log`：这一轮只要改过正文就必须记（一轮至少一条；纪律见下文）。正文没变也能记一条推进，但要同时重写「下一步」。
+3. 回读末行（`tail -n 3 <路径>`）：说明 = 这轮的事。执行记录行的时间是本机本地时间，别以为没记上。
 
-细节与正反例见 `references/log-note.md`。
+**什么算一个节点**：明天自己想不起来、或换个人接手会看不出的事，就记一条；一次状态 / 结论变化对应一条，不对应一次工具调用。拿不准够不够格、`--note` 不会写 → 见 `references/log-note.md`。
 
-## 分类与标签
+## 纪律
 
-`new` 时自行总结：`--category` 答「是什么类型」（单值，≤4 字，吃不准写「其他」）；`--tags` 答「涉及什么」（0~5 个，写不出就留空）。
-口径错开：tags 不许写 category 的同义词。统计只认 category，查询用 tags（包含匹配）。
+### 数据完整性（脚本管不了的，违反了数据就脏）
 
-细节见 `references/taxonomy.md`。
+- **执行记录禁手改**：只由脚本按 `new / claim / set / release / log / close` 追加，只增不改。
+- **改正文必配一条日志**：动了 worklog 的正文（改一句、补一节、改标题、修错字都算）就必须立刻跑一次 `log`。
+- **换人只能「释放 → 认领」**：`set --owner ""` 放回公共池，对方自己 `claim`；不许替别人挂名字。`set --owner <别人>`（预留转接通道，agent 一律不用）。
+- **身份由脚本自取，agent 全程不传 owner**：查自己用 `--mine`，只有查别人才传对方邮箱（`list --owner <邮箱>`）；释放传的是空串 `--owner ""`，不是身份。看到「读不到 git 身份」提示 ⇒ 让用户配 git，否则任务记到兜底身份名下。
 
-## 写操作红线
+### 人类授权（跑之前问不问）
+
+项目没有 `ledger/` ⇒ 先问「要不要建个台账记这活？」，不许自建。用户同意 ⇒ 直接跑第一条写命令，且**必须带 `--repo <项目根>`**：不带时脚本只从当前目录逐级往上找第一个含 `ledger/` 的目录，一个都没有就退 1 报「找不到台账」，绝不就地建；台账由这条写命令顺带建出来，没有 `init` 命令。之后可以不带 `--repo`，但查找是**逐级往上**的 —— 在本项目的子目录里跑可能命中上层项目的台账，拿不准就一直带 `--repo <项目根>`。
 
 | 命令 | 档位 | 要求 |
 |---|---|---|
-| `init` / `new` / `claim` / `set` | 动手类 | 执行前把完整参数复述给用户并取得确认 |
-| `log` | 免确认 | 本任务的推进 / 卡点 / 交付记录直接跑，跑完一句话交代「已记执行记录：…」；要替用户下结论、或替别人记，先问 |
-| `close` | 独立授权 | 只认用户明确的验收 / 结案 / 放弃指令；**agent 自判「干完了」不算** —— 那是交付，停在 `doing` 等用户回话 |
-| `tags --rename` | 批量写 | 先 `tags --all`，把影响条数与任务号报给用户，确认后再改 |
-| `list` / `show` / `history` / `validate` / `tags --all` | 只读 | 直接跑 |
-
-## 出错即停
+| `new` / `claim` / `set` | 动手类 | 执行前把完整参数复述给用户并取得确认 |
+| `log` | 免确认 | 本任务的推进 / 卡点 / 交付记录直接跑，跑完一句话交代「已记执行记录：…」；要替用户下结论，先问（任务不在自己名下会直接被拒） |
+| `close` | 独立授权 | 仅认明确说「结束掉 / close 掉」（完整判定见生命周期第 8 条）；说得含糊必须反问「是要结束这个任务吗？」；**agent 自判「干完了」不算** |
+| `list` / `show` / `history` / `validate` | 只读 | 直接跑 |
 
-非 0 退出就停手、原样报告，**不要绕过脚本手改 `progress.json` 或历史层**。
-**退出码 0 不等于没事**：写命令之后的同步（commit / push）失败仍返回 0，原因只写在输出里。写命令跑完必看输出，出现 `提示：` / `错误：` / `警告：` 就先用一句话说清「发生了什么 + 你要做什么」，再附原文关键行，按 `references/troubleshooting.md` 对应条目给步骤；纯告知类（如已用 `--no-verify` 提交）一句话带过。只读命令只有 `错误：` 才需要转述。
-并发冲突（文件被改动）重跑一次即可，不要用 `git pull` / `rebase` 去「解决」。
-写前会**定向取最新**：只刷新 `ledger/progress.json` 与 `ledger/history/`，`worklog/` 里已有的正文一个字都不动；
-本地有未推送的台账提交、未提交改动或未入库的同名文件时会中止 —— 按提示先提交 / 推送，或加 `--no-sync` 继续本地写。
-同一仓库里写命令**排队**执行（最多等 60 秒），并发时不要重试轰炸，等前一个跑完再重跑。
+### 故障处置（跑之后出事怎么办）
 
-细节见 `references/troubleshooting.md`。
+- **动作阶段失败（输出以 `错误：` 开头）= 该命令没生效**：不挡主任务 —— 继续手里的活，收尾时汇报「没记上，原因 …」；不绕过脚本手改文件。
+- **退出码 0 也要看输出**：出现 `提示：` / `错误：` / `警告：` 就先用一句话说清「发生了什么 + 下一步做什么」，再按 `references/troubleshooting.md` 给步骤；纯告知类一句话带过。只读命令只有 `错误：` 才需要转述。
+- **两类不是故障的退出码**：`validate` 查出问题时退出码 1，照实转述清单；提交阶段失败 ⇒ 文件已经写下去、只差进 git，让用户先提交再重跑，别说「没记上」。
+- **并发冲突**（文件被改动、抢不到锁）重跑一次即可；台账同步一律交给脚本，不要自己 `git pull` / `rebase` 去「解决」（脚本明说不代劳的几种除外，见 troubleshooting）。
+- 同一仓库里写命令排队执行，等前一个跑完再重跑。
 
 ## references（按需读，别全读）
 
 | 何时读 | 文件 |
 |---|---|
-| 要传 `--created` / `--finished` 补录时间、看到旧 `blocked`、答「停太久」要解释口径 | `references/state-model.md` |
-| 填正文前、补老任务文档、`log` 报错找不到文档 | `references/worklog.md` |
-| 拿不准一条记录够不够格、`--note` 怎么写 | `references/log-note.md` |
-| 写分类/标签、用户说标签太乱要归并 | `references/taxonomy.md` |
-| 任何非 0 退出、退出码 0 但有 `提示：` / `错误：`、并发冲突、`validate` 报错 | `references/troubleshooting.md` |
+| 任何非 0 退出、退出码 0 但有 `提示：` / `错误：` / `警告：`、并发冲突、`validate` 报错 | `references/troubleshooting.md` |
+| 传 `--created` / `--finished` 补录时间、看到旧 `blocked`、看 `--json` 里的时间字段、查别人时 owner 匹配异常、看 history 列义 / 时间窗口口径 / 旧格式行 | `references/state-model.md` |
+| 拿不准一条记录够不够格、`--note` 不会写 | `references/log-note.md` |