task-ledger

台账只管三件事：谁在做、做到哪、什么时候建 / 结。状态只在台账 JSON（pool.json + 每人分片），叙事只在 worklog，全部经脚本改。

台账文件

任务字段：标题 / creator / owner / 状态 / 时间（created started updated finished）/ 分类标签 / 过程文档路径。
一人一份：自己只改自己分片；池里那条是「未认领的登记」，谁都不改它 —— 要动先 claim。

前五节你直接编辑；末节「执行记录」只由脚本追加，一个字都不许手写。
不另建副本、不手改状态表和历史、不自己拼 worklog 文件名（new 会建好并给路径）。
台账 ≠ 产出物：成果按所在项目自己的约定落盘，台账只放「建/做/结」和指向成果的链接。

什么时候用

❌ 项目没有 ledger/ 且只是临时一次性的事 → 先问要不要建台账（没有 init：第一条写命令会自动把台账建好）。
❌ 只想改某任务正文 → 用 show 拿路径与全文直接改，不要另建 md；已结案的用 history 找链接。

意图 → 命令

命令怎么调

python3 <本 SKILL.md 所在目录>/scripts/progress.py <子命令> --repo <当前工作区>

子命令：new claim set log close list history show tags validate。
定位项目：--repo <目录> 优先；不给就按「git 仓根 → 含 docs/ 的上级」自己找，传子目录会抬到台账根。
参数细节一律看 <子命令> --help（不要凭记忆编参数）。
new / claim / set / show 返回 worklog 路径 + 全文；log 回一行确认、close 回结案摘要，list / history 只回摘要不吐正文。

铁律

• 状态只有 open / doing；done 只能由 close 产生。没有 blocked 状态：逾期 = started 满 14 天、停滞 = updated 满 3 天、积压 = created 满 30 天且仍 open，都由看板按时间算，台账里不存、不手改；卡在哪写进正文。
• log 就是刷新 updated 的动作：该记不记，任务会被看板标成停滞。
• owner = 当前 git 邮箱（git var GIT_COMMITTER_IDENT，退回 git config user.email），不能由外部传入；在 git 仓库里读不到就报错（与 git 自己提交不了对齐）。只能动自己分片里的任务（open 的先 claim），不在你分片里的直接拒绝 —— 不要绕过脚本改 JSON。
• 换人只能「释放 → 认领」：set --status open 把任务搬回 pool.json，对方自己 claim；不许替别人挂名字。脚本确实留着 set --owner（看板 / 维护者通道，当前没有任何端在用），agent 一律不得使用 —— 它能把任务直接写进别人分片，绕过释放 → 认领。
• 「执行记录」禁手改：只由脚本按 new / claim / set / release / log / close 追加，只增不改；手写＝伪造时间线，且不刷新 updated。
• 改正文必配一条日志：只要动了 worklog 的正文（改一句、补一节、改标题、修错字都算），必须立刻跑一次 log。没有对应日志的正文改动 = 这轮没做完 —— 时间线上会留下你改过、但没人知道为什么改的空洞。（纪律条款，脚本不校验，别指望它兜底。）
• 升级前建的老 worklog 没有这一节：不用你补，脚本第一次记时自动在文末补一节；文档丢失时 log 报错，用 show 查路径，不要手写。（updated 一般在报错前就刷新了；若这条命令同时触发过写前取最新，失败收尾会把整份文件回滚，updated 也就跟着回退 —— 以 show 看到的为准。）
• 旧数据里的 blocked：list --status doing 会一并捞出（读侧当进行中），--status blocked 也能精确定位；用 set --status doing 归位。看板侧同样按进行中统计。

细节见 references/state-model.md。

过程文档

1. 建档：new 按模板建六节骨架并把路径写进任务对象（worklog 字段）。
2. 推进：你直接编辑前五节，标题不许改名（脚本不校验六节标题，validate 只查骨架与缺失）；每改一轮正文就配一条日志——同一次编辑动作里连改多处只记一条，改完立刻 log --note "这轮做了什么"。
3. 交付（待验收）：任务仍留 doing，「待办」写「待用户验收」，「下一步」写清验收该看什么；这轮照样要走收工三步。结论只写可验证事实，评价等用户验收。
4. 封卷：close 打封卷标记，此后不再改；文档靠 history 给的回链找回。

细节见 references/worklog.md。

每次收工必做（「收工」= 这一轮对用户有可见产出）

1. 改正文：这轮变化的事实都落笔，「下一步」写具体动作，不写「继续推进」。
2. 跑 log：这一轮只要改过正文就必须记（一轮至少一条）；正文没变也能记一条推进，但要同时重写「下一步」。
3. 回读末行（tail -n 3 <路径> 或 show --id）：说明 = 这轮的事；时间是UTC（北京时间就是「现在 − 8 小时」，别当成没记上）。

交付前必须走完这三步；不走，这轮等于没发生，看板还会标停滞。

什么算一个节点：明天你自己想不起来、或换个人接手会看不出的事，就记一条；一次状态/结论变化对应一条，不对应一次工具调用。
--note 一句一条、约 60 字、含命令 / 文件:行号 / 符号名 / 结论之一（纪律条款：脚本只拒空值，不限长度）。
不记：读文件、跑 list、改错别字、依赖锁文件变更。

细节与正反例见 references/log-note.md。

分类与标签

new 时自行总结：--category 答「是什么类型」（单值：中文按字符 ≤4、纯英文按单词 ≤3，吃不准写「其他」）；--tags 答「涉及什么」（0~5 个；写不出就不传这个参数，传空串等于没传）。
口径错开：tags 不许写 category 的同义词（纪律条款，脚本不校验）。统计只认 category，查询用 tags（包含匹配）。

细节见 references/taxonomy.md。

写操作红线

出错即停

非 0 退出就停手、原样报告，不要绕过脚本手改台账 JSON（pool.json / owners/）或历史层。
退出码 0 不等于没事：写命令之后的同步（commit / push）失败仍返回 0，原因只写在输出里。写命令跑完必看输出，出现 提示： / 错误： / 警告： 就先用一句话说清「发生了什么 + 你要做什么」，再附原文关键行，按 references/troubleshooting.md 对应条目给步骤；纯告知类（如已用 --no-verify 提交）一句话带过。只读命令只有 错误： 才需要转述。
并发冲突（文件被改动）重跑一次即可，台账同步一律交给脚本，不要自己用 git pull / rebase 去「解决」；只有提示明确说脚本已回滚、或说它不替你 rebase 时，才让用户手动 git pull --rebase / git merge 后 git push，推完再重跑。
写前会定向取最新：只刷新本次要写的台账文件（owners.json、自己的分片、认领/释放涉及的 pool.json、close 当月的 history/）以及本次命令要改写的那一篇 worklog（log / claim / set / close / tags --rename；干净就刷成最新，本地有未提交的手写改动则先 stash → 快进 → 叠回，冲突即中止）。worklog/ 里其余已有的正文一个字都不动，只补本地缺的新文件；
有未推送的台账提交时先自动补推再写，不要让用户先去 push（push 是分支级的：本地属于用户自己的提交会一并被推走，脚本只提示、不 rebase）；补推失败、本地台账有未提交改动、未入库的同名文件，都会中止 —— 按提示处理，或加 --no-sync（写在子命令前后都行）继续本地写。
同一仓库里写命令排队执行（最多等 60 秒），并发时不要重试轰炸，等前一个跑完再重跑。

细节见 references/troubleshooting.md。

references（按需读，别全读）