run-system-spec-compile

run-system-spec-compile

収集済み仕様 (spec-state.json) と取得済み最新ドキュメント (fetched-references.json)・設計知識参照を、章立ての複数 Markdown ファイル + index.md の仕様書ドキュメントセットへまとめる run skill。ヒアリング継続やドキュメント再取得はしない (入力を組み立てるのみ)。

Purpose & Output Contract

入力 (境界・厳守):

• spec-state.json — カテゴリ×プラットフォーム収集マトリクス (C01 run-system-spec-elicit の単一 writer が所有)。
• fetched-references.json — 取得済み最新公式ドキュメントの出典記録 (C02 が取得)。
• 設計知識参照 — ../ref-system-design-knowledge/references/*.md (C04)。

出力: system-spec/ 配下の、先頭にU1-U9と意思決定表を持つ要件定義書 (00-requirements-definition.md) + 章別 Markdown 複数ファイル (<category>.md) + index.md。

完了条件: 要件定義書 + 全カテゴリ章 + index.md が生成され、IN1 (2 決定論ゲート exit0) と OUT1 (受入テスト) を満たす。

上位概念 anchor (要件 C9): spec-state.json の requirements_foundation (U1-U9) を 00-requirements-definition.md (要件定義書=憲法) として最初の章に生成し、各技術章 frontmatter の serves_goals (セル serves_goals の集約) で全章を上位概念へトレース (anchor) する。index.md は要件定義書を先頭に相互参照する。requirements_foundation 不在の spec-state でも空落ちさせず draft の要件定義書を出す。

やらないこと (boundary): ヒアリングの継続 (C01 の責務)、ドキュメントの再取得 (C02 の責務)、spec-state.json の書換え。本 skill は入力を章へ組み立てるだけで、収集状態そのものは変更しない。

章 frontmatter の確定マーカー仕様 (C11 hook の判定ソース・厳守)

各章 Markdown の frontmatter は次の確定マーカーを持つ。C11 hook (guard-confirmed-chapter-overwrite.py) はこのマーカーと spec-state.json のセル状態を判定ソースとして確定章の誤上書きを fail-closed で遮断する。

---
status: confirmed        # 終端カテゴリ (集約=確定/対象外) は confirmed。進行中 (未着手/収集中) は draft
category: database        # 章のカテゴリ id
aggregate: 確定           # 真理値表導出の集約状態 (未着手/収集中/確定/対象外)
spec_cells: [database.web, database.mobile, ...]   # 対応する spec-state マトリクスセル id
serves_goals: [G1, G2]    # 章が資する上位概念ゴール id (セル serves_goals の集約・要件 C9 anchor)
---

• status: confirmed=章凍結 (集約が終端の 確定/対象外)、draft=進行中。集約は宣言値ではなくセル状態から真理値表で再導出する (決定論)。
• spec_cells: 章が対応する <category>.<platform> セル id 一覧 (canonical platform 順)。
• serves_goals: 章の確定セルが資する上位概念ゴール id の和集合 (要件 C9 の anchor)。要件定義書 (00-requirements-definition.md) の goals へトレースし、どのゴールにも資さない収集を drift として --require-foundation が検出する。
• 各章本文はカテゴリ別収集状態表 (未収集 / 対象外+理由 / 確定+qa_ref) と設計知識参照ポインタと最新ドキュメント出典表を持つ (要件 C1)。

単一 writer / 確定状態保全 (C01/C03)

system-spec/ への正本書込経路は C03 (本 skill) の scripts/compile-spec-doc.py に一本化する。確定済み章の確定状態 (spec-state 確定セル・対象外理由) は保全され、勝手な巻き戻しをしない。これは C01 (spec-state.json の単一 transition writer) と対をなす二輪の単一 writerであり、C11 hook はこの正本防御を二重化する fail-closed の補助防御にすぎない (正本防御は writer 側が担う)。spec-state 上でセルが R4-reopen 済み (再オープン) のときだけ、該当章を draft へ戻して再レンダリングできる。

手順 (責務プロンプト正本 = prompts/*.md)

1. R1-assemble (prompts/R1-assemble.md): spec-state.json の requirements_foundation (上位概念) を先頭章に、収集済みカテゴリ×プラットフォーム結果を各技術章に組み立てる (カテゴリ順・canonical platform 順・集約状態を真理値表導出)。
2. R2-render (prompts/R2-render.md): 章立てに沿って章別 Markdown へレンダリングし、設計知識参照 (C04) と最新ドキュメント出典 (fetched-references) を各章へ、各技術章 frontmatter へ serves_goals (上位概念トレース) を反映する。
3. R3-crosslink (prompts/R3-crosslink.md): 全章横断の index.md を生成し、要件定義書を先頭に、各章と収集マトリクス集約状態 (未着手/収集中/確定/対象外) を相互参照可能にする。

決定論の組み立て・frontmatter 生成・index 相互参照は scripts/compile-spec-doc.py (Python 標準ライブラリのみ) が担い、責務プロンプトは判断・章構成の意味付けを担う (機械=再現性 / AI=自由度の二層分離)。

Key Rules

1. 確定性優先: 集約状態・確定マーカーは spec-state のセルから真理値表で再導出し、宣言値を鵜呑みにしない。
2. 入力非改変: spec-state.json / fetched-references.json を書換えない (読むだけ)。
3. 出典必須: 章に反映する最新ドキュメントは source_url・公式発行元・version|last_updated・取得/最新確認日時を伴う (C13 が形式検証)。
4. 対象外は理由付き: 対象外セルは必ず理由 (または承認参照) を章へ明示する (C12 が検証)。
5. 日本語成果物: 章・index の本文は日本語 (カテゴリ id・platform id・JSON キーは英語)。

ゴールシーク実行

IN1/OUT1 の未達ゲートを起点に assemble/render/crosslink の該当責務だけを再実行する。各反復で決定論ゲートを先に通し、最大5周で未達なら成果物を確定せず呼出元へ blocker を返す。全ゲートPASS時だけ完了する。

Feedback Contract (with-feedback-contract / with-goal-seek)

• IN1 (inner, script): 生成直前の spec-state.json / fetched-references.json に対し ../../scripts/validate-coverage-matrix.py --matrix <spec> と ../../scripts/validate-source-citation.py --targets <spec> --references <refs> が exit0。
• OUT1 (outer, test): 生成ドキュメントセットがカテゴリ×プラットフォームの確定/対象外理由と最新ドキュメント出典を含むことを tests/test_compile_spec_doc.py が確認。
• goal-seek (engine=inline, fork=subagent, max_loops=5): IN1/OUT1 を満たすまで章構成・レンダリングを反復改善する。

Additional Resources

references/resource-map.yaml を最初に読む。主要参照:

• scripts/compile-spec-doc.py — 要件定義書 (00-requirements-definition.md) + 章別 Markdown + index.md の決定論コンパイラ (frontmatter 確定マーカー / serves_goals / 状態表 / 出典表 / 相互参照)
• references/chapter-template.md — 章 Markdown の構造テンプレート
• prompts/R1-assemble.md / prompts/R2-render.md / prompts/R3-crosslink.md — R1/R2/R3 責務別プロンプト
• 入力: spec-state.json (C01) / fetched-references.json (C02) / ../ref-system-design-knowledge/references/*.md (C04)
• 決定論ゲート: ../../scripts/validate-coverage-matrix.py (C12) / ../../scripts/validate-source-citation.py (C13)