プロジェクト登録簿 作成ルール
Project Register Documentation Rules
本ドキュメントは、プロジェクト登録簿の個別登録項目（pjr-XXXX-<topic>.md）、項目別イベントログ、そこから生成する一覧・派生ビューの記述ルールです。現在値の正本は個票の Frontmatter、監査履歴の正本は項目別イベントログとし、一覧は表示専用の生成物として扱います。
1. 全体方針
- epic、TODO、要確認事項、リスク、課題、変更要求、決定事項、備忘の全登録項目は、それぞれ 1 件の個票を持つ。
- 個票 Frontmatter の現在値は、分類、処理状態、優先度、担当、日付、結論、起票元の唯一の正本である。
events/pjr-XXXX.yamlは、起票・状態遷移・更新を追う監査履歴の正本である。現在値の再計算には使わず、個票の現在値との整合を検証する。- 個票の H1 と本文は、それぞれタイトルと説明・根拠・経緯・対応内容の正本である。
generated/pjr-index.mdとすべての派生ビューは個票からregister buildで生成し、直接編集しない。<project-id>:pjr-indexはgenerated/pjr-index.mdの文書 ID とする。controls/**/generated/はdoc-indexの限定走査対象とし、register buildの後にindex buildを実行する。- 一覧と個票で同じ構造化フィールドを保持・同期する規則は設けない。
- type 別テンプレートの選択と初期生成は
register addが担うため、本 rulebook は単一の template を参照しない。
2. ファイル命名・ID規則
2.1. ID規約
- 個別登録項目の表示 ID は
PJR-XXXX形式とする。XXXXには数字と英字からI/L/O/Uを除いた4文字を使う。例:PJR-AB12。 - 個別登録項目の文書 ID は
<project-id>:pjr-XXXX-<topic>形式とする。例:prj-0001:pjr-ab12-auth-boundary。 - 個別登録項目のファイル名は
pjr-XXXX-<topic>.md形式とし、文書 ID のローカル部分と拡張子を除くファイル名を一致させる。 - 文書 ID とファイル名では
XXXXを小文字にする。 <topic>は英小文字または数字で始まり、英小文字・数字・単一ハイフンだけで構成し、 ハイフンで終えたり連続ハイフンを含めたりしない。対象領域や論点が分かる短い名称にする。- イベントファイル名は
pjr-XXXX.yamlとし、topic を含めない。ID の小文字表記を用いる。
2.2. 配置規約
- 個票は
docs/ja/projects/<project-id>/controls/project-register/直下に置く。 - 項目別イベントログは同ディレクトリの
events/配下に置き、個票 1 件につき 1 ファイルとする。 - 登録項目一覧は
docs/ja/projects/<project-id>/controls/project-register/generated/pjr-index.mdに生成する。 - 状態別・優先度別・担当者別の補助一覧と、元の項目から派生先を辿る一覧は同じ
generated/配下に生成する。 - controls 全体の type 別管理ビューは
controls/generated/に生成する。生成物の別名コピーは作らない。
3. 推奨 Frontmatter 項目
個票には register-item-frontmatter.schema.yaml が定義する次の項目を置く。未定の担当、期限、完了日時、結論は表用のプレースホルダを保存せず、該当キーを省略する（期限なしだけは due_on: null）。
| 項目 | 説明 | 必須 |
|---|---|---|
id | <project-id>:pjr-XXXX-<topic> | ○ |
type | project | ○ |
status | 文書成熟度。draft / ready / deprecated | ○ |
rulebook | specdojo:pjr-rulebook | ○ |
part_of | <project-id>:pjr-index を要素に持つ配列 | ○ |
item_type | 登録項目の分類 | ○ |
track | epic が担う track。ほかの type では指定しない | epic で必須 |
item_status | 登録項目の処理状態 | ○ |
priority | 対応優先度 | ○ |
difficulty | agent 振り分け用の作業難易度 | 任意 |
owner | 主担当者または役割 | 任意 |
registered_at | 起票日時 | 任意 |
due_on | 対応期限または判断期限 | 任意 |
completed_at | 完了・却下・決定日時 | 条件 |
block_reason | waiting へ遷移した直近の理由 | 任意 |
conclusion | 終端時の結論要約 | 任意 |
derived_from | 起票の元になった登録項目 ID の配列 | 任意 |
depends_on | 実行前に完了しているべき先行の登録項目 ID の配列 | 任意 |
approach | 対象を作成・修正するときの進め方 | 任意 |
target_path | カタログなしで作成する成果物のリポジトリ相対パス | 任意 |
target_rulebook | 対象成果物の rulebook ID | 任意 |
targets | 変更対象文書の doc id リスト | 任意 |
epicは track ごとの大きな仕事を表し、自身は実行しない。trackは英小文字・数字・ハイフンの識別子とし、先頭は英小文字または数字にする。tml-index.yamlがある場合、定義済みの track を指定する。ない場合も識別子を保持できる。register add --type epic --track <track>で起票し、register update --track <track>で変更する。epic のtrackは削除できない。変更はイベントに残す。statusは文書成熟度、item_statusは処理状態であり、同じ状態軸として扱わない。item_type、item_status、priority、difficultyの値は schema の enum だけを使用する。difficultyはhard/medium/easyのいずれかとし、省略時は従来の agent 自動選択を使う。block_reasonはwaiting中の直近の待機・失敗理由、conclusionは終端時の結論として用途を分ける。register wait --reasonは前者だけを更新し、waiting以外へ遷移すると現在値から削除する。削除前の理由は項目別イベントログの変更前の値に残す。- Frontmatter の構造化フィールドを本文や生成一覧へ手作業で複製しない。
derived_fromは同じ project の元項目をPJR-XXXX、別 project の元項目を<project-id>:PJR-XXXXで記録する。自己参照や存在しない項目は使用しない。未設定の project は拒否する。別 project の存在確認は、その project のローカル統合ブランチを正とする。depends_onは実行順序、derived_fromは起票の由来を表す。両者を相互に推測・転記しない。参照書式と別 project の存在確認はderived_fromと同じ規則を使い、存在しない ID、自己参照、project をまたぐ循環を記帳前とregister buildで拒否する。register add/updateの--depends-on <ID>は反復指定でき、一覧を置換する。--depends-on -は依存を削除し、ほかの ID と併用しない。変更は event に記録する。- すべての先行項目が
done/decidedのときだけ実行を許可する。rejected/deferredは依存を満たさない。直接のexec run --registerは未完了の先行 ID と状態を示して停止し、routine の sweep（--register-filter）と夜間 queue は理由を記録して対象を飛ばす。依存を理由に状態を自動でwaitingへ変更しない。
3.1. 日時と日付の使い分け
- 起票と終端は瞬間として記録し、
registered_at/completed_atに UTC の RFC 3339・秒精度（YYYY-MM-DDTHH:MM:SSZ）で保存する。 - 期限は瞬間ではなくプロジェクトタイムゾーン上の暦日であるため、
due_onはYYYY-MM-DDのまま保持する。 - 一覧・派生ビューの「登録日」「完了日」は、保存した日時をプロジェクトの登録日タイムゾーンへ変換して導出する表示値であり、個票へ日付として重複保存しない。
- 日時は register コマンドが記録する。手書きで日時を入力する場合も、タイムゾーンを含む値から UTC へ変換した値だけを保存する。
3.2. Register event と責務境界
- 個票の現在値は
item_statusなどの Frontmatter フィールド、変更履歴はevents/pjr-XXXX.yaml、保存・配布・差分レビューは Git が担う。Git コミットはイベントの発生単位ではなく、履歴再構成の正本にしない。 - イベントファイルのルートは YAML 配列とし、イベントを古い順に追記する。項目ごとの配置により、イベントごとの追加ファイルを作らず、異なる項目を並行更新したときの共有ログ競合を避ける。
- 各イベントは version、イベント ID、UTC 発生日時、action、actor、遷移前後の
item_status、reason、変更フィールド、直前イベント ID を保持する。Git から移行したイベントだけは移行元 commit も保持できる。 - action は
add/start/wait/review/close/reject/defer/reopen/update/renumber/migrateのいずれかとする。詳細な型と enum はregister-events.schema.yamlを正本とする。 register buildは個票とイベントファイルの 1 対 1 対応、イベント ID の一意性、時刻順、直前イベント参照、遷移前後状態の連鎖、最新イベントの状態と個票のitem_statusの一致を検証する。不正なイベントを無視して一覧を生成しない。
4. 本文構成（標準テンプレ）
4.1. 個別登録項目
| 順序 | 内容 | 必須 | 説明 |
|---|---|---|---|
| 1 | type 固有の記録 | ○ | 対象、背景、評価、対応・判断、結果など |
| 末尾 | 関連ドキュメント | ○ | 根拠、影響先、追跡先を文書 ID で示す |
- H1 は
PJR-XXXX <タイトル>形式とする。 - 実行対象の
todo・issue・change-request・question・riskの個票は、対話で得た前提・制約・委任範囲を箇条書きで残す入力節を持つ。入力がない場合は-とする。完了条件・回答の確定条件とは分ける。既存個票に節がなくても読み込め、初回の入力更新時に節を追加する。 epicは概要、範囲（track と domain）、完了の判断の基準、子項目、対応結果、関連ドキュメントを持つ。範囲には domain と境界、完了の基準には子項目と schedule を確認する判断条件、対応結果には人が完了を判断した根拠を記録する。- 子 todo は
--from <epic-id>で起票する。derived_fromを逆引きした epic 別ビューは直接の子を type と状態付きで表示し、子がない epic も表示する。別 project の子は project 修飾 ID で識別する。孫を再帰的に含めず、状態の自動集約や自動 close は行わない。 - type 固有の構成は
todoの概要・完了条件・作業内容・対応結果など、各 type 用テンプレートに従う。 - ID、分類、処理状態、優先度、担当、期限、完了日時は本文へ重複記載せず、Frontmatter を参照する。
- 終端前に未確定の結果・結論がある場合は、
-または共通ラベルを用い、確定済みの記述と混在させない。
4.2. 生成一覧と派生ビュー
| 生成物 | 内容 | 編集可否 |
|---|---|---|
generated/pjr-index.md | depends_on を含む全個票の一覧 | 不可 |
generated/pjr-views-by-status.md | 状態別の補助一覧 | 不可 |
generated/pjr-views-by-priority.md | 優先度別の補助一覧 | 不可 |
generated/pjr-views-by-owner.md | 担当者別の補助一覧 | 不可 |
generated/pjr-derived-items.md | 元項目と派生先の一覧 | 不可 |
generated/pjr-epic-items.md | epic ごとの直接の子項目と状態 | 不可 |
generated/pjr-dependent-items.md | 先行項目から後続項目を逆引きする一覧 | 不可 |
controls/generated/pm-*.md | type 別の管理ビュー | 不可 |
- 一覧の標準列は ID、ステータス、タイトル、説明、分類、優先度、担当、登録日、期限、完了日、結論、個票、
depends_onとする。 - タイトルは個票の H1、説明は個票本文、その他の列は個票 Frontmatter から生成する。
- 登録日と完了日の列は、
registered_at/completed_atをプロジェクトの登録日タイムゾーンへ変換した暦日として生成する。 - 生成ビューに独自の詳細情報や手作業の修正を追加しない。修正は個票に行い、
register buildを再実行する。
5. 記述ガイド
5.1. 個票の記述
背景には、登録が必要になった事実、制約、判断または対応の期限を記載する。
評価や選択肢には、比較可能な観点と根拠を記載し、結論だけを先に固定しない。
対応・判断内容には、実施または採択した範囲と、明示的に対象外とした範囲を記載する。
結果・結論には、完了を判定した根拠と後続対応を記載する。
関連ドキュメントには、判断根拠、変更対象、影響先、追跡先のうち該当する文書を記載する。
実行中に問題や後続作業を見つけて別の登録項目を起票するときは、起票元を
derived_fromに必ず記録する。decision から todo を起票する場合も同じ関係を使い、decision 本文へ追跡先を重複記載しない。既存本文の追跡先は移行のために書き換えない。本項目の実施において確実に変更する対象文書が分かっている場合は、その文書 ID を Frontmatter の
targets配列へ宣言する。宣言したtargetsは agent 実行時の変更網羅検証（target coverage）に用いられる。未知の場合や対象を固定しない場合は宣言を省略する。approachを宣言する場合、targetsは 1 件だけ必須とする。成果物の対象はカタログを優先して解決する。cross-deliverable-dedupはカタログを必須とする。それ以外の成果物の approach（fully-guided・recipe-guided・freeform・bootstrap・retrofit・finalize・bootstrap-finalize）は、カタログなしでも既存文書の索引とspecdojo.rulebook、または個票のtarget_pathとtarget_rulebookから解決できる。新規文書は両フィールドを必須とし、リポジトリ外のパスや別文書との衝突、既存文書と指定の不一致は認めない。カタログ設定済みで対象が未登録の場合も両フィールドがある場合だけ同じ解決を使う。rulebook-maintenance・recipe-maintenance・sample-maintenance・template-maintenanceの対象は、名前に対応する種別の kata の doc id とし、文書索引で解決する。対応する正本で解決できない ID や、approachと種別が合わない対象は使用しない。カタログなしの完了基準は個票の完了条件と rulebook とする。recipe・sample・template は rulebook frontmatter から辿り、
not-neededのものを対象に含めない。fully-guidedの必要な一式、recipe-guidedの recipe が不足する場合は起票・更新を拒否する。カタログなしの
bootstrapはtarget_path、新しいtarget_rulebook、設定のkata_authorityを必須とする。既存 rulebook を再利用しない。rulebook の名前部分から recipe・sample・template の ID を導出し、docs/ja/specdojo/<kind>s/<kata_authority>/に配置する候補を plan へ示す。成果物には新しいspecdojo.rulebookを記録する。finalize・bootstrap-finalizeは既存成果物だけを対象にし、カタログなしでは個票の完了条件を確認チェック表にする。後者は成果物と frontmatter から辿る kata 一式を確定対象とする。対話で得た前提は
register add --input <text>で個票本文の入力へ記録する。繰り返し指定した順に箇条書きとし、register update --inputは指定した一覧で置換する。追記する場合は既存分を含めて渡し、--input -単独で全削除する。未指定時は保持する。空文字、削除指定と他の入力の混在、add での削除指定は拒否する。入力の変更は event の
inputフィールドへ変更前後の JSON 配列として記録し、値がない場合は-とする。register 経由の plan は approach の有無を問わず、入力がある場合だけ「個票の入力（前提）」に展開する。入力を完了条件へ転記しない。
5.2. 構造化フィールドと生成
- 新しい項目は
register addで作成し、個票の Frontmatter に初期値を書き込む。全 type で個票を省略しない。 - 担当・期限・結論・topic・
derived_from・approach・targetsなどを変更するときはregister update、処理状態を変えるときは状態遷移コマンドを使用する。register addとregister updateでは、起票元に繰り返し指定できる--from、進め方に--approach、対象に繰り返し指定できる--target、成果物の配置と rulebook に--target-pathと--target-rulebookを使う。配置と rulebook の明示指定もそれぞれ-で削除できる。起票元、approach、対象を削除するときは、それぞれ--from -、--approach -、--target -を指定する。待機理由はregister wait --reasonで記録し、誤った現在値を手動補正するときはregister update --block-reason -で削除する。 register buildは個票を読み取り、一覧・派生ビューを再生成する。generated/pjr-derived-items.mdではderived_fromを逆引きし、元の項目から派生先を辿れるようにする。一覧を編集して個票へ反映する経路はない。register add、状態遷移、register update、register renumberは現在値を個票へ、イベントを対応する項目別ログへ記録する。--byで actor、--reasonで理由を明示でき、省略時は予約 actor のSpecDojoを記録する。--byに指定できるのは、project のpm-members.yamlにある人の nickname、repository の.specdojo/agent-members.yamlにある agent の nickname または alias、予約 actor のSpecDojo・specdojo-orchestrator・night-orchestratorに限る。agent の alias は実体の nickname に解決して記録し、名簿にも予約一覧にもない値は書き込み前に拒否する。- 決定・承認を記録する actor には、
POなどの Role code や予約 actor ではなく、決定・承認した人の nickname を使う。specdojo-orchestratorは対話型オーケストレーター自身の操作だけに使い、人の判断主体を代替しない。 - 同じ現在値へ同じ操作を再実行した場合は、新しいイベントを追加しない。イベント ID と直前イベント参照を保ったまま再実行し、既存イベントの置換や削除で重複を解消しない。
- ID の変更は
register renumberで行い、個票のファイル名・Frontmatter・参照と生成ビューを整合させる。 - 主題の変化に伴う
<topic>の変更はregister update --topicで行う。個票のファイル名と Frontmatter の文書 ID、他文書中の旧文書 ID 参照を同時に更新し、生成ビューを再生成する。
5.3. 登録項目の item_status 遷移基準
5.3.1. item_type 別の item_status 終端基準
item_status の通常終端は、登録した目的を達成したときに使用する。type ごとの通常終端と判定基準は次のとおりとする。
item_type | 通常終端 | 遷移条件 | conclusion に残す内容 |
|---|---|---|---|
epic | done | 子項目と schedule を材料に、track の完了基準を満たすと人が判断した | 判断の根拠と残課題 |
todo | done | 個票に記載した完了条件をすべて満たした | 実施内容と完了を確認した根拠 |
question | decided | 問いへの回答を確認し、後続作業の要否を判断できる | 確定した回答 |
decision | decided | 選択肢、採択理由、影響を記録し、必要な承認を得た | 決定内容 |
note | なし | 終端させず、open のまま新しい事実・知見を追記する | 終端しないため使用しない |
risk | done | リスクが顕在化しないまま消滅した、または対応を終えて追跡が不要になった | 消滅・対応完了の根拠 |
issue | done | 問題を解消し、必要な確認を終えた | 解決内容と確認結果 |
change-request | done | 採択した変更を対象へ反映し、必要な確認を終えた | 反映内容と確認結果 |
question/decisionの通常終端にdoneを使わず、回答・決定が確定したことを示すdecidedを使う。epic/todo/risk/issue/change-requestの通常終端にdecidedを使わず、対応または追跡が完了したことを示すdoneを使う。epicは todo と同じ処理状態と例外終端（rejected/deferred）を使用する。exec run --registerの実行対象にはせず、filter と夜間 queue も飛ばす。具体的な作業は子 todo で実行する。noteのopenは未対応を意味しない。内容を継続して更新できる、生きている記録であることを示す。noteから対応・回答・判断が必要になった場合は、todo/question/decisionなど目的に合う別項目を起票し、note 自体はopenのまま参照元として保持する。noteの内容が陳腐化または置換された場合は、その事実と参照先を本文へ追記する。done/decided/rejected/deferredへ遷移させて閉じない。
5.3.2. 例外的な追跡終了
note 以外では、通常終端に達していなくても、次の条件で追跡を終了できる。
item_status | 使用条件 | 記録要件 |
|---|---|---|
rejected | 対応・回答・判断の対象外、前提不成立、または変更を採択しないことが確定した | 採択しない理由と、必要なら代替の追跡先を記録する |
deferred | 現時点の追跡を停止し、再開条件または再評価時期を定めた | 再開条件または再評価時期を記録する |
rejectedは完了・決定の代用にせず、実施または採択しない判断が確定した場合だけ使う。deferredは状態遷移上の終端だが、完了を意味せずcompleted_atを持たない。再開するときはregister reopenを使う。question/decisionで回答または決定を得た場合はrejectedではなくdecidedを使う。問い・判断自体が不要になった場合だけrejectedを使う。riskを受容して監視を終える場合は、受容判断と残存影響をconclusionに記録したうえでdoneとする。リスクの前提が誤りだった場合はrejectedとする。
5.3.3. 中間状態を経ない終端
終端への遷移は、in-progress / waiting / review を経ていることを前提としない。open から直接終端させてよい。
- 人または対話型 orchestrator が対応した項目では、着手を記録する前に完了することがある。形式を揃えるために
startを遡って記録すると、実際には行われていない時点の遷移がイベントログに残る。事実と異なる記録を避けるため、直接の終端を許す。 - agent が
exec runで実行する項目は runner がstartを記録するため、この経路では中間状態が必ず残る。 - 中間状態を経ない場合は、誰がどの経路で対応したかを終端イベントの
reasonへ記録する。exec の plan / result / evidence が存在しないため、実施内容と検証結果は個票の対応結果へ残す。 - 実行していない主体を actor とする遷移を、記録の体裁を整える目的で追加しない。
5.4. 個票 status の遷移基準
status | 意味 | 遷移させる時点 |
|---|---|---|
draft | 作成直後。type 固有の必須節が未確定 | register add で個票を生成した時点 |
ready | type 固有の必須節が固まり _TODO_ が残っていない | register close 時に必須節を満たすと判定した時点 |
deprecated | 却下・破棄され成熟度を追う必要がない | register reject 時点 |
- 遷移は register コマンドが担い、個票 Frontmatter を直接手書きで書き換えない。
readyへの昇格には、type 固有の必須節に_TODO_が残っていないことを要する。reopenは過去の結果を消さず、再開理由と新しい対応状況を個票本文へ追記する。
6. 禁止事項
- 生成された
pjr-index.md、補助一覧、controls 全体の派生ビューを直接編集しない。 - 一覧と個票の同期、一覧から個票への書き戻し、または個票を作るかどうかの分離基準を設けない。
- 構造化フィールドを個票本文や別の正本へ重複管理しない。
type/item_status/priorityに schema 未定義の値を使用しない。registered_at/completed_atに、UTC 以外のオフセットやタイムゾーンを伴わない値、暦日だけの値を保存しない。- 個票の文書 ID から
<topic>を省略したり、ファイル名と異なるローカル ID を使用したりしない。 - type 固有の必須内容を、見出しだけ残した空欄のまま終端状態にしない。
- 実行していない主体を actor とする状態遷移を、記録の体裁を揃える目的で追加しない。
events/pjr-XXXX.yamlを手書きで追加・修正・並べ替え・削除しない。履歴補正が必要な場合も register コマンドを使い、監査イベントを破壊しない。