ADR-0036 — folio-vocabulary glossary derive + partition

§2. Decision

§2.1 folio が canonical folio-vocabulary を author→ship、 consumer は derive (ADR-0034 §2.8 を extend)

folio は folio-framework 語の canonical definition を vocabulary.yaml に上流で author し (folio が所有・SSoT)、 これを ship する。 consumer 側は folio-closed 語を derive (自動 mark) で受け取り、 自身では folio 語の定義を書かない。 これは ADR-0034 §2.8 (glossary Class B = vocabulary.yaml SSoT + HTML view は生成 projection) の extend であり、 SSoT model・hybrid architecture をそのまま継承する。

配布機構 (#130 grill 2026-06-02 確定): vocabulary.yaml は plugin-resident SSoT として folio plugin に同梱し (現 architecture/vocabulary.yaml)、 folio build/fix が $CLAUDE_PLUGIN_ROOT の vocabulary.yaml を直読みして consumer 側の glossary を derive/mark する。 consumer には vocabulary.yaml を置かない (ADR-0024 init は seed しない) — folio を唯一の canonical SSoT に保ち (P-5 1 canonical name / P-7 定義二重化禁止)、 consumer 側 copy の drift を構造排除する (copy 配布案は canonical を 2 箇所に分裂させるゆえ却下)。 実装は folio_glossary_map の探索 candidate に $CLAUDE_PLUGIN_ROOT/architecture/vocabulary.yaml の plugin-resident fallback を追加する (現 root_abs + 親探索の後段、 self-host 時は現探索が既に hit するゆえ additive)。

§2.2 分割ルールの明文化 + vocabulary.yaml domain namespace (P-5 cross-layer)

用語を 2 tier に分割し規約化する:

• folio-closed 語彙 (domain: folio-closed) = folio 所有・固定。 folio が canonical 定義を ship し consumer 側で 自動 derive/mark。
• consumer-domain 語彙 (domain: consumer、 python 等) = consumer 所有・folio 解説不能。 #110 の手動 best-effort のまま (explicit-mark)。

vocabulary.yaml schema に terms[].domain: folio-closed | consumer の namespace 区別を ship 前に追加する。 これは P-5 (1 entity = 1 canonical name) の cross-layer 衝突回避規律である: folio-closed 語 (xref 等) と consumer-domain 語 (同綴の別概念) が canonical ID 空間で衝突し自動 mark が誤定義を貼るのを構造排除する。 fix (auto-mark、 §2.3) / build (glossary.html derive) / validate (gate) は domain: folio-closed 語のみを対象とし、 consumer-domain 語への越権 (自動 mark) を起こさない。 現 vocabulary.yaml の語は全て folio-closed。

§2.3 completeness は best-effort を保存 (REQ-GLOSS-001 据置 + 新 REQ-GLOSS-002 追加、 ADR-0034 を supersede しない)

これは本 ADR の最重要規律である。 「folio-closed は closed set ゆえ機械列挙可能 → NLP 不要で全 occurrence を auto-mark できる」という推論は 非 sequitur である: ADR-0034 §2.8 が auto-detect を却下した理由は 自然語 prose 中の全 occurrence を誤検出なく拾うのが NLP 難問である点 (例: spec が specialist の一部、 SoT が code literal 内、 引用例の中の用語)。 これは集合列挙の問題ではない — closed set は集合を列挙できるだけで occurrence 検出の困難を解かない (現 mask 機構の line-granular hole = task #112/#116/#119 を継承する)。

ゆえに:

• REQ-GLOSS-001 (best-effort) を据置く — 「未 mark 言及を gap-lint しない」を変更しない。
• auto-mark は 新 REQ-GLOSS-002 を best-effort tier で追加する: 「domain: folio-closed 語について folio fix が doc 初出の canonical occurrence を best-effort で auto-mark する」。 主語は build でなく fix (#130 grill 2026-06-02 確定): auto-mark = spec body に term mark (<span class="term">、 hover tooltip のみの no-JS span、 click→glossary は §2.4 で撤回) を挿入する spec mutate ゆえ、 ADR-0035 §2.3 の「fix = graph を整える (spec mutate) / build = 派生 view を出す」分離に従い fix の領分とする (既存 fix Pass 3 = xref auto-wrap / Pass 4 = glossary tooltip populate と同系譜、 build が spec を mutate する設計矛盾を回避)。 全 occurrence の no-gaps normative 化はしない (それは ADR-0034 が却下した NLP-hard occurrence 検出を再燃させ REQ-GLOSS-001 の supersede = P-10 risk になる)。
• partition は 2 tier の境界定義であって既存 tier の縮小ではない (REQ-GLOSS-001 の best-effort はそのまま、 REQ-GLOSS-002 が共存する追加 tier)。

すなわち ADR-0035 決定 1 の「機械検証」は glossary については 「ship された定義の consistency / parity を機械検証する」意味であり、 「全 folio-term occurrence が mark 済」を normative 保証する意味ではない。

§2.4 描画 = hover tooltip のみ (single-SoT derive、 旧 click→glossary.html は S4b-2 dogfood で routing 衝突が判明し撤回)

同じ ship 済 vocabulary.yaml を 2 面に derive する: (1) spec-body の hover tooltip (no-JS CSS-only、 ADR-0034 §2.4 と同機構)、 (2) nav/index から到達する独立辞書 glossary.html ページ。 spec-body の用語 mark から glossary.html へ deep-link はしない (hover-only)。 供給者は artifact 別 (#130 grill 確定): spec-body の marked span (<span class="term">、 hover tooltip のみ) の data-tooltip は fix Pass 4 が plugin-resident vocabulary.yaml の definition から populate し (§2.3 の auto-mark と同 subcommand = spec mutate)、 glossary.html ページは build が同 vocabulary.yaml から derive する生成 projection (view 出力、 二重化回避 = P-7、 definition を 2 箇所に author しない double-SoT 構造排除)。 これは ADR-0034 §2.9 が roadmap (1.x) に置いた「生成 HTML glossary view」を pre-1.0.0 に timing pull-forward するものであり、 §2.9 自身が「非破壊で後付け可」と宣言した項目の timing 変更で決定内容の supersede ではない。

amend (folio-ovi、 2026-06-03): 当初 §2.4 は描画を hover tooltip + click→glossary.html 両方とし、 auto-mark を <a class="term" href="../glossary.html#term-<slug>"> anchor で実装した (S4b-2 SHIP、 commit 6648c11)。 しかし SHIP 後の dogfood で doc 名と被る用語 (constitution / ADR / inventory / prime / vocabulary 等) を glossary へ deep-link すると、 本来その語の実体 doc (例 constitution.html) へ飛ぶべき導線と routing が衝突・冗長化することが判明した。 ゆえに描画を hover-only に転換し、 用語 mark を <span class="term"> (href なし) に統一する。 glossary.html ページは nav/index から到達する独立辞書として存続する (deep-link を失うのみで辞書自体は不変)。 REQ-GLOSS-001/002 は共に span 形に統一され、 区別は manual (001) か auto (002) かのみとなる。

§2.5 enforcement = folio validate に glossary gate 追加

• glossary single-SoT: 生成 glossary.html 全体が vocabulary.yaml からの regen (folio build emit) と byte 一致 (definition drift + 構造 drift 双方を含む = build derive の証明 + 手編集検出)。 実装は nav-regen-drift gate に畳む (index.html と同型の regen-drift、 §2.5 冒頭の 3 gate に新 gate を増やさず glossary 特化を追加)。 同一 canonical 用語を別途 prose で重複定義しない (P-5 SSoT 唯一性)。
• vocabulary-parity: glossary.html の term 集合 == vocabulary.yaml の canonical 集合 (過不足の対称差を報告し drift の所在を surface)。
• term-marked (best-effort、 opt-in): 既存 glossary gate (data-term resolve + tooltip consistency、 ADR-0034 §2.6) を folio-closed 語彙で再利用。 §2.3 により 非 opt-in は no-op (keystone)、 opt-in でも best-effort tier (no-gaps normative にしない)。

slug 化規約 (#term-<canonical>、 canonical 名の space/記号の slug 化) は glossary.html ページ内部の <dt> term id に用いる (nav/index からの直 URL 到達 + in-page 索引用; spec-body の用語 mark は hover-only ゆえ #term- へ deep-link しない)。 実装で確定する (empty-slug fallback + 一意性 gate は S4c)。