HTML 仕様書 graph 管理の徹底調査

§1. 調査背景

§1.1. folio の核心問題

folio は AI agent (Claude Code) と人間が共同で「仕様書 (architecture spec)」 を書き続ける meta framework。 すべての spec を HTML 形式で記述するルール (P-2) のもと、 ディレクトリ整理 + index + 各仕様書間ハイパーリンクで関係性を表現したい。 ただし、 新規 spec ファイル追加時に 既存ハイパーリンク網に正しく組み込まれ整合性が保たれる仕組み が必要。 一方で HTML ファイル全文を AI agent に毎回読ませると context window が圧迫され管理破綻する懸念がある。

§1.2. Beads パターン類推適用の動機

Beads (github.com/steveyegge/beads) は GitHub Issue の依存関係を Dolt (versioned SQL database) で管理し、 issue 間の関係をグラフとして表現することで AI agent が効率的に dependency を辿れる仕組みを実現している。 これと類推して spec ファイル間の関係 (cross-reference / 依存 / extend / supersede 等)、 要約・メタデータ、 グラフノード構造をデータベース技術で整理し、 AI が HTML 全文を読まなくても全体構造を把握できるか — を検証することが本調査の趣旨。

§1.3. 5 サブ質問

1. HTML/Markdown 文書群の関係性を versioned SQL/graph database で管理する基盤技術の比較
2. SSG (Sphinx, Hugo, MkDocs, Docusaurus, Antora, DocFX) および PKM tools (Foam, Obsidian, Logseq, Roam, DokuWiki, MediaWiki) の link graph 実装パターン
3. AI agent (Claude Code, Continue.dev, Cursor) が大規模 documentation を context window 効率的に扱うための indexing / RAG / graph traversal パターン
4. 仕様書・ADR・dependency tree 管理の OSS 実装事例 (Beads, log4brains, MADR, Specmatic, Spectral, ArchUnit, Backstage)
5. HTML 内 machine-readable metadata 埋め込み技術と spec drift detection

§2. 5 サブ質問の調査結果サマリ

§2.1. DB/graph 基盤技術 (researcher-1)

Beads は Dolt 単一バックエンドへ完全移行 (v1.0.0)

SQLite + JSONL hybrid を捨て、 cell-level merge / multi-writer / built-in version history / native push-pull のためだけに Dolt を選択。 「dual storage の同期複雑性を排除しつつ分散バージョン管理を維持」 が決定打。

Dolt の技術基盤

Prolly Trees (content-addressed B-trees) + Commit Graph (Merkle DAG)。 fast diffs O(d)、 structural sharing、 embedded mode で Go アプリ組み込み可能。 SQL アクセス (MySQL 互換) + dolt_* system tables/procedures で version control 操作。

W3C 標準語彙 (DCMI)

dcterms:replaces が 「supersedes」 関係を W3C 標準としてすでに提供 (URI: http://purl.org/dc/terms/replaces)。 ただし「depends-on」 の標準語彙は存在せず ドメイン固有 ontology が必要。

Property Graph vs RDF

一般的推奨は 「default で Property Graph、 interoperability 必要時のみ RDF」。 AI agent のクエリ生成では Cypher/GQL の方が SPARQL より好まれる傾向 (compact + expressive)。 ただし Beads は意図的に SQL を選択 (SQL は LLM training データが豊富)。

§2.2. SSG/PKM の link graph 実装 (researcher-2)

12 ツールを 4 軸 (ストレージ / Backlink 戦略 / Link 解決 / Broken link 動作) で整理 (詳細マトリクスは §3.2 参照)。 ストレージは大別して 4 種類:

• Flat 圧縮ファイル: Sphinx objects.inv (zlib + 行形式)、 DocFX xrefmap.yml (YAML refs list)
• In-memory Map/Object: Antora ContentCatalog (Map<family, Map<key, file>>)、 Obsidian resolvedLinks (Record<src, Record<dest, number>>)
• RDBMS テーブル: MediaWiki pagelinks + linktarget (immutable、 正規化された varbinary キャッシュ + 整数 FK)
• EAV / Datalog DB: Logseq (DataScript の :block/refs, :block/path-refs)、 Roam (Datomic)、 Foam (graphlib)、 DokuWiki (専用 .idx + Memory/File Index)

§2.3. AI agent 向け doc indexing (researcher-3)

Claude Code は意図的に indexing しない

4 リスク (security, privacy, staleness, reliability) を回避するため。 3-tool hierarchy: Glob → Grep → Read。 深い探索は Explore sub-agent (Haiku) を spawn。 Amazon Science 2026 論文: agentic search は 「over 90% of RAG-level performance without a vector database」 を達成。

Anthropic Agent Skills: Progressive Disclosure (3-tier)

Tier 1 (metadata, 30-50 tokens) → Tier 2 (SKILL.md 本体) → Tier 3 (reference files) の段階的読込で 140x efficiency。 folio HTML 仕様書管理に直接適用可能なパターン。

Microsoft GraphRAG / LazyGraphRAG

GraphRAG: Hierarchical Leiden clustering + community summary。 LazyGraphRAG: 標準 GraphRAG の indexing cost の 0.1% (1000x 削減)、 query-time iterative deepening。 query cost 700x lower。

LlamaIndex DocumentSummaryIndex

folio の 2 段構造 (summary + detail) と最も近い実装。 LLM-based / Embedding-based の両 retrieval mode をサポート。

§2.4. 仕様書 ADR OSS 事例 (researcher-4)

Beads dependency edge schema

9 種類のエッジ: blocks / parent-child / related / discovered-from / conditional-blocks / waits-for / replies-to / supersedes / duplicates。 hash-based ID (bd-a1b2) で分散衝突防止。

Beads Phase metaphor (folio へ完全に写像可能)

Solid (Proto) / Liquid (Mol) / Vapor (Wisp) の三層抽象が folio の constitution.html (frozen) / decisions/*.html (ADR active) / research/*.html (ephemeral) に対応。

Beads AI agent integration: CLI + Hooks > MCP

MCP tool schemas は 10-50k tokens 追加するが、 bd prime (CLI) は 1-2k tokens → 10-50x context efficiency。 folio も同様に folio prime 相当の context injection を CLI で実現可能。

log4brains の Adr.supersedeBy() ―― 双方向リンク自動 materialization

古い側 status を superseded by [new-slug](path) に書換え、 新しい側に Supersedes [old-slug](path) リンクを自動追加。 これは Backstage の bidirectional relations (dependsOn ↔ dependencyOf 等) と同じ思想。 folio の P-10 amendment 戦略に直接転用可能。

MADR の trade-off (ADR-0009)

「freedom が parsing を犠牲にする」 と公式に認めている。 folio は frontmatter (機械可読) + 本文 markdown link (自由度) の dual-track で両立を目指せる余地あり。

§2.5. HTML metadata + spec drift detection (researcher-5)

JSON-LD が 2026 デフォルト推奨

<script type="application/ld+json"> ブロックで HTML 構造から decoupled。 @id による linked data 構築が容易。 microdata は nested で maintenance nightmare、 RDFa は niche shrinking、 HTML5 data-* は MDN が明示的に「機械可読 metadata に非推奨」 と警告。

extruct (Scrapinghub) ―― HTML → DB sync の決定的ツール

HTML から JSON-LD / Microdata / RDFa / Microformats / Open Graph / Dublin Core を統一的に抽出。 標準パイプライン: HTML fetch → extruct で JSON-LD 抽出 → 型チェック → DB 行に正規化。

Sambal モデル ―― JSON-LD ファーストな SSG

HTML page と raw schema.org JSON-LD の両方を生成。 @id で external resources への参照を持つ linked data を、 DB なしで構築可能。

Broken link detection: lychee + hyperlink が最有力

lychee (Rust async, TOML config, anchor 4 modes, GitHub Action 成熟) + hyperlink (Rust file-system only, Sentry docs 1.1GB を 4 秒, flake free) の組み合わせが folio に最適。

Spec drift detection

oasdiff (OpenAPI 用 450+ breaking change rules) のメタファー応用。 検出パイプライン: (i) lychee で anchor 検証、 (ii) extruct で JSON-LD 抽出 + Dolt sync、 (iii) Dolt SQL で relations テーブル整合性検証、 (iv) ADR supersede 関係を log4brains 風に materialize。

§3. 統合観点

§3.1. Beads パターンの完全分解 (researcher-1 + researcher-4 のクロス検証)

両 worker が独立に Beads を深掘りし、 結論が完全一致 ―― 信頼度 high。 Beads 設計の核心 4 判断:

1. Dolt 単一バックエンド (v1.0.0) ―― SQLite + JSONL hybrid を捨てた
2. Hash-based ID (bd-a1b2) ―― 分散衝突防止
3. Phase metaphor (化学 metaphor) ―― Solid/Liquid/Vapor の三層抽象
4. CLI + Hooks > MCP ―― 10-50x context efficiency

§3.2. SSG/PKM link graph 実装マトリクス (researcher-2)

§3.3. Progressive Disclosure (researcher-3)

Anthropic が Agent Skills で実装している 3-tier loading が folio HTML 仕様書管理に直接適用可能:

140x efficiency。 folio は vector DB に頼らず grep-friendly な HTML 構造 を目指すべき (Claude Code は意図的に indexing しないため)。

§3.4. HTML metadata embedding 技術比較 (researcher-5)

§3.5. dcterms:replaces が W3C 標準として "supersedes" を既に提供

folio が JSON-LD で関係性を表現する場合、 独自の folio:supersedes を作らず DCMI 既存語彙を使うべき:

{
  "@context": {
    "dc": "http://purl.org/dc/terms/",
    "folio": "https://folio.dev/spec/v1/"
  },
  "@id": "decisions/ADR-0042-database-choice.html",
  "@type": "TechArticle",
  "dc:replaces": { "@id": "decisions/ADR-0017-original-database.html" },
  "folio:depends-on": { "@id": "constitution.html#P-3" }
}

§3.6. Bidirectional Materialization (log4brains + Backstage)

log4brains の Adr.supersedeBy() メソッド (TypeScript ソースから直接抽出) は、 folio が採用すべき双方向リンク自動化パターン:

supersedeBy(superseder: Adr): void {
  const relation = new AdrRelation(this, "superseded by", superseder);
  this.body.setHeaderMetadata("Status", relation.toMarkdown());
  superseder.markAsSuperseder(this);  // 自動的に逆参照を生成
}

private markAsSuperseder(superseded: Adr): void {
  const relation = new AdrRelation(this, "Supersedes", superseded);
  this.body.addLinkNoDuplicate(relation.toMarkdown());
}

Backstage も同じ思想で 8 対の双方向 relations を提供 (dependsOn ↔ dependencyOf, partOf ↔ hasPart, ownedBy ↔ ownerOf 等)。 folio で同じパターンを採用すれば、 人間も AI も「片方を編集すれば反対側が自動で同期」 する保証が得られる。

§5. 未解決事項・追加調査候補

critique で PASS と判定済だが、 Phase 2 (Dolt 統合) 着手前に取得を推奨する nice-to-have の gap が 4 件:

1. Beads の Dolt 内部 SQL DDL (CREATE TABLE statements verbatim)

docs には table 名と column 一覧は出るが、 index / FK / CHECK 制約の完全な SQL DDL は未確認。 リポジトリの internal/storage/dolt/ 配下の Go ファイル直接読みが必要。

2. schema.org CreativeWork / TechArticle 系の文書間関係プロパティ

isBasedOn, citation, hasPart 等の詳細プロパティが文書間関係表現に使える可能性。 今回は dc:* 語彙を中心に調査したが、 schema.org の補完候補として深掘り余地あり。

3. HTML SSoT graph DB sync の production 事例

SSG (Sambal/Astro/Next.js) では DB→HTML が一般的で、 HTML→DB の事例は extruct を使った scraping/監査用途以外見当たらず。 folio は意図的に新しい設計領域 (草分け) になる可能性。

4. HyDE / GraphRAG を HTML/Markdown documentation に適用した production case study

HyDE は一般 retrieval 用途の事例はあるが、 仕様書 documentation 向けの具体実装は未確認。 GraphRAG / LazyGraphRAG も knowledge base 中心の事例が多く、 spec documentation 向けは限定的。

これらは Phase 2 着手時の設計検討で WebFetch + 追加 researcher spawn で補完予定。 Phase 1 着手には影響しない。

§5.1. 検出された緊張関係 (tensions)

• Claude Code は indexing しない vs Beads は Dolt 採用: 異なる layer の判断 (session 内 retrieval は agentic search、 persistent storage は別途)。 folio は両方を組み合わせる戦略が可能。
• SSG は DB→HTML、 folio は HTML→DB: 方向が逆。 extruct + 独自パイプラインで実装する必要あり (Sambal が一部 hint)。
• MADR 自由度 vs 機械可読性: MADR-0009 で公式に認められたトレードオフ。 folio は frontmatter (機械) + 本文 markdown link (自由) の dual-track で両立可能。

§6. 参照ソース一覧

計 117 件。 全ソースは 2026-05-22 に確認。 公式ソース (Anthropic / W3C / DCMI / MS Research / GitHub README / 公式 docs) は 46% を占める。

§6.1. DB / Graph 基盤技術 (researcher-1)

§6.2. SSG / PKM Link Graph 実装 (researcher-2)

§6.3. AI agent 向け doc indexing (researcher-3)

§6.4. 仕様書 ADR OSS 事例 (researcher-4)

§6.5. HTML metadata + spec drift detection (researcher-5)

§7. 調査メタデータ

調査セッション ID

c3c53fbb (snapshot: /tmp/research-search-c3c53fbb/)

調査日

2026-05-22

使用ワークフロー

/research:controller-search (deep モード) — Plan → Parallel Research (5 workers) → Integrate → Critique → Report の 5 段階

調査担当 researcher 5 名

researcher-1 (DB/graph 基盤) / researcher-2 (SSG/PKM link graph) / researcher-3 (AI agent indexing) / researcher-4 (仕様書 ADR 事例) / researcher-5 (HTML metadata + drift)

合計 WebSearch 回数 / Fetch 成功件数

WebSearch 62 回 / WebFetch 成功 68 件 (5 worker 合計)

品質検証

critic specialist で評価 → Overall Verdict: PASS (Coverage / Relevance / Citation Accuracy / Gap すべて PASS)

本レポートの位置づけ

scratch/research/ 配下の調査資料。 folio rule に縛られない自由形式。 試作 plugin が完成したら archive 候補。