task-ledger 1.3.0 → 1.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/README.md +29 -247
  2. package/SKILL.md +173 -88
  3. package/package.json +22 -22
  4. package/references/log-note.md +3 -1
  5. package/references/state-model.md +29 -27
  6. package/references/troubleshooting.md +97 -32
  7. package/scripts/ledgerkit/__init__.py +0 -0
  8. package/scripts/ledgerkit/actions/__init__.py +0 -0
  9. package/scripts/ledgerkit/actions/atom.py +154 -0
  10. package/scripts/ledgerkit/actions/bootstrap.py +26 -0
  11. package/scripts/ledgerkit/actions/claim.py +82 -0
  12. package/scripts/ledgerkit/actions/close_task.py +180 -0
  13. package/scripts/ledgerkit/actions/guard.py +136 -0
  14. package/scripts/ledgerkit/actions/handoff.py +74 -0
  15. package/scripts/ledgerkit/actions/list_tasks.py +53 -0
  16. package/scripts/ledgerkit/actions/log_progress.py +60 -0
  17. package/scripts/ledgerkit/actions/new_task.py +120 -0
  18. package/scripts/ledgerkit/actions/query.py +33 -0
  19. package/scripts/ledgerkit/actions/query_history.py +172 -0
  20. package/scripts/ledgerkit/actions/registry.py +82 -0
  21. package/scripts/ledgerkit/actions/release.py +51 -0
  22. package/scripts/ledgerkit/actions/result.py +88 -0
  23. package/scripts/ledgerkit/actions/set_task.py +43 -0
  24. package/scripts/ledgerkit/actions/show_task.py +27 -0
  25. package/scripts/ledgerkit/actions/validate.py +224 -0
  26. package/scripts/ledgerkit/core/__init__.py +0 -0
  27. package/scripts/ledgerkit/core/history_md.py +350 -0
  28. package/scripts/ledgerkit/core/identity.py +27 -0
  29. package/scripts/ledgerkit/core/ids.py +58 -0
  30. package/scripts/ledgerkit/core/labels.py +79 -0
  31. package/scripts/ledgerkit/core/paths.py +93 -0
  32. package/scripts/ledgerkit/core/time.py +102 -0
  33. package/scripts/ledgerkit/core/worklog_md.py +232 -0
  34. package/scripts/ledgerkit/env.py +93 -0
  35. package/scripts/ledgerkit/errors.py +15 -0
  36. package/scripts/ledgerkit/notices.py +28 -0
  37. package/scripts/ledgerkit/shell/__init__.py +0 -0
  38. package/scripts/ledgerkit/shell/cli.py +259 -0
  39. package/scripts/ledgerkit/shell/gitops.py +655 -0
  40. package/scripts/ledgerkit/shell/merge.py +266 -0
  41. package/scripts/ledgerkit/shell/presync.py +23 -0
  42. package/scripts/ledgerkit/shell/render.py +165 -0
  43. package/scripts/ledgerkit/shell/runner.py +225 -0
  44. package/scripts/ledgerkit/store/__init__.py +0 -0
  45. package/scripts/ledgerkit/store/atomic.py +130 -0
  46. package/scripts/ledgerkit/store/dirty.py +108 -0
  47. package/scripts/ledgerkit/store/history_store.py +189 -0
  48. package/scripts/ledgerkit/store/json_store.py +166 -0
  49. package/scripts/ledgerkit/store/locks.py +64 -0
  50. package/scripts/ledgerkit/store/owners_index.py +114 -0
  51. package/scripts/ledgerkit/store/task_store.py +28 -0
  52. package/scripts/ledgerkit/store/worklog_store.py +168 -0
  53. package/scripts/progress.py +8 -3109
  54. package/references/taxonomy.md +0 -26
  55. package/references/worklog.md +0 -39
package/references/taxonomy.md DELETED
@@ -1,26 +0,0 @@
1
- # 分类与标签
2
-
3
- > TL;DR：`category` 答「是什么类型」（单值，≤4 字，吃不准写「其他」）；`tags` 答「涉及什么」（0~5 个，写不出就留空）。两者口径错开；统计只认 category，查询用 tags。
4
-
5
- 为什么不设枚举：本 skill 跨所有工作区（开发 / 运维 / 个人事务 / 调研备忘），固定分类覆盖不全。分类与标签由 agent 在 `new` 时按本节口径自行总结；脚本只校验形态（≤4 字 / 纯英文 ≤3 词 / ≤5 个），不校验语义。
6
-
7
- ## 两条边界
8
-
9
- 1. **口径错开**：tags 不许写 category 的同义词 —— `category=缺陷修复` 时，tags 别再写「bug修复」。
10
- 2. **统计与查询分工**：统计只认 category（精确匹配，同值才能比较）；tags 只做查询（包含匹配，「bug」命中「bug修复」正是要的效果）。
11
- 3. **数量不设下限**：3~5 个是目标不是硬指标；设下限会逼出凑数标签。
12
-
13
- ## 写法口径
14
-
15
- - 名词性短语，不带时态、不用动词收尾：写「缺陷修复」，不写「修复了」「修 bug」。
16
- - 中文优先，不中英混排；纯英文 ≤3 个单词（`fix a bug` 可以，`fix a login bug` 超了）。
17
- - 标签之间用**逗号**分隔；空格属于英文多词标签自身（`--tags "fix a bug,docker"`）。
18
-
19
- 正例：`--category 缺陷修复 --tags "镜像拉取,超时重试"`
20
- 反例：`--category 已完成登录修复`、`--tags 修 bug`
21
-
22
- ## 时机与修正
23
-
24
- - `new` 建档时一并总结（标题 + 背景语义最全）。
25
- - `close` 可用 `--category` / `--tags` 覆盖修正一次；终值写进 history 行的「分类 / 标签」列。
26
- - 日常漂移：先 `tags --all` 看全量频次与低频变体，再 `tags --rename 旧 新` 归并（只改在办任务，已封卷文档不动；批量写，见写操作红线）。
package/references/worklog.md DELETED
@@ -1,39 +0,0 @@
1
- # 过程文档（worklog）
2
-
3
- > TL;DR：六节固定；前五节 agent 改，末节「执行记录」只由脚本写。改完正文必须 `log`，交付也要 `log`。老文档缺末节时脚本自动补。
4
-
5
- ## 六节结构
6
-
7
- | 节 | 写什么 |
8
- |---|---|
9
- | 背景 | 为什么做：触发它的原话 / 现象 / 链接 |
10
- | 待办 | 还没做的、没验证的、等别人给东西的 |
11
- | 下一步 | 下一个**具体动作**（文件:行号 级别），不要写「继续推进」 |
12
- | 过程 | 踩坑与证据：带 revision + `文件:行号` 或符号名 |
13
- | 结论 | 做成了什么、留了什么坑；只写可验证事实，评价留给用户验收 |
14
- | 执行记录 | 脚本维护，**禁手改** |
15
-
16
- 标题结构不能改名。建档只由 `new` 做（按 `assets/worklog.md` 模板生成骨架并写入状态表 `worklog` 字段）。
17
-
18
- ## 执行记录
19
-
20
- - 一行一事件：`- 2026-10-19 12:08:33 · log · @GuoJia-Agent · 说明`。
21
- - 类型：`new`（建）/ `claim`（认领）/ `set`（改状态、owner 变更）/ `release`（`set --status open` 释放）/ `log`（手记）/ `close`（结案）。
22
- - **只追加、不改旧行**：`@谁` 记的是这次动手的人，不是任务现 owner —— 释放/重新认领后旧记录仍留在原负责人名下。
23
- - 老 worklog 没有这一节：脚本第一次记时在文末自动补一节（正文不迁移），agent 不用也不许手动加。
24
- - 过程文档丢失：`log` 报错退出（`updated` 已刷新），用 `show --id` 查路径，**不要手写这一节**。
25
-
26
- ## 编辑既有任务
27
-
28
- 1. `show --id` 拿任务 JSON + worklog 全文与路径；
29
- 2. 直接改前五节；
30
- 3. **立刻** `log --id <任务号> --note "补了…/改了…"`。
31
-
32
- **改正文必配一条日志**：只要动过正文（哪怕一处错字、一个标题），就必须跟一条 `log`；没有日志的正文改动等于没发生过。同一次编辑动作里连改多处，只记一条。
33
-
34
- 已结案任务：worklog 已封卷、不在状态表，用 `history` 给出的回链找回，只读不改。
35
-
36
- ## 交付与封卷
37
-
38
- - **交付（待验收）**：任务仍留 `doing`；「待办」写「待用户验收」，「下一步」写清验收看什么（哪条命令 / 哪个文件）；按收工三步记一条 `log --note "已交付待验收：…"`。
39
- - **封卷**：`close` 打封卷标记，此后不再修改；历史行按结案时间写入 `ledger/history/<年月>.md`（存量 `ledger/PROGRESS-HISTORY.md` 只读兼容，不再写入）。