PJR-9Y7G 登録簿の正本を1項目1ファイルへ移し pjr-index を生成ビュー化する
1. 背景
登録項目の正本を個票 frontmatter へ一本化し、pjr-index.md を generated の派生ビューへ変更するかを判断する。表の差分レビュー喪失の代替手段も選択肢比較に含める。
登録簿は pjr-index.md の登録項目一覧（表）を正本とし、詳細が必要な項目のみ個票 pjr-XXXX-<topic>.md へ分離する二層構造をとっている。この構造について、正本の粒度を実体（登録項目）単位のファイルへ移すべきかを判断する必要がある。
判断が必要になった事実と制約は次のとおり。
- 1つの登録項目の属性が2ファイルへ分割保管されている。specdojo:pjr-rulebook の
index と個別登録項目の同期で、処理状態・優先度・担当・期限・完了日・結論要約はpjr-index側、背景・経緯は個票側という分割と、両者を一致させる同期規則が定義されている。 - 表を共有単位とするため、並行編集で行の追記・編集が衝突しうる。これに対して PJR-ID の乱数化、
register addの統合ブランチ自動ルーティング、--reserve/--local/--strict-sync、register where --integration、register renumber、worktree 隔離と lifecycleLock による補償機構を実装済みである（prj-0001:pjr-0137-register-id-uniqueness、prj-0001:pjr-0138-register-add-on-integration-branch）。 - 表セルは構造化データの器としての制約（
|のエスケープ、wikilink 表示名区切りの escape、整形ツールによる表崩れ、未定値をプレースホルダ文字列で埋める規約）を持ち、検証には表専用のpjr-index-content.schema.yamlを要する。他の成果物では構造化メタを frontmatter に置き、frontmatter スキーマで検証している。 - SpecDojo 全体は「正本＝成果物ファイル、派生＝
generated/」を採用し、docs/**/generated/*は.gitignoreで非追跡としている。pjr-index.mdのみ表が正本という例外になっている。 - SpecDojo は未リリースのため、移行コストではなく設計の妥当性を主たる判断軸にできる。
判断は PO が行う。期限は登録簿一覧の「期限」欄で管理する。
2. 検討した選択肢
| 選択肢 | 内容 | 利点 | 懸念 |
|---|---|---|---|
| A | 現状維持。pjr-index.md の表を正本とし、詳細のみ個票へ分離する | 台帳全体を1ファイルの差分で追える。表を人が直接編集・レビューできる。移行不要 | 正本の粒度が実体と一致せず同期規則が必要。並行編集が不可換で補償機構の維持が要る。表専用スキーマが残る |
| B | 個票 frontmatter を唯一の正本とし、pjr-index.md を generated/ の派生ビューへ変更する | 正本の粒度が実体と一致し同期規則が不要。項目の追加・遷移が構造的に可換で衝突しない。既存 frontmatter スキーマで検証できる。framework 内の正本・派生の扱いが統一される | 台帳の変更履歴が個票へ分散し1ファイルの差分で追えない。表の手編集を運用から外す必要がある。CLI・スキーマ・rulebook・テンプレート・既存項目の移行が必要 |
| C | 折衷。表を正本のまま維持し、補償機構（--reserve / --local 等）のみ簡素化する | 移行が小さく、既存の運用と差分レビューを維持できる | 正本の粒度と同期規則の問題は残る。衝突は運用規律に依存し続ける |
選択肢 B を採る場合の成立条件は次のとおり。
- 構造化フィールド（処理状態・優先度・担当・期限・完了日・結論・分類）は個票 frontmatter を唯一の正本とし、本文へ複製しない。
pjr-index.mdをgenerated/配下の生成物へ移し、追跡対象から外す。手編集を運用から外す。- 「個票を作る項目／作らない項目」の二分を廃止し、全項目を1ファイルとする。
- 生成の決定性（ID 昇順などの固定ソート）を担保する。
- 補償機構を撤去し、
renumberは乱数 ID 衝突の救済のみへ縮小する。 - 台帳の差分レビュー喪失に対する代替（個票の履歴で追う、pull request では frontmatter 差分を見る、一覧表示コマンドを用意する等）を決める。
評価の結果、選択肢 B を採択した。決定内容と採択理由は後続の章に記載する。
3. 決定内容
Bを選択する。
4. 採択理由
- 正しい設計がBで、本格展開前に移行する。
5. 承認
| 項目 | 内容 |
|---|---|
| 決定者 | PO（GitHub アカウント: naoji3x） |
| 決定日 | 2026-08-09 |
| 承認方式 | PR（選択肢 B は framework の schema と CLI に破壊的変更を伴うため） |
| 証跡 | PR: https://github.com/specdojo/specdojo/pull/3 / merge SHA: 98f507236c5997f82106e4139a82a4a3485a4c71 |
- 承認方式は
commitまたはPRを記載する。PRの場合は証跡に PR URL と merge SHA を本文テキストで記載する。 - 不可逆・高リスク・framework schema 破壊的変更に該当する決定は
PR方式で承認する。
6. 影響範囲とフォローアップ
| 項目 | 内容 |
|---|---|
| 影響範囲 | 選択肢 B 採択時: register CLI（add / 状態遷移 / build / renumber / where）、pjr-index-content.schema.yaml、specdojo:pjr-rulebook、specdojo:register-operation-guide、pjr-index-template.md と個票テンプレート、派生ビュー生成、既存の全登録項目の移行 |
| 必要な対応 | B を採択したため、移行タスク（CLI・スキーマ・rulebook・テンプレート・既存項目の移行）を別途起票する |
| 追跡先 | 本個票（PJR-9Y7G） |
7. 関連ドキュメント
- specdojo:pjr-rulebook: 登録簿の記載ルールと index・個票の同期規則（判断根拠）
- specdojo:register-operation-guide: 登録簿の運用手順と PJR-ID の統合ブランチ集約（判断根拠）
- prj-0001:pjr-index: 変更対象となる登録項目一覧
- prj-0001:pjr-0137-register-id-uniqueness: PJR-ID 重複の検知と復旧（先行対応）
- prj-0001:pjr-0138-register-add-on-integration-branch: 統合ブランチ集約による採番（先行対応）