folio — architecture/spec/ (framework spec index)

§1. Purpose

本 README は spec/ cluster の index で、 cluster 内 spec file 同士の関係を一望し reader (人間 / AI) のナビゲーションを支える。不変資産の constitution は index 対象外。

本 README は spec/ cluster の index。 cluster 内 spec file 同士の関係を一望し、 reader (人間 / AI agent) のナビゲーションを支える。 repo-root inventory.json は folio inventory CLI で auto-generate される (relations.html §4)、本 README はその人手版 Tier 1 navigation index を兼ねる。

constitution (不変資産、 spec graph scan 対象外の特別枠) は本 cluster の index 対象外。編集禁止、 cross-ref のみ。

§2. File Inventory

spec/ cluster の現在 4 file (rules / folio-self-spec / relations / verification) と本 README の role・status・依存を一覧する。

spec/ cluster の file 一覧 (現在 4 file)
file	role	status	depends-on	extends
`rules.html`	Layer 1 consumer 向け universal rules (markup / naming / EARS / Mandatory Actions)	active (v1.0.0)	`./constitution.html`	—
`folio-self-spec.html`	folio Layer 0 framework 自身の architecture spec (provisional)	stable (v1.0.0)	`./constitution.html`	`rules.html` (§10 cross-ref)
`relations.html`	spec 間の関係性表現規約 (JSON-LD + W3C 語彙 + inventory schema)	active (v1.0.0)	`rules.html`	—
`verification.html`	sandbox verification framework spec (機能単位 use case verification SSoT、 REQ-VER-001〜008)	active (v1.0.0)	`rules.html` + `relations.html`	—
`README.html` (本 file)	spec/ cluster index (本 cluster の navigation)	active (v1.0.0)	—	—

§3. Dependency Graph

spec/ 配下 4 file と constitution の依存関係を図示する (実線 = strong dependency、点線 = soft reference)。

%%{init: {'theme': 'base'}}%%
graph TD
  accTitle: spec/ cluster dependency graph
  accDescr: spec/ 配下 4 file (rules / folio-self-spec / relations / verification) と constitution.html の依存関係を示す graph TD。 実線 = strong dependency (depends-on / hasPart)、 点線 = soft reference (extends / references)。
  CONST["constitution.html
frozen"]:::frozen
  RULES["rules.html
Layer 1 rules"]:::active
  FSS["folio-self-spec.html
Layer 0 self-spec"]:::active
  REL["relations.html
relations spec"]:::active
  README["README.html
spec index"]:::index

  RULES -.->|extends| CONST
  FSS -.->|extends| CONST
  VER["verification.html
sandbox"]:::active
  FSS -->|"references §10"| RULES
  REL -->|depends-on| RULES
  REL -.->|"references §2"| CONST
  VER -->|depends-on| RULES
  VER -->|depends-on| REL
  VER -.->|"references §7.6"| FSS
  README -->|hasPart| VER
  README -->|hasPart| RULES
  README -->|hasPart| FSS
  README -->|hasPart| REL

  classDef frozen fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#333333
  classDef active fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#333333
  classDef index fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px,color:#333333

図 1: spec/ cluster + constitution.html の依存関係。実線 = strong dependency (depends-on, hasPart)、点線 = soft reference (extends, references)。 constitution.html は spec/ 内 (frozen・scan 対象外)、 spec/ 配下 4 file (rules / folio-self-spec / relations / verification) は living spec (継続編集、現 status は §1 の表)。

§4. Reading Order

新規 reader の推奨読書順 (constitution → rules → folio-self-spec → relations → verification) と、編集種別ごとの必読範囲 MUST を示す。

新規 reader (人間 / AI agent) は以下の順序で読む SHOULD。

constitution.html — folio の 14 不変原則 (前提知識、全 spec の基底)
rules.html — Layer 1 consumer project に適用する規範 MUST (markup / naming / Mandatory Actions、 spec edit 開始前必読)
folio-self-spec.html — folio Layer 0 framework 自身の動作仕様 (harness / plugin / bindings、 §7.6 試作 minimal scope)
relations.html — spec 間関係性表現規約 (JSON-LD vocabulary、 spec 編集時に <head> JSON-LD を書く際必読)
verification.html — sandbox verification framework (Phase X3 Step 1〜4 完遂済 / 試作 plugin 実機検証の規範)

spec edit を行う AI agent は最低限 (1) + (2) を必読 MUST、関係性宣言を変更する場合は (4) も MUST、試作 plugin 実装 / 検証時は (3) + (5) も MUST。

§5. Change Log

初期の change log は research の worklog archive へ退避済で、以後の変更履歴 SSoT は git log + 各 ADR + delta marker。本 README には蓄積しない。

初期 (2026-05-22〜24) の change log table は research/spec-readme-worklog-archive.html §2 へ退避した (ADR-0039 §2.4 の作業ログ撤去、 2026-06-11)。以後の変更履歴の SSoT は git log + 各 ADR + delta marker (rules §5) — 本 README には変更履歴を蓄積しない。

§6. Open TODO

Phase X3 由来の未解消事項を 3 つに整理する — frozen file の dogfood failure (§6.1)・defer 事項 (§6.2)・ADR 起票候補 (§6.3)。

§6.1 Dogfood failure (frozen file、 user 判断待ち)

relations.html 導入で生じた既存 frozen file の JSON-LD 旧パターン残存を、 user 指示により head 据え置きで trace する。

relations.html 導入に伴い既存 file に dogfood failure が残存:

file	問題	対応
./constitution.html	`<head>` JSON-LD が旧パターン (`@context` 文字列形式、 `@type: "FolioConstitution"` 等独自型)	user 指示「これ以上いじりたくない」を遵守、 cross-ref のみ更新で head は据え置き。 dogfood failure 残存を許容
ADR-0001 / ADR-0002	ADR-0001 は旧 `@context` 文字列形式だったが 2026-05-25 に構造準拠化 (folio validate が検出 → machine-readable block のみ object 化 + `@id` 追加、 commit 147674b、 user ratify 済)。 ADR-0002 は JSON-LD 自体なし。新 ADR (0003/0013/0015 等) は relations §3.2 pattern (object 形式) を採用	ADR-0001 は machine-readable block を最小 touch で構造準拠化 (decision 本文・legacy key は frozen 不変、 inventory/prime golden 不変)。 ADR-0002 は JSON-LD block 無しで validate/inventory 共に scan 対象外 (skip)。旧 dogfood trace は本行に保持

解消済: folio-self-spec.html の <head> JSON-LD は前 commit (2026-05-22) で新規定 pattern に移行済 (作業ログ archive §2 参照)。

§6.2 Phase X3 進行中の defer 事項 (2026-05-24 集約)

frozen ADR の divergence trace と未解消の既知制限のみを恒久保持する (解消済の作業記録は research archive へ退避)。

Phase X3 起源の defer 事項のうち、 frozen ADR (ADR-0003) divergence trace と未解消の既知制限のみを恒久保持する (frozen は P-10 で修正不可のため、実装との乖離は本表が trace の SSoT)。解消済の作業記録 7 行は research/spec-readme-worklog-archive.html §3 へ退避した (ADR-0039 §2.4、 2026-06-11):

Phase X3 deferred issues (整理 2026-05-24)
項目	severity	内容	解消 timing
Gap 1 (#39344 fix)	LOW (一部解消)	Claude Code `permissionDecision: deny` Bug 群 (Issue #37210 / #33106 / #39344 / #18312) の upstream fix 確認。 Phase 2.5 実機検証で PostToolUse blocking error は機能 (commit 1b18ddb)、 exit 2 + stderr 経路は信頼可能と判明 (REQ-VER-006 SHOULD NOT は維持で問題なし)	upstream fix 公式アナウンス時に full 解消 (現状で実用上影響なし)
verification §3 REQ-VER-007/008 昇格	✓ 完遂	REQ-VER-007 (path boundary) + REQ-VER-008 (README index staleness) を verification.html §3.6 に EARS 文として正式追加 (Stage 2a / D-4)。 ADR-0003 §2.1 は frozen のため update せず、 divergence は本 §6.2 で trace	解消済 (Stage 2a、 commit 54c57b3)
hook 並列順序仕様	MEDIUM	hooks.json 内 2 つの PreToolUse hook (caller-marker + path-boundary) の実行順序 / 1 つが deny 時の他 hook 動作が Claude Code 公式仕様で未明示 (動作は OK 確認済)	upstream docs 更新待ち or 実機検証
Phase 2.5: plugin 構造修正 (hooks/ 配置 fix)	✓ 完遂	当初 `.claude-plugin/hooks/hooks.json` 配置で hook 認識されず (公式仕様 L733: `.claude-plugin/` には plugin.json のみ、 hooks/ skills/ 等は plugin root 直下 MUST)。 fix: git mv で `hooks/hooks.json` に移動、 hooks.json 内 command path を `${CLAUDE_PLUGIN_ROOT}/.claude-plugin/scripts/` に書き換え (scripts/ は P-11 部分隔離維持)	commit 1b18ddb、解消済。 ADR-0003 §2.3 「`.claude-plugin/` 配下に隔離」の適用範囲は scripts/ 等の HOW に narrowing 解釈 (ADR 本文は frozen 維持、 CLAUDE.md §6 + 本 §6.2 で trace)
CLAUDE.md plugin root warning	LOW (恒久 benign)	claude plugin validate で「CLAUDE.md root は project context、 distribute 時は SKILL に移行推奨」 warning。 Stage 1 で folio-architect SKILL.md を実装したが warning は残存 (warning は CLAUDE.md の存在自体が要因で SKILL 有無と無関係と判明)。 project 用として valid	恒久 benign (distribute 時に CLAUDE.md を分離する場合のみ解消)
ADR-0003 §2.1 script 命名 drift	MEDIUM	ADR-0003 §2.1 table の `lint-jsonld` (script name) vs 実装 `check-jsonld-lint.sh` の divergence。 ADR は frozen (P-10) のため修正不可、命名規約は `check-*` prefix 採用 (caller-marker / path-boundary / jsonld-lint と統一)	ADR-0004 起票時に script 命名規約 (check-* prefix) を formal 化、 ADR-0003 との drift を trace
JSON-LD 複数 block 検査	LOW	check-jsonld-lint.sh は試作 minimum で単一 block 前提、 1 .html に複数 `<script type="application/ld+json">` がある場合は連結 parse される	完成形 (ADR-0004 候補、 ajv + pyld 2 層) で multi-block 対応
@context 空 object {} は通過	LOW	試作 Light は `@context` の type が object であることのみ check、中身が空でも allow (scenario で trace)	完成形で semantic check (context resolution) で検出
ADR-0003 §2.1 update-readme-index (mutate) vs check-readme-index.sh (check 型) divergence	MEDIUM (trace)	ADR-0003 §2.1 は `update-readme-index` (自動更新 mutate) を宣言。実装は `check-readme-index.sh` (check 型、 staleness 通知のみ、 file 改変なし)。 ADR は frozen (P-10) のため修正不可。試作 slice として check 型を採用 (副作用ゼロ + jsonld-lint と一貫、理由は check-readme-index.sh §1 comment)。命名も論理名 update-readme-index → check-readme-index (check-* prefix 統一)	完成形 mutate 移行時に ADR-0004 候補で formal 化
ADR-0003 §2.1 script count 6 vs 実装 5 file + plugin-lib	LOW	ADR 宣言 6 script vs 実装 5 file (check-caller-marker / check-path-boundary / check-jsonld-lint / check-readme-index / plugin-lib)。差異: inject-inventory は ADR-0007 で実装済 (経緯は作業ログ archive §3) / link-integrity 未実装 (CI、 Phase X4+) / lint-jsonld→check-jsonld-lint 命名 / plugin-lib.sh 追加 (ADR 未宣言 shared lib)	inject-inventory=Step 5 (Track 2 解消済)、 link-integrity: internal(anchor+fs)=Track 3 `folio validate` に取込 (ADR-0020)・external URL CI script=Phase X4+、命名/lib=ADR-0004 候補

§6.3 ADR 起票候補 (user 承認 MUST)

Phase X3 進行中の ADR 起票候補を一覧する (自動起票禁止・user 承認 MUST、起票済と未起票を区別)。

Phase X3 進行中に逐次起票候補。自動起票禁止 (CLAUDE.md §2)、 user 確認必須:

起票済 (2026-05-25、 decisions/README §3):

✓ ADR-0004 JSON-LD lint mechanism (試作 Option B Light = jq 構造 check、完成形 ajv+pyld 2 層は defer) — retrospective
✓ ADR-0006 caller marker hook (hybrid: env var OR marker file) — retrospective
✓ ADR-0007 context injection (SessionStart + PreCompact、 Beads-inspired) — forward (Track 2)
✓ ADR-0017 verification の unit (sandbox) vs integration (e2e) 境界 — retrospective (Track 1/2 後)
✓ ADR-0018 CLI golden-diff verification harness (kind:cli-golden、 Track 1 実装後 retrospective)
✓ ADR-0019 path boundary hook (Option Pragmatic: content-marker 検出)
✓ ADR-0020 folio validate 試作 scope (内部 link-integrity + jsonld structural、 Track 3 forward) — 実装は spawn

起票候補 (未起票、 user 承認 MUST):

ADR-0008 3 層防御原則 (全体設計まとまった時点)
ADR-0014 — 見送り (verification §3.5 で実質規範化済)
ADR-0016 exit code 中心 assertion (Gap 1 解消後)