PJR-GH26 台帳の差分レビュー代替手段を決めて実装する
1. 概要
PJR-ES57 の分割8。一覧が非追跡になることで失われる台帳全体の差分レビューについて、代替手段を決めて運用ガイドへ反映する。
prj-0001:pjr-es57-register-file-ssot-migration の分割8。一覧が生成物となり追跡対象から外れることで、台帳全体の変更を1ファイルの差分で追えなくなる。これは prj-0001:pjr-9y7g-register-item-file-as-ssot で選択肢 B の懸念として挙げた点であり、成立条件として代替手段を決めることが求められている。
2. 完了条件
- 台帳の変更を確認する手段が決まっている。個票の履歴で追う、pull request で frontmatter 差分を確認する、一覧表示コマンドを用意する等の選択肢が比較されている。
- 選定した手段が実装または運用手順として整備されている。
- 手段が specdojo:register-operation-guide へ記載され、いつ何を見れば台帳の変化を追えるかが分かる。
- 監査時に、ある期間の登録項目の追加・状態遷移を再構成できる。
3. 作業内容
| No | 作業 | 担当 | 状態 | メモ |
|---|---|---|---|---|
| 1 | 代替手段の選択肢を洗い出して比較する | ARC | done | 個票履歴 / PR 差分 / 一覧表示コマンドを、確認の容易さ・実装コスト・監査耐性で比較 |
| 2 | 採用する手段を決める | ARC | done | 3 手段の役割分担（用途別の併用）を採用。単独案は監査要件を満たさない |
| 3 | 実装または運用手順を整備する | ARC | done | register history を CLI へ追加（src/register-history.ts） |
| 4 | 運用ガイドへ反映する | ARC | done | specdojo:register-operation-guide に「台帳の変更を追う」を追加 |
4. 対応結果
- 代替手段の選択肢を次の観点で比較した。
| 選択肢 | 確認の容易さ | 実装コスト | 監査への耐性 |
|---|---|---|---|
A. 個票の Git 履歴を直接読む（git log -p） | 1項目の経緯は追いやすいが、台帳全体は項目数だけコマンドが要る | 不要 | 生データとしては完全だが、期間内の全項目の再構成は手作業になる |
| B. pull request で個票 Frontmatter 差分を見る | 変更単位でまとまり、レビューには最適 | 不要（既存の PR 運用） | PR を経ない直接 commit を取りこぼす。過去期間の遡及集計に向かない |
C. 一覧表示コマンド（register history） | 期間・項目・種別で絞って1行1イベントで読める | 中（新規モジュールとテストが必要） | 期間指定で追加・状態遷移を機械的に再構成でき、JSON で証跡化もできる |
- 単独では完了条件（監査時に、ある期間の登録項目の追加・状態遷移を再構成できる）を満たす選択肢が無いため、用途別に3手段を併用する形を採用した。台帳全体の把握と監査は C、変更の妥当性レビューは B、1項目の深掘りは A とし、役割分担を運用ガイドへ明記した。
- C を実装した。
specdojo register historyは登録簿ディレクトリの Git 履歴（git log --reverse --name-status）を走査し、各コミット時点と親コミット時点の個票 Frontmatter を比較して、項目単位のadded/updated/removedを古い順に出力する。比較対象は生成一覧の列（ステータス・タイトル・説明・分類・優先度・担当・登録日・期限・完了日・結論）に揃えたため、表を正本にしていた時期の一覧差分と同じ粒度になる。 - 監査用途に
--since/--until（期間、当日を含む）、--id（項目の限定）、--status-only（追加・削除・状態遷移のみ）、--limit（走査コミット数の上限）、--json（機械可読出力）を用意した。--status-onlyは変更内容も遷移に関わる項目（status/type/completed/conclusion）へ絞り、本文推敲の差分を落とす。 renumberによる ID 付け替えは、フィールド値が変わらず rename としてのみ現れるため、idの変更として明示的にイベント化した。生成物（generated/配下）と個票以外のファイルは対象外とした。- 実装は純粋関数（ログ解析・差分生成・整形）と Git 呼び出しを分離し、
tests/src/register-history.test.tsで追加・状態遷移・本文のみの変更・renumber・削除・絞り込み・整形を検証した。 - 運用ガイドに「台帳の変更を追う」を追加し、目的別の手段、コマンド例、出力の読み方、個票化前（
pjr-index.mdが正本だった期間）の履歴の参照方法を記載した。CLI リファレンスにもregister historyとオプションを追加した。
5. 関連ドキュメント
- prj-0001:pjr-es57-register-file-ssot-migration: 分割元の移行タスク
- prj-0001:pjr-9y7g-register-item-file-as-ssot: 代替手段の決定を成立条件とした決定
- prj-0001:pjr-rzr3-pjr-index-as-generated-view: 一覧が非追跡になる変更
- prj-0001:pjr-1d0c-pjr-index-wikilink-broken: 同じくRZR3/9P5Qで一覧が非追跡になったことに起因する別問題（wikilink解決）。本項目の対応方針検討時に候補として参照したが、
register historyはwikilink解決を代替しないため対象外とした - specdojo:register-operation-guide: 反映先の運用手順