todo-board

TODO 队列看板：把排期判断做成可维护的数据 + 渲染它的本地网页，替代一次性的静态优先级表。零依赖（纯 Node ≥20）、本地优先、离线可用。

[!NOTE] 分发只有 npm；一次 init 物化之后，工具对你的仓只是脚本——日常操作知识全部落在你的仓里，不依赖任何外部站点（产品面宪法 docs/product.md）。本仓自己的待办也跑在同一套管线上；驱动它们的 agent 技能正本住本仓 [skills/todo-board/](skills/todo-board/（物化到 ~/.agents/skills/todo-board，evals/ 开发载荷不进 npm 包——ADR 案例五）。

安装

npm i -g todo-board        # 得全局命令 todo-board（Node ≥20）
# 免装试用：npx todo-board <子命令>
# 升级：npm i -g todo-board@<新tag>，然后 collect 干跑对账收尾

快速开始（在一个已存在的仓库里）

todo-board init                                        # 干跑：看清会落地什么
todo-board init --write                                # 物化实例居所（config + 白名单 gitignore 两件）
# 照模板建首条 TODO/YYYYMMDD-HHMM-{slug}.md（模板：todo-board skill 或包内 adopt/）
todo-board collect                                     # 干跑对账：[new] 应出现首条（仓内任意位置，免旗标）
todo-board collect --write
todo-board refresh                                     # 再生 + 注入页面
todo-board serve                                       # 起看板（自动开浏览器）

init 只落地居所事实件：.todo-board/collect.config.toml（扫描几何种子，改 dirs 等仓事实）+ .todo-board/.gitignore（白名单——tracked 只此两件，快照与页面是再生件不进 git）。纪律面不物化进仓：操作卡 / 队列 README / 条目模板 / 溯源戳一概不落地，正本 = 用户级 todo-board skill（或 todo-board docs）。已有文件一律不覆盖——冲突全量列清、零落地。

日常

| 动作 | 做法 | |---|---| | 建档 | 照模板写 YYYYMMDD-HHMM-{slug}.md（skill assets 或包内 adopt），从档头改起（六键 + created/blockedBy 必填） | | 收口 | 档头加一行 status: done（或 rejected）——离板进历史，删该行即复活 | | 对账 | todo-board collect（[new]/[drop]/[fact] 逐行弄清再 --write） | | 查询 | todo-board query p=P0,P1 s=S,M；--json 机器输出；history 查收口件 | | 看板 | todo-board serve（http 直读磁盘档头，PORT= 换端口） |

手册

todo-board docs               # 六篇随包手册（usage / format / config / page / collect / spec），离线可读
todo-board docs usage         # 从这篇读起
todo-board <command> --help   # 每个子命令的自描述

边界

• 零依赖：不引入 CLI 框架，全局安装即一个裸包；file:// 双击即开；
• 机器不代填判读：新条目判读不全 skeleton 拒写，档头写坏当场拒跑，已有文件不覆盖；
• 条目 = 档头带 queue 键的 md（成员资格内容声明，目录只是整理惯例）；收口 = 档头 status 声明，覆盖成员资格。

Commit 闸

commit message 一律英文——.githooks/commit-msg 闸强制（物化自 {ls-gates}:publish/carriers/commit-msg，字节同步锁在 birth 侧；commit 需 node 运行时）。新 clone 由 npm test 自动接线（test 链首步 = 幂等安装器；发布面 package.json 刻意不挂 prepare——scripts 随 tarball 发布且 prepare 在 pack 流程执行，承 UKP 教训）；逃生门 git commit --no-verify。