relations.html §3.2 は spec / ADR / cluster-readme の <head> JSON-LD pattern を規定する (object 形式 @context + @id + @type 必須)。 rules.html §10.2 REQ-CI-016 は CI gate として JSON-LD validation を要求する。 ADR-0003 §2.1 は PostToolUse hook の一つに「JSON-LD lint」 を列挙したが、 validation mechanism (どの tooling で何を check するか) は未確定で、 ADR-0003 §3 Neutral に「ADR-0004 候補」 として defer されていた。
plugin-architecture-research / plugin-sandbox-verification-research の調査では、 JSON-LD validation の業界標準として ajv (JSON Schema による構造検証) + pyld (JSON-LD context expansion による semantic / unmapped property 検出) の 2 層 approach が確認された。 一方 folio は「動くものを先に作る」 試作駆動 (ADR-0003 §1) を採るため、 試作段階で full 2 層を導入するか軽量実装に留めるかの判断が必要だった。
Phase X3 試作の JSON-LD lint は .claude-plugin/scripts/check-jsonld-lint.sh として PostToolUse (Write) hook に実装し、 純粋 shell (jq + bash + sed) による構造 check に留める。 検証内容は以下の 3 点:
@context / @id / @type) が存在@context が object 形式 (旧 string 形式は deny、 relations.html §3.2 新 pattern への移行を強制)対象 scope は Write tool のみ + .html のみ + 単一 JSON-LD block 前提。 JSON-LD block 不在の .html は通過 (spec/ADR/cluster-readme 以外の可能性)。
完成形では ajv (JSON Schema 構造検証) + pyld (semantic + unmapped property 検出) の 2 層 validation に拡張する。 Edit tool 対応 (file 再読込) および複数 JSON-LD block 対応も完成形で扱う。 本 ADR は試作 scope (Option B Light) の確定のみを規定し、 完成形は本 ADR の後継 revision または successor ADR で扱う。
lint は PostToolUse に配置する (tool は実行済、 exit 2 + stderr は user への notify)。 試作段階で relations.html §3.2 conformance は SHOULD level であり、 write 前 block (PreToolUse) は valid edge case の false-block リスクを伴うため見送る。 PreToolUse 化は完成形の upgrade path として残す。
jq + bash のみ。 試作駆動「動くものを先に」 に整合@context 移行の強制: 旧 string 形式 @context を deny し relations.html §3.2 新 pattern を enforcescenarios/jsonld-lint.yaml 12/12 PASS + e2e walk S-B3 (string @context → notify) で live 発火確認@context (constitution.html / ADR-0001 / ADR-0002) は retrofit せず (dogfood failure、 specs/README §6.1 で trace)| 案 | 採用しなかった理由 |
|---|---|
| 案 A: ajv + pyld 2 層を試作で即導入 | node / python 依存 + 導入 overhead が試作駆動「動くものを先に」 (ADR-0003 §1) と矛盾。 完成形へ defer |
| 案 B (採用): Option B Light = jq + bash + sed 構造 check | 純粋 shell・依存ゼロ・即着手可能。 object @context 移行 enforce に十分 |
| 案 C: JSON-LD validation を実装しない | REQ-CI-016 (rules §10.2) が未 enforce、 relations §3.2 conformance を検証不能。 試作の核心機能 (schema check) を欠く |
| 案 D: PreToolUse で write 前 block | 試作段階の conformance は SHOULD level。 valid edge case の false-block リスク。 PostToolUse notify で十分、 block 化は完成形 upgrade path |
.claude-plugin/scripts/check-jsonld-lint.sh (PostToolUse Write hook、 hooks.json 宣言)@context + @id + @type pattern).claude-plugin/)check-jsonld-lint.sh header の「ADR-0004 候補で trace 予定」 を起票確定する (retrospective、 実装 + e2e 検証後)