folio は当初「自分自身を規律する META FRAMEWORK」として作られたが、 そこで磨いた文書規律 (dual-audience / EARS / RTM / declarative / 1 名 1 語 / HOW を外側へ / 3-domain 分離 / inter-doc 照会) は folio 固有ではなく あらゆる文書一式に効く一般原理である。 文書規律エンジン (C) はこの規律を抽出し、 任意プロジェクト向けに「完璧な文書一式」を生成する道具にする試みである。
進め方は 抽出主導 (rule-of-three): 全列挙で設計するのではなく、 folio を強い事前知識として ~3 例の実物を作り、 共通項を core として後から抽出する。 SRS-pack (epic folio-c5g) が一例目、 本 B1 の ADR-pack が二例目 (instance#2)。 止め時は「新しい doc-type が core を一切変えずに純粋な pack として挿さった」とき。 抽出は可逆 (誤って core に置いた物は pack へ降格できる)。 endgame は folio 自身をこのエンジンで dogfood すること。
| フェーズ | bd | 内容 | 状態 |
|---|---|---|---|
| B0 | folio-9ay | 設計 grill (6 論点合意) | 完了 |
| B1 | folio-bwc | instance#2 = clinic ADR 生成 + 本 design-of-record | 本 doc |
| B2+ | (後続別 bd) | core 抽出 (非破壊) → research/principle pack → 照会/HOW-outside 機構 → folio self dogfood | 未着手 |
engine は次の 3 層 + 別軸の constitution に分かれる。 「機構 (どう生成・検証するか)」と「規律 (何が良い文書か)」と「中身 (各 doc-type 固有の部品)」を分離するのが要点で、 これが core / pack 境界を引く基準になる。
| 層 | 役割 | 具体 (folio の現状から) |
|---|---|---|
| plumbing core (機構) | doc-type 非依存の生成・検証の足回り | 現 §12 の 4 機構: ①機械 SSoT から生成 ②決定的 assembler + opus prose ③自己完結 (single-file inline) ④2-gate (floor 機械 ∧ ceiling LLM) |
| 普遍規律層 (著作規律) | どの文書にも効く「良い文書」の規律 | dual-audience / declarative / 1 名 1 語 (canonical name) / HOW を外側へ / domain 分離 / inter-doc 照会 |
| doc-type pack (中身) | その文書型固有の schema + 部品 + gate 詳細 | SRS: EARS・RTM・37 部品 / ADR: context・options・decision・consequences・supersession |
| (別軸) constitution | 採用時のみ効く不変原則 (§5) | optional-but-special |
core⟷pack の境界判定 = 「その機構を新 doc-type に持ち込んだとき改変が要るか」。 改変ゼロで再利用できれば core、 doc-type 固有なら pack。 B1 の実物がこの判定を初めて検証した (§7)。
文書間・文書内の「主張 → 根拠 → … → 終端」のつながり (照会) を、 doc-type 固有語ではなく 抽象ロールで定義する。 core が次の抽象役割と普遍 edge「主張 → 根拠 → 探索 → … → 終端」を定義し、 各 pack が具体語をこの役割へ写像する。
| 抽象ロール | 意味 | SRS-pack の写像 | ADR-pack の写像 |
|---|---|---|---|
| claim | 主張・約束されるもの | 要件 (FR/NFR) | decision (採用した判断) |
| rationale | なぜそれが要るか | 上位ニーズ (N-x) | context (背景・力学) |
| exploration | 検討した選択肢 | (SRS では薄い) | options (選択肢 + 利点/欠点) |
| verification | 満たせたと確かめる基準 | 受入基準 (AC) | (検証手法バッジ) |
| principle | 遡らない終端原則 | (constitution あれば) | principle (照会終端) |
| implementation | HOW 側 (外部化) | tests / コード (照会リンク) | 実装方式 (decision が指す) |
照会終端の規約 = principle があれば principle、 無ければ top-rationale で止める。 既存の folio JSON-LD graph (relations / xref) を描画・格納の基盤に再利用し、 1 名 1 語 (P-5) を保つことで文書横断クエリが可能になる。
★B1 で実証した最難関 edge = cross-doc 照会: ADR の decision (claim) が別文書である SRS の要件 FR2 (予約受付) / FR3 (競合拒否) を正当化する edge を機械 SSoT に持たせ、 参照先 SRS に当該要件 ID が実在することを fail-closed で検証した (§7)。
design-intent (WHAT/WHY) と実装・検証 (HOW) を content として分離し、 HOW へは照会リンクで繋ぐ (本文に HOW を埋めない)。 これを守らせる enforcement は core 同梱の 3-tier:
照会 graph が tier 1 の注入物になる。 これは folio の ADR-0007 (context injection) / ADR-0028 (2-gate enforcement) を一般化したものである。
constitution (不変の最上位原則) は 必須ではない。 採用したプロジェクトに対してのみ、 core が (a) 不変性、 (b) 改訂 gate (P-10 一般化: 改訂は ADR 経由で照会記録を残す)、 (c) 照会終端としての役割、 を保証する。 採用しないプロジェクトでは照会は top-rationale で終端する (§3)。 「必須でないが、 採用時だけ特別扱い」という非対称が要点。
engine は 単一の版ラインで進める (folio の plugin.json 1 版)。 SRS-gen は 1.1.0、 core 抽出 + ADR-pack は後続 MINOR、 と 追記式に積む。 pack は「電池同梱」で folio と版が連動する。 MAJOR (2.0) は contract schema を破壊するときだけ。
★設計制約 (B1 から守る): core 抽出は 既存 SRS contract schema を不変に保つ (抽象ロールへの写像は pack 側に置く) ことで、 非破壊の MINOR に収める。 B1 の ADR-pack はこの制約を守って作った (SRS contract に一切触れず、 ADR から SRS を照会する片方向で実装)。
B1 (folio-bwc) は clinic SRS の FR2/FR3 (二重予約防止) を正当化する clinic ADR を機械 SSoT から生成し、 同一ドメインで SRS + ADR の文書ペアを成立させた。 実物 (.claude-plugin/design-system/generator/) で得た core / pack の切り分けは次の通り。
| 要素 | SRS との関係 | 判定 |
|---|---|---|
inject-prose.sh (prose 注入) | 無改変で共用 (data-slot-id ベースで doc-type 非依存) | core 候補 (強) |
| esc / mark_terms / band / cover / glossary / footer の語彙 | idiom を共用 (関数を流用) | core 候補 |
| 2-gate (floor 機械 ∧ ceiling LLM) の型 | 同型 (verify-adr が verify-fab と同じ規律) | core 候補 |
| fabrication-free 規律 (行数=contract導出 / escape / 集合一致 / fail-closed) | 同型だが対象 schema が違う | core 規律 + pack 適用 |
| contract schema (context/options/decision/...) | SRS と全く別 | pack 固有 |
| section emitter (options card / decision panel / cross-doc justify) | SRS と別構造 | pack 固有 |
| cross-doc 照会の解決 (justifies → 別 contract の req 実在) | SRS には無い新軸 | core 機構 (照会) の pack 適用 |
一次証拠: prose injector が 1 byte も変えずに ADR で動いたこと、 2-gate と fabrication-free の規律がそのまま移ったことが「SRS-pack ∩ ADR-pack = core」を具体的に示す。 一方 assembler 本体は doc-type 固有の section 構造ゆえ fork が要った (= pack)。 core 抽出 (後続別 bd) は inject-prose.sh + 2-gate 型 + fabrication-free 規律 + 照会機構を core へ引き上げ、 assemble の共通 idiom (esc/mark_terms/band/cover/glossary/footer) を共有ライブラリ化する方向になる。
非目標 (rule-of-three の経済性): フル ADR generator 化・複数 ADR・独立版は作らない。 B1 は最小の extraction-probe に留める。