| name | ledger-flow |
| user-invocable | true |
| argument-hint | [対象の台帳・計画文書のパス(任意)] |
| description | 進捗台帳と計画・引き継ぎ文書の運用ルール。todo・計画書・テストリスト・STATUS 等のチェックボックス付き文書を作る/更新する、「台帳を更新して」「進捗をまとめて」「引き継ぎ文書を書いて」「todo を整理して」と頼まれる、作業完了で台帳を消し込む、スナップショット文書(STATUS/RESUME)を発行する、といった場面で参照する。記法の凡例を一本化し、消し込み先を1ファイルに固定し、完了主張に証跡ポインタを義務付け、完了文書を closed で閉じる。台帳が緑を偽らない・履歴が消えない・読み手が考古学をしないための規範。コミット粒度は commit-flow、教訓の記録は review-feedback が担う。 |
ledger-flow — 進捗台帳と文書ライフサイクルの運用
このスキルの目的
進捗台帳(todo・計画書・テストリスト)とスナップショット文書(STATUS・引き継ぎ・再開メモ)は、放っておくと決まった壊れ方をする:記法が場当たりに増える、同じ進捗が複数ファイルに分散して食い違う、完了主張に証跡が無い、更新がコミットに遅行する、完了済み文書が open のまま化石になる。壊れた台帳は「済んだ作業を未了と報告する」か「未検証を緑と報告する」かのどちらかで嘘をつく。ここでは台帳が嘘をつかないための運用を定める。
1. 記法の凡例は1箇所で定義し、増やさない
- チェックボックスの意味は台帳の冒頭(または台帳群の README)に1回だけ定義する。標準は3値:
[ ] 未着手/未検証、[~] 部分完了(何が残るかを同じ行に書く)、[x] 完了(実装と検証の両方が実在する)。
- 完了圧で凡例を増やさない。
[対象外] [保留] のような独自マーカーの新設や、「保留項目を判断記録へ移して箱の分母から外す」操作は、チェックボックスを数える機械判定(hook・自動チェック)と非互換になり、同一指摘の無限ループや誠実さの疑義を生む。スコープ外にする項目は、マーカー発明ではなく行ごと「対象外」節へ移し、除外理由と再登録条件を書く。分母から外したことが読み手に見える形にする。
[x] を付ける条件は「実装と検証の証跡が両方ある」。迷ったら [~] に倒す。
2. 進捗の真実源は1ファイルに固定する
- 計画書・テストリスト・集約 STATUS のように同じ作業を映す文書が複数あるときは、消し込む台帳を1つ決め、他は参照だけにする。全部を並行更新しようとすると必ずどれかが遅れ、「計画書では全部未着手・STATUS では全部完了」の食い違いが起きる。
- 計画書(plan)は write-once でよい。進捗は台帳側で消し込み、計画書には冒頭に「進捗は <台帳> を見よ」と1行書く。
- 集計値(96/103 等)を別文書へ転記しない。転記した数字は元と乖離する。載せるなら「n/m は <台帳> の集計を正とする」と出典を書く。
3. 完了主張には証跡ポインタを付ける
[x] や「PASS」「検証済み」の記録には、それを証明する成果物の所在(実行ログのパス、テスト名、コミットハッシュ、CI run の URL)を同じ行か直後に書く。- 証跡の無い PASS 記録は誤読の温床になる(実行結果テーブルの記号を読み違えて、走ってすらいないケースを PASS と記録した実例がある)。記録した時点でログが実在することを確認する。外部ランナーの結果を転記するときは、記号の意味(スキップ/非対応/失敗)を凡例で確認してから写す。
4. 台帳更新はコミット・状態変化と同時に行う
- 作業をコミットしたら、その場で対応する台帳行を消し込む。「後でまとめて更新」は必ず遅行し、台帳が「済んだ作業を未了と報告する」状態になる。
- 逆に、コミットより先に
[x] を付けない(検証前の先付けは緑詐称)。消し込みとコミットは同じ作業単位の中で対にする。
5. 文書のライフサイクルを閉じる
- 完了・不要になった文書は closed で閉じる: 冒頭に
closed (YYYY-MM-DD), successor: <後継文書 or なし> を1行足す。閉じない文書は、未完了の箱や「実行中」の記述を残したまま化石化し、後から読む者に「これは生きているのか」の考古学を強いる。
- スナップショット文書(STATUS・集約報告)には発行日と有効条件を書く。「〜が全て完了」という宣言は発行後の事実で失効しうる。失効に気付いたら本文を書き直すのではなく、冒頭に失効マークと理由を足す(発行時点の記録としては残す)。
- 再開の起点は1文書に固定する。「最新は別文書を読め」の多段リダイレクトと、セッションローカルな場所(リポジトリ外)への参照を作らない。再開メモを書き直すときは古い方を closed で閉じる。
- 台帳を別用途に転用するときは、先に退避してから上書きする。台帳が VCS 管理外に置かれる運用(このスキル群の tasks/ 規約)では、上書きした瞬間に履歴が消える。エポックが変わるなら
<name>-<epoch>-done.md に写してから空ける。
6. 機械検査に落とせるものは落とす
未チェック残・欠番・凡例違反の検査は決定論で書ける。loopeng-extract / test-design の採番台帳ゲート(hooks/loopeng-extract-gate.sh、hooks/test-design-extract-gate.sh)が同型の実装例で、- [ ] の残存と ID の欠番を PreToolUse で機械ブロックしている。恒常運用する台帳には同型の検査を用意し、目視の数え上げに置き換える。
やらないこと
- 台帳のためだけの新フォーマット発明(既存の Markdown チェックボックスで足りる)。
- 全文書の並行更新(§2 に反する)。
- 進捗率を見栄えのために informational 項目で水増しすること(分母は実装対象のみ。informational は別枠で数える)。
完了条件
台帳を触った作業の完了時に、次が全て成り立っている:
- 消し込んだ行の
[x]/[~] に証跡ポインタがある。
- 対応するコミット(あれば)と台帳の状態が一致している。
- 完了・失効した文書に closed / 失効マークが付いている。
- 同じ進捗を映す他文書との食い違いが無い(他文書は参照に置き換わっている)。
