task-ledger 1.3.0 → 1.3.2

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` 去「解决」；只有提示明确说脚本已回滚、或说它不替你 rebase 时，才让用户手动 `git pull --rebase` / `git merge` 后 `git push`，推完再重跑。
-写前会**定向取最新**：只刷新 `ledger/progress.json` 与 `ledger/history/`，`worklog/` 里已有的正文一个字都不动；
-有未推送的台账提交时**先自动补推再写**，不要让用户先去 push。只有补推失败、或本地有用户自己的非台账提交（脚本不替他推业务提交）时才中止；有未提交的台账改动、未入库的同名文件，同样中止 —— 按提示处理，或加 `--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` |

package/package.json

@@ -1,24 +1,24 @@
 {
-  "name": "task-ledger",
-  "version": "1.3.0",
-  "description": "Task-ledger skill for coding agents: per-workspace progress tracking (ledger/progress.json, history, worklog) driven by a CLI script. Standalone install for CodeBuddy and other agents; also bundled inside the dsh-task-ledger DSH plugin.",
-  "keywords": [
-    "skill",
-    "agent-skill",
-    "task-ledger",
-    "progress",
-    "todo"
-  ],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/cq-guojia/dsh-task-ledger.git"
-  },
-  "files": [
-    "SKILL.md",
-    "README.md",
-    "scripts/",
-    "assets/",
-    "references/"
-  ]
+	"name": "task-ledger",
+	"version": "1.3.2",
+	"description": "Task-ledger skill for coding agents: per-workspace progress tracking (ledger/pool.json + owners/<hash>.json shards + owners.json index, history, worklog) driven by a CLI script. Standalone install for CodeBuddy and other agents; also bundled inside the dsh-task-ledger DSH plugin.",
+	"keywords": [
+		"skill",
+		"agent-skill",
+		"task-ledger",
+		"progress",
+		"todo"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/cq-guojia/dsh-task-ledger.git"
+	},
+	"files": [
+		"SKILL.md",
+		"README.md",
+		"scripts/",
+		"assets/",
+		"references/"
+	]
 }

package/references/log-note.md

@@ -1,6 +1,8 @@
 # 执行记录：什么算一个节点
 
 > TL;DR：一件事「明天你想不起来、换个人接手看不出」就记一条；一次状态/结论变化对应一条，不对应一次工具调用。`--note` 一句 60 字内，必须含具体对象。
+>
+> 本节全部是 **agent 口径**：脚本只拒空值、折叠空白，**不校验长度、不校验内容** —— 别指望它帮你把关。
 
 ## 判据
 
@@ -33,7 +35,7 @@
 正例：
 
 ```
---note "把 home.service 的停滞口径改成 updated 满 3 天（home.service.ts:41-52）"
+--note "改了认领即 doing（claim.py:56）"
 --note "验证通过：verify 25 项；下一步补 UI 的 overdue 标记"
 --note "卡在远端鉴权，缺 deploy key，等用户给"
 ```

package/references/state-model.md

@@ -1,44 +1,46 @@
 # 状态与时间模型
 
-> TL;DR：状态只有 `open` / `doing`；`done` 由 `close` 产生。逾期 = `started` 满 14 天、停滞 = `updated` 满 3 天、积压 = `created` 满 30 天仍 `open`，看板算、不存字段。`updated` 由 `new/claim/set/log` 刷新。owner 只取当前 git 身份。
+> TL;DR：状态只有 `open` / `doing`；`done` 由 `close` 产生。认领即 `doing`（`claim` / `new --self` 都直接置）。`started` = 首次认领时间，释放不清、重新认领不刷新。`updated` 由 `new/claim/set/log` 刷新。身份由脚本自取，agent 不传 owner。
 
 ## 状态机
 
 ```
-open ──claim──> doing ──close──> ledger/history（移出状态表）
-doing ──set --status open──> open          # 释放认领，执行记录类型 release
+new               → 公共池（open，没人认领）
+new --self        → 自己名下（doing，记 started）
+公共池 ──claim──▶ 自己名下（doing；started 空则补 now）
+set --owner ""    → 公共池（open，没人认领；started 保留）
+set --owner 别人   → 对方名下（预留转接通道，agent 不用）
+close             → 历史层 + 封卷 + 移出自己名下
 ```
 
-- `open`：已建、等认领。`doing`：已认领、在做。`done` 只由 `close` 产生。
-- **没有 `blocked` 状态**（2026-10-19 取消）。旧数据里残留的 `blocked` 读侧当进行中：`list --status blocked` 可捞出，用 `set --status doing` 归位；新写入一律拒绝。
-
-## 三个标记（看板计算，不是状态）
-
-| 标记 | 依据 | 阈值 |
-|---|---|---|
-| 积压 | `created`（建了）至今仍 `open`（没人认领） | 满 30 天 |
-| 逾期 | `started`（接任务）至今，中途更新不影响 | 满 14 天 |
-| 停滞 | `updated`（最后推进）至今 | 满 3 天 |
-
-- 真源：`packages/plugin/src/host/services/home.service.ts` 的 `BACKLOG_DAYS = 30` / `OVERDUE_DAYS = 14` / `STALE_DAYS = 3`；看板随响应下发三个天数，界面文案不硬编码。
-- 脚本不算这三个值，`progress.json` 里也不存；agent 要回答「哪些停太久」时用 `list --json` 的 `created` / `updated` / `started` 与当前时间比。
-- 老数据没有 `updated` 时，读侧回退到 `started`，再到 `created`。
+- **`started` 是外卖计时器**：首次认领盖上之后，释放（`set --owner ""`）不清、重新认领不刷新 —— 逾期时钟从首次认领一口气跑到结案，转手不重置。防的是「眼看要超时，释放掉再认领回来洗时钟」；全链路没有重置 `started` 的命令（`claim` 的 `or now()` 只在它为空时才盖值；`set` 原样保留）。接手一个已超时的任务，一接单即逾期：单子已经迟了，谁端着谁负责；责任归属看执行记录流水（谁认领 / 谁释放逐笔有记录），计时器只回答「这单迟没迟」。
+- 旧数据里的 `blocked`：读侧按 `doing` 算 —— `list --status doing` 能捞出，`--status blocked` 反而一条都匹配不到；没有归位命令，也不需要（只是读数）。
+- 认领 / 释放 / 交接一律先写目标、再删原处，崩在中间会同一任务号短暂出现在两处 —— 重跑一次同一条命令即幂等收敛（`already_done`），或按 `validate` 的提示删掉多余那份。
 
 ## 时间
 
-- **精度**：任务号、worklog 目录与文件名到分（`年月日-时分`）；其余记录到秒（`YYYY-MM-DD HH:MM:SS`）。
-- **默认不传**：`new` 创建、`claim` / `set` 推进、`log` 刷新 `updated`、`close` 结案，脚本都取当前时刻。
-- **只在补录过去时间时传**：`new --created`、`close --finished`。格式 `YYYY-MM-DD[ HH:MM[:SS]]`，脚本补全到秒；非法值拒绝。
-  **`new --created` 补录时 `updated` 会一并等于该时间**，之后记得补一条 `log`，否则看板算它停滞。
-- **筛选语义**：`list` / `history` 的 `--since` / `--until` 按**创建时间**；只给日期时，起 = 当天 `00:00:00`、止 = 当天 `23:59:59`（含整天）。
-- **history 列序**：第一列结案时间、第二列创建时间；排序按创建时间。
+- **精度**：任务号、worklog 目录与文件名到分（`年月日-时分` / `YYYYMM`）；其余记录到秒（`YYYY-MM-DD HH:MM:SS`）。
+- **默认不传**：`new` / `claim` / `set` / `log` / `close` 都取当前时刻。
+- **只在补录过去时间时传**：`new --created`、`close --finished`。格式 `YYYY-MM-DD[ HH:MM[:SS]]`，按本地墙钟给、脚本内部转 UTC。`new --created` 补录时 `updated` 一并等于该时间 —— 之后补一条 `log` 把 `updated` 刷回当前。
+  - 注意：任务号前缀与 worklog 月份目录按 **UTC** 推 —— UTC+8 下裸日期 `--created 2026-01-05` 存成 `2026-01-04 16:00:00`，任务号前缀变成 `20260104-1600`；临午夜补录要连时间一起传。
+- **筛选语义**：`list` 的 `--since` / `--until` 按**创建时间**；`history` 的按**结案时间**（历史文件按结案月归档，按创建时间比较会漏「上月建、本月结」的记录）。只给日期时起 = 当天 `00:00:00`、止 = 当天 `23:59:59`（含当天）。
+- **时区**：存盘为 UTC 的只有 —— 任务号、worklog 目录 / 文件名、台账 JSON 的 `created`/`started`/`updated`/`finished`、history 行、worklog 头部「创建」行。**执行记录行、封卷行、`list` / `history` 的人话输出都是本机本地时间**（给人看的日志行）；`--json` 原样给 UTC，由消费方自己转。存量老数据（2026-10-22 前）写的是写入者本地时间、无标记，无法与 UTC 区分。
+- **history 文件 9 列**：结案时间 / 创建时间 / 工作包（= `new --title` 的任务标题）/ 分类 / 标签 / owner / creator / 摘要 / 过程文档；排序与 `--since` / `--until` 按**结案时间**。（`history` 命令的人话输出只展示其中几列：结案时间、负责人、标题。）
 
 ## 任务号
 
-`年月日-时分` + 标题里的字母/数字/汉字 + 4 位随机码（如 `20261015-1430-登录接入-sso-7f3a`）。要指定就传 `--id`（小写字母、数字、汉字、连字符）。
+`年月日-时分` + 标题里的字母 / 数字 / 汉字 + 4 位随机码（如 `20261015-1430-登录接入-sso-7f3a`）。随机码必须保留：任务号在**公共池、我自己的分片**两处查重（并发安全闸门），并直接判**过程文档路径** `worklog/<创建月>/<去前缀名>.md` 是否已存在 —— 在办、已结案任务的文档都留在磁盘上，命中即号被占过（复用会撞同一篇文档、日后让 `close` 误判 `already_done` 变僵尸）。O(1)，不必扫历史。想自己指定就传 `--id`（小写字母、数字、汉字、连字符）。
 
 ## 身份
 
-- owner 恒取 `git config user.name`；读不到直接报错，**不做兜底**（先让用户配好 git）。
-- 取身份的命令：`new`（记 creator）、`claim`、`set`、`close`、`log`、`list --mine`、`history --mine`。`history --owner <别人>` 是只读查询，不校验身份。
-- `set` / `close` / `log` 都校验「owner 是不是你」；不是你的、或任务还没人认领，直接拒绝。
+- 主键 = **git 邮箱**（`git var GIT_COMMITTER_IDENT` 里的 email，退回 `git config user.email`），归一化（去空白 + 小写）后比对。
+- 读不到邮箱**不报错**：走兜底链（`USER`/`LOGNAME` → `getpass` → 主机名 → 字面 `default`）并出一条提示，命令照常跑完。看到提示要告诉用户配好 git，否则任务记到兜底身份名下。
+- 全站只认 git 邮箱这一个身份键；`list --owner` / `history --owner` 是归一化后的**精确匹配**，没有 `me` 缩写，「自己」用 `--mine`。
+- `close` / `log` 只对自己名下的任务生效，不在名下直接拒绝；`set --owner ""` 对已在公共池里的任务是幂等空转（退 0）；`set --owner <自己>` 会把公共池里的任务认领到自己名下。
+
+## 历史层
+
+- 按**结案时间**分月存放，9 列（creator 在 owner 之后）；`close` 从任务直写分类 / 标签终值。
+- 存量平铺历史文件只读兼容、永不重写；`history` 连同它在内、按下面的月份区间合并。
+- **查询区间**：`history` 先由时间参数算出要读的月份文件，再逐个「存在才读、缺月跳过」，不扫磁盘。无时间参数默认最近 3 个自然月；`--months N`（近 N 月）与 `--since/--until`（结案时间闭区间）二选一；一次最多读 13 个历史文件（按月分文件，不区分连续/分散，只数总数），超出直接报错、不读任何文件。末列文档链接只按**文件名**消费（取 basename），链接里的 `../worklog/<年月>/` 前缀只为阅读器跳转服务，解析时忽略。
+- `history --json` 直接按文件现状解析，旧行没有的列不编造；`close` 追加历史行时才会把旧行升级补上 creator。