folio の architecture 内には defined-object (principle P-N / requirement REQ-* / decision ADR-NNNN / rule §) と glossary 用語 (SSoT / dual-audience / EARS 等) が多数存在する。 現状これらは一意 canonical 定義を持つが、 他所からの参照は手動 <a href> に依存し穴が空く (例: principle への手動 cross-ref が 39 件あるが、 残る言及はリンクされていない)。 user / AI が「ある object の最も詳しい定義」へ確実に辿れず、 human は用語の意味を毎回想起できず、 AI は normative 読解時に参照先を構造的に辿れない。 単に手で link を張るだけでは作業に穴ができ長期的に劣化する — これを穴を作らない system として組み込むのが本 ADR の課題である。
本課題の維持性の核心は ADR-0033 (dual-audience) と同型の金脈にある: 「導出 (derive) = 構造的に穴なし」 vs 「手動 = 穴」。 この選択を裏打ち/補正するため /deep-research (multi-agent web research、 106 agent、 24 source fetch、 25 claim を 3-vote 敵対的検証 → 23 確認/2 棄却) で外部知識を調査した (in-band 埋込 / 外部 DB / 非 DB index / hybrid の 4 architecture、 ReqIF・ISO 29148・ISO 704 等 RE 標準、 Sphinx/rustdoc/SCIP の完全性検出、 beads/Dolt の DB-backed AI 知識基盤)。
研究の結論は明確に hybrid (4 goal — 長期安定 / 再現性 / human 見やすい / AI 使いやすい@大規模 — すべてで 1 位): canonical 定義は git-tracked flat HTML に in-band SSoT として残し、 そこから read-only な structured projection (完全性 lint + AI-graph) を生成する。 DB に canonical state を置かない。 主要 verified 根拠:
.beads/issues.jsonl) は明示的に SSoT でなく、 authoritative な Dolt DB は gitignore され sync も git でなく Dolt remote 経由。 → DB 採用は git-diff 可能な canonical file を「lossy export」に降格させる = folio の「要件定義書 = git-tracked portable artifact」前提と矛盾、 最高 migration risk。P-*/REQ-*/ADR-* ID と同型)。 ReqIF が query store でなく flat interchange format である事実自体が「portability の正解は DB でなく flat」を裏づける。 ISO 704 は定義を concept に束ね term は designation (= folio の vocabulary.yaml の canonical/forbidden/definition と同型)。 ISO 29148 は要件の completeness/consistency/verifiability を規範化 (folio の no-gaps 目標を追認)。broken_intra_doc_links / SCIP の「broken-link で fail」= 必要な機械的完全性機構。 SCIP はhuman-readable な string ID で索引するため生成 index が人間可読かつ AI 可辿。 → folio の validate + fix は同じ実証済 family で novel risk でない。重要な棄却 claim (0-3): 「JSON-LD @context が term ごとに単一 canonical IRI を保証する」は棄却された。 → 「1 object = 1 canonical SSoT」は format から仮定できず、 authoring 規律 + completeness/uniqueness lint で enforce する MUST。 これは folio の enforce-not-assume 哲学 (ADR-0028 二層 enforcement) と完全に整合し、 本 ADR の validate gate を正当化する。
→ 本 ADR の中心命題: defined-object/term の cross-reference を in-band SSoT + 生成 projection の hybrid で構成し、 維持は ADR-0025 の materialize pattern を拡張した folio fix auto-wrap で「穴を埋め」、 完全性は folio validate で機械保証する。 DB-as-SSoT は却下 (研究が最高 risk かつ不要と判定)。 本 feature は user 提案により 1.0.0 前に追加すべき機能であり、 ADR-0030/ADR-0032 の 1.0.0 timing を gate する。 grill (13 問) で各論点を解決済。 status = proposed (user 承認待ち)。
cross-reference の canonical 定義は各 object の in-band HTML 要素 (その id) を SSoT とする。 そこから read-only な structured projection (完全性 lint + AI-graph) を生成する — projection は派生・disposable・再生成可能で SSoT でない。 外部 DB に canonical state を置かない (DB-as-SSoT 却下、 §4)。 大規模 query 用の MCP server は projection 上の read-only 公開として roadmap に置く (Pole-2 scale 対応、 §2.7)。 本構成は P-2 (HTML) / P-13 (no-mandate-build) と整合するため constitution を touch しない (P-10)。
P-N) / requirement (REQ-*) / decision (ADR-NNNN) / rule (§ section) の 4 つ (既に de-facto ID 有り)。 EARS keyword・doc-type は語彙的ゆえ glossary (Class B、 §2.8) が扱う。P-*→constitution / REQ-VER-*→verification / REQ-REL-*→relations / REQ-CI-*・REQ-DA-*→rules / ADR-*→decisions / rule §→rules。id を持つ要素が、 その prefix の SSoT doc 内にある = 定義 site」。 他所の <a href="…#id"> は reference site。 新規 attribute 不要 (既存 id + registry で lint が定義/参照を判別)。 REQ の定義 site は ADR-0033 の dual-audience card であり、 その human essence が tooltip text になる。REQ-CI-*/REQ-DA-* 等は table/EARS-list で id 付き定義要素を欠く可能性 → これらを統一 markup に正規化する作業を含む。inline 参照は untyped な xref (<a class="xref" href="…#id" data-tooltip="essence">) とする。 「定義へのリンク」の用途 (読みやすさ + nav + 完全性検査) に十分で、 結果として生じる "X mentions Y" edge が AI graph を満たす。 typed/directional relation ("refines"/"verifies"/"supersedes" 等、 ReqIF SpecRelation 相当) は既存の file-level JSON-LD (relations.html の dc:references/folio:depends-on) + coverage RTM に留め、 object-level 拡張は roadmap とする (全 mention への型強制はしない)。 untyped である事が §2.5 の auto-materialize を可能にする (型を機械選択できないと auto-wrap が破綻するため)。
tooltip は human のみの読みやすさ enhancement (AI は href/graph を辿るため tooltip 不要)。 baseline は常に動く xref リンク (click → 定義 + 既存 :target flash、 ADR-0033 の RTM deep-link pattern)。 その上に no-JS CSS-only tooltip (:hover + :focus-visible で styled box) を載せ、 text は folio fix が定義 essence からコピーした data-tooltip 属性から供給する。 JS (tippy 系の rich/interactive/cross-doc preview tooltip) は §8 JS governance 準拠の roadmap とし、 1.0.0 core には入れない (user の JS 慎重 + archival pristine を保つ)。 no-JS markup (href + data-tooltip) は将来 JS と前方互換 (同属性を読んで rich 表示、 非破壊で重ねられる)。
維持モデルは ADR-0025 の broken-reverse materialize の精密な再利用とする: 著者は prose に裸で P-5/REQ-VER-001/ADR-0033 と書く → folio validate が「リンクされていない object-token」を検出 → folio fix が <a class="xref"> に自動 wrap + data-tooltip を定義 essence から生成。 build step 不要 (P-13 整合)、 手動の手間ゼロ。 scoping:
fix は初出を wrap (全 occurrence でなく — AI graph は edge 1 本で足り、 human も 1 doc 1 入口で読みやすい)。P-N/REQ-*/ADR-NNNN、 regex で確実に拾える)。 rule (§) は canonical token を持たない (「§7.3」は doc 跨ぎで曖昧) ため explicit xref tier (resolve 検査 + tooltip + graph edge は得るが裸言及の auto-gap 検出はしない)。folio_prose_only 流用): 自身の定義要素内 / code・machine block (<pre>/<code>/JSON-LD/dual-audience machine) / 見出し (<h2>/<h3>) / 既に <a> 内 — は wrap しない。ADR-0020 の validate scope を拡張し、 deterministic floor として 4 gate を追加する (棄却された JSON-LD 保証の代わりに lint で enforce):
xref (canonical-ID 形の href target) が既存の定義 site に解決する (broken xref 検出)。data-tooltip が定義の現 essence と一致 (drift 検出、 fix 再生成)。AI-graph は新フォーマットを作らず 既存 projection を object/term-level に拡張する: in-band の個々の <a class="xref"> リンクが edge の SSoT、 inventory.json (relations §4 schema) を node (canonical object: id/class/SSoT-location/essence) + edge (xref 集計) で拡張、 folio prime に compact object-index を追加 (in-context AI 用)。 鮮度: projection (inventory/prime) は gitignore・再生成ゆえ VCS に stale が残らない; in-HTML の data-tooltip コピーは §2.6 の tooltip-consistency gate + fix 再生成で managed (既存 golden 規律と同型)。 MCP server over projection は roadmap (大規模 query = Pole-2、 1.0.0 は inventory/prime の in-context graph まで)。
glossary 用語 (Class B) はbest-effort tier として defined-object (Class A) の no-gaps とは別扱いとする (自然語の全 occurrence 検出は NLP 難問、 棄却 claim と同じく term 完全性は約束しない)。
vocabulary.yaml の definition field (ADR-0031 §2.4 enrich、 ISO 704 concept model: canonical = 主 designation / forbidden = 別 designation / definition = concept 定義)。 HTML glossary view は vocabulary.yaml からの生成 projection (二重化回避、 P-7)。vocabulary.yaml を新規作成 (現状 fixture のみ) — folio canonical 用語 + 定義を載せ、 dogfood + glossary SSoT とする。<dfn> or <span class="term" data-term="…"> で mark した箇所だけ、 Class A と同じ CSS tooltip 機構を再利用)。 auto-detect / gap-lint しない。1.0.0 MVP: (1) object-identity 形式化 + rules.html marking 正規化、 (2) in-band untyped xref markup、 (3) no-JS CSS-only tooltip + 動くリンク baseline、 (4) folio fix auto-materialize、 (5) folio validate 4 gate、 (6) inventory.json object-graph 拡張 + prime index、 (7) 全既存 spec への dogfood 適用 (~60-80 object を接続、 「実用に耐える」検証)、 (8) glossary 機構 (folio vocabulary.yaml 新規 + explicit-mark tooltip + starter population)、 (9) 本 ADR + rules §amend + folio-self-spec/relations 反映。
roadmap (1.x、 非破壊で後付け): MCP server over projection / JS rich tooltip / typed object-level relation / RULE-* token scheme / glossary 全 population / 生成 HTML glossary view。
実装は ADR-0033 同様 多段 SPAWN (規範+enforcement → 適用層+dogfood) で行い、 PARENT が validate clean + sandbox GREEN + playwright + review + golden 再生成 + ff-merge する。 spec 編集 (architecture/spec/) は caller-marker dance で gate される。 本 ADR は constitution を touch しない。
| 案 | 採否 |
|---|---|
| hybrid: in-band SSoT + 生成 projection (採用) | 採用 — 研究ランクで 4 goal すべて 1 位。 canonical 定義を flat HTML に残し projection を生成。 既存機構の拡張で constitution 不変、 低 migration risk、 MCP roadmap で Pole-2 も確保 |
| external-DB as SSoT (beads/Dolt 型) | 却下 — 研究の決定的反証: DB を authoritative にすると git-diff 可能な canonical file が gitignored「lossy export」に降格し、 sync が git でなく DB remote 経由になる (beads ARCHITECTURE.md verified)。 「要件定義書 = git-tracked portable artifact」前提と矛盾、 最高 migration risk、 かつ flat JSON-LD で RDF 級 traversal が届くため不要。 user の「constitution を変えてでも DB を」の問いへの研究の答え = 「変える必要は無い・変えると最高 risk」 |
| non-DB-index 単独 (projection のみ、 in-band link 無し) | 不採用 — index だけでは human の in-text 参照 (tooltip/nav) が成立せず、 SSoT と index の対応も弱い。 in-band link を SSoT に、 index を projection に、 の hybrid が優位 |
| in-band 手動リンクのみ (projection/lint 無し) | 不採用 — まさに現状で「穴ができる」。 完全性の機械保証が無く長期劣化する (user が明示的に拒否) |
| typed/directional relation を全 inline mention に強制 | 不採用 (core) — authoring 負担増 + 型を機械選択できず auto-materialize が破綻 (= 手動の穴が復活)。 typed relation は file-level + roadmap に留める |
| JS rich tooltip を 1.0.0 core に | 不採用 (core) — folio 初 JS + cross-doc は file:// fetch 破綻 + AI 無関係。 no-JS markup は JS と前方互換ゆえ roadmap で非破壊後付け可。 §8 governance 準拠で 1.x に |
/deep-research (106 agent、 24 source、 23/25 claim 確認) で in-band/DB/非DB-index/hybrid を 4 goal で比較 → hybrid が全 1 位、 DB-as-SSoT 却下、 「単一 canonical は format で保証不可 = lint で enforce」 (棄却 claim) を確認。bin/folio の fix auto-materialize + validate 4 gate + inventory/prime 拡張) → PARENT review → ② 適用層 (全 spec dogfood + marking 正規化 + glossary 機構)。 検証 = folio validate clean + sandbox GREEN + playwright (tooltip light/dark) + golden 再生成。