PJR-JHSC exec のイベント粒度の理由を確認し規範文書へ記録する
1. 概要
exec のイベントはイベント単位でファイルへ分けられ、606 ファイルに達している。しかしこの粒度を選んだ理由が、文書にもコードのコメントにも残っていない。
理由が分からない状態では、将来の見直しを安全に行えない。ファイル数を減らせるのか、減らすと何が壊れるのかを判断できない。
現状の設計理由を調査し、規範文書へ記載する。
2. 完了条件
- イベントをイベント単位で分ける理由が規範文書へ記載されている。
- タスクごとの集約が可能かどうかの判断と、その根拠が記録されている。
- 集約する場合は移行方法が定められ、既存の履歴が失われない。
- 集約しない場合は、将来同じ検討が繰り返されないよう理由が明示されている。
3. 作業内容
| No | 作業 | 担当 | 状態 | メモ |
|---|---|---|---|---|
| 1 | 設計理由の調査 | ARC | done | 実装、導入時のGit履歴、関連文書から復元した |
| 2 | 集約可否の判断 | ARC | done | 技術的には可能だが、運用上の問題が未確認のため現時点では集約しない |
| 3 | 規範文書への記載 | ARC | done | システム設計横断ルールとexec運用ガイドへ記載した |
| 4 | 集約する場合の移行 | ARC | done | 集約しないため移行対象なし。将来の再検討条件を記録した |
3.1. 実装から読み取れる事実
ファイル名は <タイムスタンプ>_<実行者>_<タスクID>_<種別>_<乱数>.json の形式である。書き込みは新規作成のみで、既存ファイルへ追記しない。状態は全イベントを畳み込んで再構成する。
イベントソーシングの実装であり、追記をファイルの追加で表現している。
3.2. 並行性は理由にならない
1 つのタスクを複数の agent が同時に実行することは、claim による排他で起こらない。したがって同一タスクのイベントが同時に書かれることはない。
exec run --parallel で複数タスクを並行実行する場合も、タスクが異なればファイルも異なる。タスクごとに 1 ファイルとしても競合しない。
3.3. 調査で確認した理由
初期実装コミットf42bd005は、実行状態をeventからfoldする仕組みと1 event 1 JSONの書込みを同時に導入した。続くa66855baの利用ガイドでは、設計目標を「Gitネイティブなプロジェクト管理」「append-only実行ログ」「deterministic生成物」としている。task単位でなくevent単位にした固有の理由は、コミットメッセージやコードコメントには残っていなかった。
現行実装と履歴から確認できる理由は、状態変更の保存境界を1 eventにそろえ、過去のファイルへ追記せず、新しいeventを新規ファイルとして追加するためである。これにより、Git差分では1回の遷移が1ファイル追加になり、schema違反や破損はファイル名付きで特定され、reopenなどの訂正も過去eventの書換えではなく後続eventとして残る。
一方、worktree統合時の競合回避や同一taskの並行実行はevent単位である必然性を示さない。task単位のファイルでも排他は設計可能である。この点を理由として記録しない。
3.4. register との対比
register のイベントは個票の Frontmatter に配列として保持され、pjr-rulebook に理由が明記されている。
項目ごとの配置により、イベントごとの追加ファイルを作らず、異なる項目を並行更新したときの共有ログ競合を避ける。
exec 側にも同等の記述が要る。粒度が異なること自体は問題ではないが、理由が説明されていないことが問題である。
3.5. 集約可否の判断
task単位への集約は技術的には可能だが、現時点では集約しない。
- 2026-09-01時点の606ファイルはJSON本文の合計が227,784 byte、ディスク使用量が2.5 MiBである。
- doc-indexはMarkdownとYAMLだけを走査するため、event JSONのファイル数はdoc-indexへ影響しない。
- 読取処理は1ファイル1eventをschema検証してfoldし、書込処理は常に新規ファイルを作る。この契約をtask単位へ変えるには、混在形式の読取り、履歴を失わない移行、移行前後のfold結果一致検証が必要になる。
- ファイル数に起因する検証時間、Git操作、ストレージの具体的な障害は確認されていない。確認できていない問題のために形式移行を行う根拠がない。
将来、計測可能な運用問題が生じた場合は別の変更として再検討する。その際は、既存eventオブジェクトと時系列を変更せず、旧形式と新形式を読める移行期間を設け、全taskで移行前後のfold結果が一致することを受入条件とする。
4. 対応結果
- SpecDojo システム設計横断ルールの
scp-STA-001へ、1 event 1 JSONの規範、設計理由、集約しない判断を記載した。 - exec運用ガイドへ、保存形式、並行性が理由ではないこと、606ファイルの実測、将来の再検討条件を記載した。
- task単位への集約は行わず、既存606ファイルと読書き実装を変更しなかった。履歴の移行は発生しない。
5. 関連ドキュメント
- prj-0001:pjr-9rwg-register-events-separation: register のイベント配置。粒度の判断で対比する。
- specdojo:exec-operation-guide: exec の実行とイベント。記載先の候補。
- specdojo:pjr-rulebook: register 側の配置理由の記述例。
- sysd-cross-cutting-policy: exec eventのappend-only規範と保存粒度の正本。