folio の spec は P-2 により HTML で記述する。 現状の audience 非対称は machine に Tier 1 digest (folio prime 派生要約)・human に全文であり、 human 視点では「構造妥当だが字ばかりで読む気がしない」 = 認知負荷が高い。 mermaid 等の図は markdown でも扱えるため、 HTML プレゼンの固有価値は「同一ソース内で audience 別に提示を切り替えられる」点にある、 という問いから本 ADR は出発する。
HTML プレゼンの prior art 調査 (80 sources、 critic PASS 8.3/10) で金脈を得た: DITA conditional processing (@audience profiling) と literate programming (Knuth WEB の tangle/weave) は double-SSoT 問題を完全に同一の原理で解いている — 「単一ソースを一度だけ authoring し、 各 audience view は filtering / 機械変換で生成 (derived) する。 view は独立に維持 (maintained) しない」。 これにより divergence は規律でなく構造的必然として消える。 Knuth 原典 (The Computer Journal 1984, DOI 10.1093/comjnl/27.2.97): "if this were defined in a separate source document, then inconsistencies would be almost impossible to prevent"。 DITA (OASIS): "There is only one source. Deliverables are derived, not maintained"。
folio が grill で選んだ構造は data-audience taxonomy + <details> fold で両 audience を 1 HTML artifact に co-author (no-build で AI が source HTML を直読) である。 方向性 (machine normative = SSoT / human essence = 派生 view) は prior art と一致するが、 1 DOM に両 audience を同居させ human essence を手書き co-author する構造は prior art に存在しない novelty (調査 H3 で Sphinx / AsciiDoc / DocBook / Antora / MkDocs / DITA を比較、 全て build-time の分離成果物)。 co-author は DITA/LP が回避した "independent maintenance → divergence" の罠に自ら踏み込む。
→ 本 ADR の中心命題: folio の ADR-0028 二層 enforcement (validate floor + Phase F review agent ceiling) は、 DITA/LP が「機械的導出」でタダで得る consistency を、 co-author モデルで失う代わりに「強制」で取り戻す代替機構である。 LLM ceiling (fidelity review) は装飾でなく構造の要 (load-bearing)。 本 ADR は dual-audience HTML hub の SSoT モデル・構造・enforcement・human view・普遍性・normative 範囲・JS governance を決定する。 grill (7 問) で各論点を解決済。 status = accepted (user 承認済 2026-05-29)。
dual-audience spec は単一 HTML ソースとし、 progressive disclosure で audience 別に提示する。 machine 精密 normative = canonical SSoT、 human essence + graphical = 派生 view (非規範)。 human view は machine normative の要約であって別物の paraphrase ではない。 machine SSoT は relations.html 系の <script type="application/ld+json"> (JSON-LD inline) に保持し、 これが将来 Option A' (§2.3) で「human view を生成する元データ」になる。
data-audience = closed 2 値 core (machine | human)。 AI 抽出 ([data-audience="machine"]) の決定性と floor 検査の単純化のため 2 値固定。 synonym (data-reader / data-for 等) は P-5 (1 entity = 1 canonical name) により禁止。 継承 (cascade) なし = 明示付与のみ (fold 境界と 1:1)。<details> 視覚 fold: machine 部は DOM に常在 (AI / accessibility-tree / find-in-page に可視) し、 視覚的初期表示のみ畳む。 folio prime が machine 部を抽出注入する = 「AI は AI 用部分だけを読む」。aria-hidden を machine 部に付けない: aria-hidden="true" は accessibility tree から除去するため、 Playwright 等 accessibility-tree ベース AI agent からも不可視となり「AI は読める」目的に反する (調査 verified)。 find-in-page (Chrome/Edge) は閉じた <details> を自動展開するため、 fold は検索からの隠蔽ではない。<aside class="machine-readable" aria-hidden="true"> は meta tag + JSON-LD + 可視 header に既出の冗長な metadata 複製であり、 dual-audience の data-audience="machine" が保持するcanonical normative SSoTとは別物。 後者にのみ aria-hidden 禁止が適用される (本 ADR 自身の aside は前者ゆえ template 踏襲)。現 grill 結論を Option B = co-author + enforce として明示採用する: human essence を data-audience="human" に手書き、 machine normative を data-audience="machine" に併記、 consistency は ADR-0028 floor + ceiling で強制。 利点 = no-build (P-13 整合)・1 artifact・AI 直読・実装単純。 代償 = consistency が構造的でなく強制依存 (LLM ceiling が load-bearing)、 prior art 無し。
Option A' = derive-into-DOM (machine SSoT から human view を build-time 生成し同一 DOM に埋込、 Bikeshed / ReSpec snapshot モデル) を中長期 roadmapとして残す。 consistency が機械的導出で構造的にタダになる利点があるが、 build step が P-13 (no-mandate-build 志向) と緊張する。 folio prime が既に digest を生成している事実は Option A' への自然な拡張点であり、 移行は後続 ADR で評価する。
co-author の consistency を、 ADR-0028 の deterministic floor + LLM ceiling モデルで担保する。
folio validate 構造検査 (ADR-0020 scope 拡張): REQ-DA-STRUCT-1 各 [data-audience="human"] に対応 machine が存在 / -2 machine の JSON-LD @id が human card と一致 / -3 data-audience 値が machine|human のみ / -4 machine 部に aria-hidden 不在 / -5 JSON-LD status と human badge の status 一致。 floor は構造的対応と機械可読 key の一致のみ判定 (意味の一致は判定しない)。spec-review-fidelity が、 各 requirement の human essence が machine normative の正確な要約か (脱落・誇張・矛盾なし)、 EARS pattern badge が normative keyword と一致するかを read-only で LLM 検査する。 これが「機械的導出の代役」の中核。human 向け graphical view は次の 3 要素の Hybrid とする: ① concept flowchart (section 単位 1 枚、 mermaid、 「どう動くか」)、 ② compact list (純 CSS、 1 行 1 REQ、 最小読量、 「何があるか」)、 ③ coverage RTM (requirement × derives × scenario × verified の traceability matrix、 空 mapping = gap を可視化、 trace / coverage が主題の section にのみ)。
dual-audience の各要素は一律普遍でなく段階適用する: dual-audience core (data-audience + fold + essence) は普遍 / concept flowchart・compact list は適用可能な section / trace RTM (REQ → derives P-N/rule) は P-13 ゆえ普遍 / coverage 列 (verified/scenario) は verification mapping を持つ spec のopt-in。
規範範囲は最小に保つ: a11y (rules §4.6 WCAG 等) は MUST。 dual-audience safety invariant (data-audience taxonomy / aria-hidden 禁止 / machine = canonical) はconditional-normative (pattern を使うなら MUST、 使わない自由は残す)。 concept 図 / compact list / coverage RTM / EARS badge / fold の使い所はguidance menu (author・folio-architect 判断、 強制しない)。
JS は render/view の read-only enhancement に限り、 content の SSoT にしない (ReSpec/Bikeshed が共通に守る原則)。 canonical artifact は static HTML。
beforeprint で details 一括 open)。fetch ロード content の SSoT 化 / CDN 実行時取得 script による content 生成 / ES modules + fetch() (file:// で null origin CORS により破綻、 verified)。<script> か inline / inline data は <script type="application/json"> 同梱。bin/folio validate に floor REQ-DA-STRUCT-1..5 を gate 追加 (ADR-0020 scope 拡張)。spec-review-fidelity を新設し ADR-0029 Phase F セットに追加 (folio-architect SKILL Phase F に統合)。spec-review-fidelity) が load-bearing。 ceiling が機能しないと human/machine が乖離しうる。REQ-DA-STRUCT-5 (status 一致) + 将来 CLI 生成 (Option A' 部分適用) が緩和策。folio prime の digest 生成が自然な拡張点。<meta> CSP の実挙動はブラウザ依存の可能性 → prototype で実検証 REQUIRED。| 案 | 採否 |
|---|---|
| Option B: co-author + enforce (採用) | 採用 — human essence を手書き co-author、 consistency を ADR-0028 floor+ceiling で強制。 no-build・1 artifact・AI 直読を優先し、 enforcement = 機械的導出の代役と frame。 LLM ceiling fidelity review を必須化 |
| Option A': derive-into-DOM (build-time 生成) | roadmap 保留 — machine SSoT から human view を build-time 生成し同一 DOM に埋込 (Bikeshed/ReSpec snapshot)。 consistency が構造的にタダだが build step が P-13 と緊張。 中長期に folio prime 拡張として評価 |
| build-time 分離成果物 (DITA-OT / Sphinx / DocBook 正規) | 不採用 — audience 別に分離した成果物は no-build・1-artifact・AI source 直読と非整合。 単一ソース原則のみ借用 |
| aria-hidden で machine 部を隠蔽 | 不採用 — accessibility-tree ベース AI から不可視化し「AI は読める」目的に反する (verified)。 <details> 視覚 fold で代替 |
| graphical を JS で実装 (現 wave) | 不採用 (現 wave) — CSS-only 骨格を先行。 JS は governance ruleset (§2.8) 確立後に read-only enhancement として別 wave |
@audience / literate programming が double-SSoT を「単一ソース + 機械的導出 (view は派生・維持しない)」 で構造保証 → folio の 1-DOM co-author は novelty ゆえ ADR-0028 enforcement が導出の代役。folio validate clean + sandbox GREEN + playwright (light/dark) + spec-review-fidelity PASS。