Pre-choice usable artifact execution
Purpose & Output Contractの最小の実成果物をmain contextで作成する。effect別のparse/open・secret・irreversible・corrupt guardだけを実行し、現物path・digest・開き方を提示してからaccept-as-is/light/standard/detailedを記録する。accept-as-isはその場でhandoff完了とし、後続sectionを実行しない。
Post-choice selected improvement execution
以下の既存workflow・goal-seek・評価・修正sectionはlight/standard/detailedが記録されてsemantic_evaluator_startedへ遷移した場合だけ実行する。release/exhaustiveは別の明示eventを必要とする。
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)
- R1-assemble (
prompts/R1-assemble.md): spec-state.json の requirements_foundation (上位概念) を先頭章に、収集済みカテゴリ×プラットフォーム結果を各技術章に組み立てる (カテゴリ順・canonical platform 順・集約状態を真理値表導出)。
- R2-render (
prompts/R2-render.md): 章立てに沿って章別 Markdown へレンダリングし、設計知識参照 (C04) と最新ドキュメント出典 (fetched-references) を各章へ、各技術章 frontmatter へ serves_goals (上位概念トレース) を反映する。
- R3-crosslink (
prompts/R3-crosslink.md): 全章横断の index.md を生成し、要件定義書を先頭に、各章と収集マトリクス集約状態 (未着手/収集中/確定/対象外) を相互参照可能にする。
決定論の組み立て・frontmatter 生成・index 相互参照は scripts/compile-spec-doc.py (Python 標準ライブラリのみ) が担い、責務プロンプトは判断・章構成の意味付けを担う (機械=再現性 / AI=自由度の二層分離)。
Key Rules
- 確定性優先: 集約状態・確定マーカーは spec-state のセルから真理値表で再導出し、宣言値を鵜呑みにしない。
- 入力非改変: spec-state.json / fetched-references.json を書換えない (読むだけ)。
- 出典必須: 章に反映する最新ドキュメントは source_url・公式発行元・version|last_updated・取得/最新確認日時を伴う (C13 が形式検証)。出典は target の category (主たる章) に載せ、target が
also_categories で宣言した章にも同じ出典を載せる。宣言の無い章へは推測で重複させない。
- 対象外は理由付き: 対象外セルは必ず理由 (または承認参照) を章へ明示する (C12 が検証)。
- 日本語成果物: 章・index の本文は日本語 (カテゴリ id・platform id・JSON キーは英語)。
- 逐語は章の構造を壊さない: spec-state の逐語 (qa の問・答・出所、承認 note、章の適用記述、To-Be/Delta のゴール・具体的にやりたいこと・意思決定の問) に見出し・フェンス・setext の下線が行として含まれるときは、その逐語をフェンスに閉じ込めて描く (本文の字面は変えない)。表のセルに入る逐語 (状態表の対象外理由、To-Be/Delta の目標と観測点) は、改行を
<br> に、| を \| にして 1 行に収める (表示される字面は変えない)。逐語の行頭 ### が章の見出しとして漏れると、次回の compile がそれを人の節と見なして引き継ぎ続ける。
- 置き換え済みの qa は旧版の印付きで描く:
superseded_by を持つ qa entry は「旧版（置き換え先: <qa_id>）」の印付きで描き、問・答は逐語のまま残す。印の根拠は superseded_by だけで、R4-reopen の履歴から一律に旧版と推し量らない。
- 既存章の片付け (移行): 以前の compile が漏らした見出し (Key Rules 6 でフェンスに閉じ込める逐語に、行として現れる見出し) は、2 つの判定で扱いを分ける。(a) 引き継ぎの境界からは字面だけで外す (逐語と同じ字面の見出しは、人の節としても引き継げない)。(b) 消失判定から外すのは、既存章でその見出しの直下 (次の見出しまで) が漏れの形をしている場合に限る。漏れの形とは、同じ逐語の続きの行がそのまま並び (逐語の中に次の見出しがあればそこまで)、逐語が末尾まで続いたときだけ、その後ろに spec-state から導ける行 (逐語の行と、compile が qa・承認とその参照を描く行) が並ぶ形をいう。見出しの字面が逐語と同じでも、直下が漏れの形でなければ人の節なので、消失として CompileError で止める。エラーは衝突した見出しを示し、人の節なら逐語に無い見出しへ改めるよう、旧 compile の漏れならその見出しと直下の行を既存章から消すよう促す。管轄節と同じ見出しの
#### 質疑ブロックは引き継がず再描画する。人が書いた見出しが消えるときは従来どおり CompileError で止める (人の節の保存則は変えない)。
ゴールシーク実行
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)