背景の root cause 分析は ADR-0038 §1 を参照 (価値の非対称 → gate の非対称 → 16-gate green のまま人間に読めないサイト)。 本 ADR はその機構側の答えを確定する。 独立 5-lens 監査 (wf_8b14e53a) が実測した症状の構造化: (a) 入口の型が不在 — landing に hero / 読者別導線 / getting-started がゼロ、 最初の本文が保守者向け運用注記。 (b) chrome の不在と分裂 — 33 ページが dead-end、 戻り導線 3 方式、 ページ内目次は 1 ページのみ。 (c) 既定表示が読者ニーズと逆 — rules.html は折り畳み 26 個全閉で要件要旨が 1 件も見えず、 index は 28 ADR を丸ごと隠す。 (d) 削る編集の不在 — 単一段落 8,858 字 (監査 2026-06-10 時点実測) の blob、 無定義略語が 1 文に 5〜8 個、 glossary hover の本文 auto-mark 適用 0 件。
重要な対比として、 ADR 層には §1〜§5 の固定 template が既に徹底されており「型化の能力はあるのに、 最も恩恵の大きい入口・ナビ層にだけ型が無い」が核心 gap である (監査 + research の一致した結論)。 また folio build は index / glossary を既に機械生成しており (ADR-0035 / ADR-0036)、 「build が型を所有する」前例は確立済み — 本 ADR はその生成範囲の拡張であって方針転換ではない。 討論の決定 1〜5 (読者層別 / 入口 template / 統一 chrome / バランス型既定値 + toggle / co-author 堅持) と ADR grill G3〜G7 が設計を確定し、 業界パターンの裏付けは presentation-design-patterns research (Diátaxis / NN/g / W3C APG / GOV.UK / MADR ほか 100+ sources) に集約した。
rules に「ページ種別 × 主たる人間読者層」の定義節を新設する (P-14 が存在を要求、 本 ADR が初期割当を確定): 入口層 (landing index / cluster README) = folio を知らない初見の外部開発者。 spec 本文層 = folio を導入済みで仕様を参照・検索する既習 consumer 開発者。 decisions 層 = 設計経緯を時系列で辿る維持者。 glossary = 初見〜既習の横断参照。 機械読者 (AI agent) への正確さは全層で維持する (dual-audience の machine 側は不変)。 以後の提示判断 (見せる / 折る / 削る) はこの定義を物差しとする。
folio build が生成する landing (architecture/index.html) に 4 層の固定型を導入する: (1) hero — h1 + 一文の価値提案 (誇張語禁止・outcome 先行)。 (2) 単一 CTA — 「まずここから」1 本。 行き先は repo README の導入手順 (getting-started ページの新設は tutorial 層の充実時に defer — 空のカードを並べる「正直でない」入口を作らない)。 (3) 読者別 3 カード — §2.1 の 3 読者層を動詞句ラベルで分岐 (「初めて folio を使う →」「仕様・要件を調べる → spec」「設計の経緯を追う → decisions」)。 CSS grid のみ・JS なし・狭幅 1 カラム収束。 (4) cluster 一覧 — 現行の status 別生成リストを温存。 hero 一文とカード文言は curated region (folio:landing-hero、 既存 folio:nav-curated と同じ first-open/last-close 往復保全 idiom) に置き、 型 (構造) は build が所有し、 文言 (意味) は人間が author する — ADR-0033 の co-author 境界と同じ線。 consumer へは folio init が placeholder 入り scaffold を配布する。 文言の確定は実装時に rendered を反復確認して行う (research 制約 (b))。
folio build が全 spec / ADR / glossary / README ページへ marker 領域で 4 種 chrome を注入・維持する: skip-link (body 直後、 W3C APG 準拠) / breadcrumb (nav[aria-label] + aria-current、 schema.org BreadcrumbList JSON-LD は BASE_URL 設定時のみ併注入 = file:// を壊さない二段構え) / ページ内目次 (on-this-page、 h2/h3 から導出) / prev-next。 生成規則:
dc:hasPart 順。 decisions cluster = ADR 番号順 (維持者の仕事 = 経緯を時系列で辿る、 に直結する決定的順序)。 番号順は実在 file の昇順隣接として実装する (欠番 0005 / 0008〜0012 / 0014 / 0016 等は単に飛ぶ — 番号の連続性を仮定しない)。 順序 SSoT の無い research / 孤立文書は prev-next 対象外。ページ種別ごとの既定表示規範を rules に定める (適用対象は living spec・生成物・新規 ADR template。 frozen 文書の本文は不変 — 折り畳み化は本文改変のため適用しない): landing = 全可視 (折り畳みゼロ)。 spec = essence・表・図・見出しは可視 / EARS 全文・経緯・運用注記は折る。 ADR (新規 template) = Context・Decision 可視 / 詳細 fold。 折り畳みネストは 2 段上限、 summary に要旨 1 文、 印刷時は全展開 (@media print)。 あわせて編集規範: 地の文の folio 内部用語は glossary xref (hover 解説) を必須化 (folio-a8y を吸収)、 巨大 prose の構造化 (decisions/README 番号体系メモ blob の解体を含む)、 作業ログ類の人間面からの撤去 (research / git 履歴へ)。
chrome に「人間向け / 機械向け / 両方」の 3 状態 toggle を置く。 実装は classic script が body class を切替えるだけ (DOM 構造不変 = rules §8 の read-only enhancement 範囲、 file:// 動作)。 状態はページ内のみ有効 (永続なし) — 連続閲覧の煩わしさが実機 walk で実証されたら localStorage 昇格 (graceful degradation 付き) する片道を注記する。 toggle JS の導入と同 commit で REQ-DA-JS-2 の機械 gate (spec 内 runtime-CDN script 検出) を validate に追加し (folio-ea9 を吸収)、 統治外 JS の混入を構造的に塞ぐ。
essence / EARS / 決定理由の執筆は人間の co-author に残し (ADR-0033 Option B は再オープンしない)、 機械導出は「書かれた意味を組み合わせて見せる view」にのみ拡大する: cluster README への配下 spec 要旨 (essence) 吸い上げ一覧、 spec 冒頭の概観 card (REQ 件数・状態・図一覧を head metadata から生成) 等。 essence そのものの生成 (derive-into-DOM / Option A') は引き続き roadmap に留める。
folio validate に readability-floor gate を新設する (ADR-0020 scope の拡張): block 3 種 — (1) hero 非空 (landing-hero curated region が空なら fail)、 (2) essence 非空 (machine 節に対応する人間向け要旨の欠落 = 孤立 EARS、 REQ-DA-STRUCT-1 の対称拡張)、 (3) landing dead-end (カード・CTA リンクの実在)。 warn 2 種 — (4) essence の句点数上限 (日本語は語数の決定的計測が不能のため句点近似・warn 止まり)、 (5) 一般 prose の単一段落文字数上限 (可視の人間向け本文のみ。 文字数は CJK でも決定的。 blob 再発の機械的見張り — 8,858 字 blob は essence でなく通常段落であり、 essence 限定では再発を見張れないため research 推奨から適用範囲を拡大)。 machine fold・code・EARS・frozen 文書は scan 除外 (既存 prose_only idiom)。 warn 閾値は corpus 実測で較正し、 block 化は ceiling の指摘頻度を見て判断する。 REQ trace は verification.html に追加し、 gate 追加の golden cascade (validate 出力 1 行増 → 全 validate golden) は確立済みの --accept + diff 検証手順で処理する。
表示層の regen は folio build が一元所有する (index / glossary / chrome / landing — 「nav-regen-drift 系の違反は build で直す」)。 folio fix は graph (reverse-link / xref / tooltip) の materialize 専任。 validate の violation message は対応する remediate tool を名指しする (どの違反をどちらで直すかの迷いを消す)。 この 2 分業を rules に明記する。
| 案 | 内容 | 不採用理由 |
|---|---|---|
| curated 拡充のみ | 既存 curated region に hero 等を手書き | 型が機構にならず consumer に配布されない・gate も張れない (対症療法) |
| 人間向け入口の別ページ分離 | architecture/index.html は機械向けに温存し別 landing を新設 | 入口が 2 つに割れ、 直リンク着地者を救えず、 記述が乖離する |
| client-side JS で chrome 生成 | 閲覧時に JS が目次・パンくずを組み立てる | 静的 DOM に chrome が存在せず、 人間と機械が同じ DOM を見る原則と非対称になる (rules §8 の精神に反する) |
| Diátaxis 4 象限カード (G3 案 C) | tutorial / how-to / reference / explanation の 4 入口 | folio は tutorial/how-to 層が薄く、 空のカードを並べる「正直でない」入口になる — 充実後の移行先として保持 |
| 既存 detector の multi-viewport 化のみ (G7 案 B) | viewport を増やすが detector は mermaid 専用のまま | chrome 崩れに効かず「検査してるつもり」の緑だけ増える — 本討論の root cause の再生産 |
| screenshot golden 回帰 | 全ページのスクリーンショットを golden 比較 | brittle (正当な変更で大量 diff)・golden 容量増。 幾何 detector + artifact 保存 + 人間 walk の組合せが folio の決定性方針に整合 |
| derive-into-DOM (Option A') | essence も build が生成し食い違いを構造的に消す | build に LLM が要り決定性・golden 体系と衝突。 ADR-0033 の roadmap 位置を維持 (討論決定 5) |