Luna Flow
日本語

ドキュメントのガバナンス

  • ステータス：active
  • 対象読者：コントリビューター、メンテナー
  • 権威：リポジトリのドキュメント方針。QED 形式仕様に従属する
  • 範囲：ドキュメントの階層、命名、メタデータ、相互参照の規則
  • 最終レビュー: 2026-10-08

本書は QED リポジトリのドキュメントガバナンス規則を定める。その目的は新たな仕様の層を追加することではなく、既存のドキュメントを権威、目的、読者によって厳密に階層化し、同じ主題が複数のエントリポイントで繰り返し語られて時間とともに逸脱することを防ぐことである。

ドキュメントの層

QED は現在、次のドキュメント層を用いる。

  1. 仕様層 QED 形式仕様が唯一の規範的根拠であり、doc/attachments/qed_formal_spec.typ がそのソースファイルである。
  2. 実装層 現在のコードと回帰テストが、実際の出荷状態を決定する。
  3. 実装ドキュメント層 ユーザーマニュアル、仕様適合性、api/、design/、tutorial/ 配下のパッケージページ、ワークスペース監査(2026-04-18)は、現在の実装契約、エンジニアリング上の適合性、パッケージごとの公開サーフェス、特定時点の監査を記述する。
  4. 要約・ナビゲーション層 README.md、CHANGELOG.md、マニュアル概要は、要約、リリース履歴、エントリポイントのナビゲーションのみを提供する。実装層や実装ドキュメント層より上位に置いてはならない。
  5. 研究層 research/ は、未出荷の設計研究、昇格ゲート、go/no-go の結論、プロトタイプ評価のみを保持する。研究ドキュメントは製品契約ではない。

コードとドキュメントが矛盾する場合は、まずコード + テストから実際の状態を確定し、それを実装ドキュメントへ書き戻す。実装が論文の仕様と矛盾する場合は、依然として論文の仕様が優先される。

正規のエントリーポイント

すべての種類の情報には、単一の主要なエントリポイントがなければならない。

  • 現在の実装契約: ユーザーマニュアル
  • 一つのパッケージの公開サーフェス、設計根拠、ウォークスルー: api/、design/、tutorial/ 配下のそのページ。マニュアル概要に一覧がある
  • 現在のユーザー入力構文のクイックリファレンス: 構文ガイド
  • エンジニアリング上の適合性とコード/テストの対応: 仕様適合性
  • 特定時点のリスクとギャップ: ワークスペース監査(2026-04-18)
  • リポジトリの要約とクイックエントリポイント: README.md
  • リリース履歴: CHANGELOG.md
  • 研究ディレクトリのエントリポイント: research/README.md

その他のドキュメントはこれらを補足できるのみであり、「現在の状態」を並行して重複させてはならない。

コードの構成とエイリアスエントリポイントのガバナンスは、コードガバナンスの一か所で定められる。それは現在のコードや実装ドキュメントより上位に置かれず、エンジニアリング上の境界と保守義務のみを固定する。

メタデータ契約

トップレベルの README.md、CHANGELOG.md、仕様本文そのもの、マニュアル概要、および api/、design/、tutorial/ 配下のパッケージページ(これらは代わりに Luna Flow のドキュメント標準に従う)を除き、保守対象のドキュメントはすべてヘッダに次を含めなければならない。

  • Status
  • Audience
  • Authority
  • Scope
  • Last reviewed

ステータスラベルは次の語彙を用いる。

  • active
  • point-in-time audit
  • research-only
  • superseded
  • archival reference

命名規則

  • 実装ドキュメントには、manual.md、conformance.md、current_workspace_audit.md のような、責務に基づく名前を用いる。
  • 研究ドキュメントには、トピックディレクトリ + 段階ごとのファイル名を用い、すべて小文字のケバブケースとする。
  • 新たな研究トピックは research/<topic>/ の下に置く。例: research/rewrite-simplify/。
  • v2、new、tmp、final のような一時的な名前を追加してはならない。置き換えが必要な場合は、移行を直接完了させて古いエントリポイントを削除する。

内容の規則

  • README.md に含めてよいのは次のみである。
    • プロジェクトの紹介
    • 現在の出荷済みサブセットの高レベルな要約
    • ビルドコマンド
    • ドキュメントマップ
  • README.md には次を載せるべきではない。
    • 完全なサポート表
    • 長い機能一覧
    • 監査の詳細
    • 将来計画の詳細
  • ユーザーマニュアルは、現在の実装境界、モジュールの責務、サポート表、安定した例を記述する。
  • パッケージページはそれぞれ一つのパッケージを扱う。api/<package>.md は pkg.generated.mbti のすべての公開項目を列挙し、design/<package>.md はその背後にある判断を説明して最後に境界を述べ、tutorial/<package>.md は現在のコードに対してコンパイルできる例を用いて作業を順に説明する。これらはユーザーマニュアルのサポート表を繰り返さず、そこへリンクする。
  • 構文ガイドは、現在出荷されている定理スクリプトの入力構文と既知の制限のみを記述する。実装契約としては機能しない。
  • 仕様適合性は、仕様との整合、コード/テストの対応、コントリビュータ向けチェックリスト、ドキュメントの例に対する制約を記述する。
  • ワークスペース監査(2026-04-18)は、ある時点で依然として成り立つリスク、ギャップ、フォローアップのみを記録し、manual/conformance の安定した事実を長期にわたって繰り返さない。
  • research/ のドキュメントは、research-only、not shipped、non-authoritative を明示的に宣言しなければならない。

例と参照の規則

  • 公に主張されるすべての機能は、現在のコードと回帰テストにたどれなければならない。
  • 公開される実行可能な例は、既存のテストにアンカーされていなければならない。ドキュメントはテストされていないスクリプトを創作してはならない。
  • README.md は機能を要約するのみであり、独自に例の意味論を創作しない。
  • 研究ドキュメントは出荷状態に言及してよいが、長期にわたる状態の記述を別に書くのではなく、実装ドキュメントへリンクすべきである。

現在のドキュメントマップ

  • README.md リポジトリの要約とナビゲーションのエントリポイント。
  • CHANGELOG.md リリース履歴。
  • マニュアル概要 パッケージマップと読み順。
  • ユーザーマニュアル 現在の実装契約。
  • パッケージページ(api/、design/、tutorial/) 各パッケージの公開サーフェス、設計根拠、ウォークスルー。
  • 構文ガイド 現在出荷されている定理スクリプトの入力構文のクイックリファレンス。
  • 仕様適合性 コード/テストの対応とエンジニアリング上の適合性。
  • コードガバナンス パッケージの階層構造、エイリアスエントリポイント、コード保守の義務。
  • ワークスペース監査(2026-04-18) 現在のワークスペースの特定時点の監査。
  • 形式仕様の変更履歴 仕様の変更履歴。仕様保守のための補助資料。
  • research/README.md 研究ディレクトリのエントリポイントと境界の表明。

保守規則

変更が実装、公開される機能の主張、研究上の判断に同時に影響する場合は、次の順序でドキュメントを保守する。

  1. コードとテスト
  2. ユーザーマニュアル
  3. 影響を受けるパッケージページ(api/、design/、tutorial/)
  4. 仕様適合性
  5. README.md と CHANGELOG.md
  6. ワークスペース監査(2026-04-18)
  7. 関連する research/ のドキュメント