ADR-0001 — architecture-rules.html を rules.html + folio-self-spec.html に分離 (v3)

Status: accepted · Date: 2026-05-22 · Revision: v3 · folio v0.4.1-draft → v0.4.2-draft (PATCH bump)

§1. Context

v0.4.1-draft 時点で architecture-rules.html は以下の 2 種類の異質な内容を 1 file に混在して保持している。

この混在は以下の問題を生じる。

  1. 名前と内容の乖離: 「architecture-rules」 は (A) を示唆するが、 実体は (A) + (B) の hybrid。
  2. SSoT 違反疑い (constitution P-7): constitution.html §3 (Layer Architecture) + §4 (Folio as a Plugin) が architecture-rules §1 + §8 と内容重複。
  3. self-application paradox: folio framework 完成後、 (B) は folio 自身の architecture/spec/ 配下に self-application されるべき (dogfooding)。 v0.4.1 段階では未完成のため「仮組み」 として (A) と同居。

ユーザーは v0.4.1-draft dig セッション (2026-05-22) で本問題を指摘:

architecture-rules の立ち位置がよくわからない。 folio の architecture spec 的な内容が書かれているが、 それこそ architecture-spec として定義したい構造をとっていない。 ……architecture-rules という名前が分かりづらい。 ようは仮組みの folio の未来 spec 的な性格なのだと思うのだ。

Phase 2 Codebase Exploration (3 並列 explorer agent、 2026-05-22 afternoon) で以下を発見:

  1. cross-ref 影響: 30+ 箇所 (constitution.html 12 箇所 + CLAUDE.md 6 箇所 + その他)。
  2. §0 Reader Guide の 2 persona aside は実は split 後の 2 reader を内包 → 片方特化が筋良い。
  3. §9 Bindings は全 binding location が .claude-plugin/ 配下 → folio-self-spec.html 一本化が SSoT 遵守。
  4. §7 内部混在: §7.3 + §7.5 は MUST 文 / design 文の分離が必要。
  5. constitution §1 Purpose 補強位置: 冒頭 p の直後 (独立 p) が narrative 整合性最良。

Phase 4 Architecture Design (2 並列 architect agent、 2026-05-22 evening) で以下を refine:

  1. rules.html 番号体系: 欠番維持 (§0 / §2 / §3-§6 / §10、 §7-§9 欠番) で folio-self-spec.html (§7-§9) と対称的空白に。
  2. §10 markup: EARS REQ-ID (REQ-CM-* + REQ-CI-*) + <table> 形式で reader experience 最大化。
  3. commit 3 scope は実際 10+ 操作点 (ADR v2 「5 箇所」 表記は粗い)、 行番号付き precise list 必要。
  4. main 直接 commit は broken link time window high severity、 feature branch + draft PR squash merge 推奨。
  5. mermaid 図移植の漏れリスク (constitution 図 3 ノードラベル + architecture-rules 図 1/2 ノードラベル)。

§2. Decision

Phase X2 開始時に以下の作業を実施する MUST。

§2.1 architecture-rules.html を 2 file に split

section 帰属 (v2 確定、 v3 で再掲):

section / 要素帰属備考
§0 Reader Guide (Developer persona)rules.html §0Layer 1 consumer 開発者向けに書き直し
§0 Reader Guide (AI Agent persona)folio-self-spec.html §0caller marker 操作手順 + folio plugin の読み方
§1 2-Layer Architecturefolio-self-spec.html §1mermaid 図 1 + table 移植
§2.1 folio repo layoutfolio-self-spec.html §2mermaid 図 2 移植
§2.2 Layer 1 consumer layout + folio.config.yamlrules.html §2—
§3 File Namingrules.html §3—
§4 HTML Formatrules.html §4—
§5 Delta Markerrules.html §5—
§6 EARS Notationrules.html §6—
§7.1〜§7.5 (informative design 部)folio-self-spec.html §7MUST 文は rules §10 への cross-ref に置換
§7.3 Caller Marker MUSTrules.html §10.1EARS REQ-CM-001〜003
§7.5 CI Gate MUST (6 gate 定義)rules.html §10.2EARS REQ-CI-001 + REQ-CI-010〜015
§8 Plugin Integrationfolio-self-spec.html §8—
§9 Bindingsfolio-self-spec.html §9一本化 (SSoT 遵守)

rules.html applicability statement (§0 内に inline):

本 rules は Layer 1 consumer project (folio framework を consume する各 project repo) に適用する。 Layer 0 (folio framework 本体) の設計は folio-self-spec.html を参照。

§2.2 architecture-rules.html 冒頭に provisional aside を追加 (commit 1)

commit 2 の split 前段階として、 commit 1 で architecture-rules.html 冒頭 (<body> 直後、 既存 <aside class="informative"> の前) に provisional aside を追加する。 split 完了 (commit 2) と同時に本 aside は撤去。

§2.3 constitution.html §3 §4 を cross-ref スタブに縮小 + §1 Purpose 補強

constitution §3 縮小文 (実装と整合、 anchor は long-form):

folio は Layer 0 (本 repo) + Layer 1 (consumer projects) の 2 層を採用する (P-12)。 詳細 (2-Layer 体系図 + table + Resolution flow) は folio-self-spec.html §1、 consumer project の directory layout は rules.html §2 を参照。

constitution §4 縮小文 (実装と整合、 anchor は long-form、 MCP 不採用宣言を保持):

folio は Claude Code plugin として配布される (P-12)。 plugin 構造の詳細は folio-self-spec.html §7 + §8。 folio harness は skill + hook + CLI (local process) のみで構成し、 MCP (Model Context Protocol) は採用しない。

constitution §1 Purpose 補強 (冒頭 p の直後、 独立 p):

folio は Layer 0 META FRAMEWORK であり、 各 consumer project は Layer 1 として別 git repo に展開される (P-12)。 Layer 0 は rules (constitution + rules.html) と plugin harness (.claude-plugin/) を一体配布し、 Layer 1 は folio.config.yaml 1 file の宣言で全体を consume する。

constitution §5 / §6 / §7 の番号は維持する (renumber しない)。 mermaid 図 3 + 図 4 を constitution から削除、 folio-self-spec.html へ移植 (詳細は §2.8)。

§2.4 SemVer bump + constitution P-2/3/11/12 plain text 修正

本 ADR 適用は不変原則 (P-1〜P-12) の semantic を変更しない。 P-2/P-3/P-11/P-12 の plain text file 名列挙を以下に書き換える:

原則現文 (抜粋)改訂案
P-2 "spec / ADR / constitution / architecture-rules / changes proposal を含む全文書" "spec / ADR / spec writing documents (constitution / rules / folio-self-spec) / changes proposal を含む全文書"
P-3 "spec / constitution / architecture-rules に platform 固有 HOW を記述しない" "spec / constitution / rules / folio-self-spec に platform 固有 HOW を記述しない"
P-11 "spec / constitution / architecture-rules に HOW を書かない" "spec / constitution / rules / folio-self-spec に HOW を書かない"
P-12 (rules 言及部) "rules (constitution + architecture-rules) と plugin harness を一体として配布" "rules (constitution + rules + folio-self-spec) と plugin harness を一体として配布"

SemVer 判定: PATCH bump (v0.4.1-draft → v0.4.2-draft、 constitution.html / rules.html / folio-self-spec.html / plugin.json すべて同 version)。 constitution §5 cross-ref 補正規定の延長として解釈。

P-10 (constitution 自身への変更前 user 確認): 本 dig session (2026-05-22) でユーザーが P-2/3/11/12 改訂を承認済。 commit 3 で改訂箇所に <aside class="ai-rationale" data-decision="2026-05-22" data-adr="ADR-0001-v3" hidden> を inline で添付し、 P-10 承認を文書化する。

§2.5 commit 粒度 — Precise List (v3 で行番号付き 10+ 操作点に refine)

4 commit に分割。 各 commit の precise file operations:

commit 1 — provisional aside 追加 (+ ADR-0001 v3 起票)

file行 (approx)操作
architecture-rules.htmlL30 (<body> 直後)provisional aside (約 14 行) を L37 既存 <aside class="informative"> 直前に挿入
decisions/ADR-0001-architecture-rules-split.html新規 (本 file)git add (decisions/ dir 新設)

commit 2 — split (rules.html + folio-self-spec.html 作成 + architecture-rules.html 削除 + common.css 更新)

file行 (approx)操作
rules.html (新規)0 → 約 250 行§0 (Developer persona) + §2 + §3〜§6 + §10 Mandatory Actions 新設
folio-self-spec.html (新規)0 → 約 500 行§0 (AI Agent persona) + §1 + §2 + §7 informative (MUST cross-ref 化) + §8 + §9
architecture-rules.html全削除git rm
common.css末尾.normative-ref CSS class 追加 (font-weight: bold; color: var(--folio-danger))

新 file の <meta folio-version> は 0.4.2-draft で開始 (commit 3 で constitution と version 整合)。

commit 3 — constitution 修正 (10+ 操作点)

file行 (approx)操作
constitution.htmlL7 (meta)folio-version を 0.4.1-draft → 0.4.2-draft
constitution.htmlL52 (§0 AI Agent aside)2 href (architecture-rules.html / #s7-3-caller-marker) を rules.html + folio-self-spec.html 分割 (#s7-3-caller-marker は folio-self-spec.html へ)
constitution.htmlL63 (§1 冒頭 p 直後)Layer 概念 1 文 (独立 p、 §2.3 文面) を挿入
constitution.htmlL124 (P-2 dd)plain text 修正 (§2.4 改訂案) + P-10 inline aside 添付
constitution.htmlL127 (P-3 dd)plain text 修正
constitution.htmlL158-L159 (P-11 dt + dd)plain text 修正
constitution.htmlL162 (P-12 dd)plain text 修正
constitution.htmlL164 (P-12 ai-rationale aside)"architecture-rules §7.4" → "folio-self-spec.html §7.4"
constitution.htmlL170-L205 (§3 全体)本文 + mermaid 図 3 削除、 cross-ref スタブ (§2.3 文面、 href 付き) に縮小
constitution.htmlL208-L240 (§4 全体)本文 + mermaid 図 4 削除、 cross-ref スタブ (§2.3 文面、 href 付き) に縮小
constitution.htmlL259 (§5 内 link)"architecture-rules.html#s5-delta" → "rules.html#s5"
constitution.htmlL273 (§6 内 link)"architecture-rules.html#s7-1-7phase" → "folio-self-spec.html#s7-1-7phase"
constitution.htmlJSON-LD (L13-L21)tiers metadata 維持 (P-1〜P-12 数 + tier 不変)

commit 4 — cross-ref 一括 + ADR status accepted + 全 version 整合

file行 (approx)操作
FOLIO.mdL14 (ASCII 図)"architecture-rules.html" を "rules.html / folio-self-spec.html" に 2 行分割
FOLIO.mdL74 (Entry points)同上
FOLIO.mdL83-L87 (AI Agent 手順)read 順序更新 + §7.4 参照 → folio-self-spec.html §7.4
README.mdL22 (table)2 行分割
README.mdL43-L44 (tailnet URL)2 URL 分割
README.mdL55 (§7.4 参照)folio-self-spec.html §7.4
CLAUDE.mdL3 (§9 Bindings 参照)folio-self-spec.html §9
CLAUDE.mdL18 (必読 list)rules.html + folio-self-spec.html (2 file)
CLAUDE.mdL28 (caller marker)"§7.3" → "rules.html §10.1 + folio-self-spec.html §7.3"
CLAUDE.mdL40 (§7.4 参照)folio-self-spec.html §7.4
CLAUDE.mdL55 (5 層防御 table)folio-self-spec.html §7.4
CLAUDE.mdL65 (format ルール)"architecture-rules" → "rules + folio-self-spec"
CLAUDE.mdL70 (plugin 構造)folio-self-spec.html §8
CLAUDE.mdL99 (§9 Bindings)folio-self-spec.html §9
.claude-plugin/plugin.jsonL3 (version)"0.4.0-draft" → "0.4.2-draft"
.claude-plugin/skills/README.mdL20folio-self-spec.html §7
.claude-plugin/agents/README.mdL20folio-self-spec.html §7.2
.claude-plugin/scripts/README.mdL19"rules.html §10.2 + folio-self-spec.html §7.5" に分割
.claude-plugin/static/README.mdL7"rules.html / folio-self-spec.html"
decisions/ADR-0001-architecture-rules-split.htmlL8 (meta status)"proposed" → "accepted"
decisions/ADR-0001-architecture-rules-split.html§5 Tracedoobidoo conversation_id 記録 (commit 4 push 後に追記)

§2.6 rules.html §10 Mandatory Actions — EARS REQ-ID Markup (v3 で Agent A draft 確定)

§10 reader guide:

<section id="s10-mandatory" class="normative">
<h2>§10. Mandatory Actions for Layer 1 Consumer</h2>

<p>本 §10 は Layer 1 consumer project が folio rules を consume する際に
<strong>無条件に遵守すべき MUST 要件を一箇所に集約</strong>する。
§2〜§6 の markup / naming rules が「構造上の規則」であるのに対し、
§10 は「動的な操作上の義務」を規定する。
各 MUST の enforcement mechanism (hook flow / script 実装) は
<a href="folio-self-spec.html#s7">folio-self-spec.html §7</a> を参照。</p>

§10.1 Spec Edit Caller Marker:

<section id="s10-1" class="normative">
<h3>§10.1 Spec Edit Caller Marker</h3>

<aside class="informative">
  <p>本 §10.1 は IETF RFC 2119 / RFC 8174 / BCP 14 に定義される MUST に従う規範要件。
  enforcement の hook flow chart は
  <a href="folio-self-spec.html#s7-3-caller-marker">folio-self-spec.html §7.3</a> 参照。</p>
</aside>

<p class="ears" data-ears-pattern="event-driven">
  <span class="ears-id">REQ-CM-001</span>:
  <span class="ears-when">WHEN AI agent attempts to write to any file under <code>spec_path</code></span>,
  the system <span class="ears-shall">SHALL</span> verify that the caller marker
  environment variable is set to the declared value.
</p>

<p class="ears" data-ears-pattern="ubiquitous">
  <span class="ears-id">REQ-CM-002</span>:
  The AI agent <span class="ears-shall">SHALL</span> set the caller marker env var
  (declared in <code>folio.config.yaml</code>) before invoking any spec Edit/Write tool call,
  and <span class="ears-shall">SHALL</span> unset it immediately upon completion.
</p>

<p class="ears" data-ears-pattern="unwanted">
  <span class="ears-id">REQ-CM-003</span>:
  IF the caller marker env var is absent or holds an unexpected value,
  THEN the PreToolUse hook <span class="ears-shall">SHALL</span> return
  <code>permissionDecision: deny</code>.
</p>

<p>env var の具体名・値は <code>folio.config.yaml</code> で declare し、
binding 詳細は <a href="folio-self-spec.html#s9-bindings">folio-self-spec.html §9</a> に集約。</p>
</section>

§10.2 CI Gate Compliance:

<section id="s10-2" class="normative">
<h3>§10.2 CI Gate Compliance</h3>

<aside class="informative">
  <p>本 §10.2 は規範要件 (RFC 2119 MUST)。
  各 gate の script 実装は
  <a href="folio-self-spec.html#s7-5-ci-gate">folio-self-spec.html §7.5</a> 参照。</p>
</aside>

<p class="ears" data-ears-pattern="ubiquitous">
  <span class="ears-id">REQ-CI-001</span>:
  The Layer 1 consumer CI workflow <span class="ears-shall">SHALL</span>
  enforce all six gates defined below before permitting merge.
</p>

<table>
  <thead><tr><th>REQ-ID</th><th>gate</th><th>結果</th><th>根拠</th></tr></thead>
  <tbody>
    <tr><td>REQ-CI-010</td><td>link-integrity gate</td><td>fail = merge block</td><td>P-6</td></tr>
    <tr><td>REQ-CI-011</td><td>declarative-form gate</td><td>fail = merge block</td><td>P-4</td></tr>
    <tr><td>REQ-CI-012</td><td>what-only gate</td><td>fail = merge block</td><td>P-3 / P-11</td></tr>
    <tr><td>REQ-CI-013</td><td>vocabulary gate</td><td>fail = merge block</td><td>P-5</td></tr>
    <tr><td>REQ-CI-014</td><td>EARS coverage gate</td><td>warn (merge 許可)</td><td>§6</td></tr>
    <tr><td>REQ-CI-015</td><td>delta marker consistency gate</td><td>fail = merge block</td><td>§5</td></tr>
  </tbody>
</table>
</section>

§2.7 Branch Strategy — feature branch + draft PR squash merge (v3 で新設)

main 直接 commit は broken link time window (commit 2 split → commit 4 cross-ref 修正 までの中間状態) が high severity risk のため、 feature branch 戦略を採用する MUST。

  1. git checkout -b split/adr-0001-v3 で feature branch 作成。
  2. commit 1〜4 を branch 上で順次実行。
  3. git push -u origin split/adr-0001-v3 で branch push。
  4. gh pr create --draft で draft PR 作成、 user が diff 全体を review。
  5. review OK 後、 user が gh pr ready + gh pr merge --merge (normal merge、 4 commit history 保持) で main に取り込み。 squash merge は採用しない (4 commit の独立性を git history に残す)。

§2.8 Mermaid 移植 詳細 (v3 で新設)

architecture-rules.html の 8 mermaid 図の帰属:

元 図番号data-diagram-type帰属修正
図 1layer-detailfolio-self-spec.html §1ノード AR["architecture-rules.html"] → R["rules.html"] + 別ノードで folio-self-spec.html 表現
図 2folio-layoutfolio-self-spec.html §2ノード RULES 内 plain text "architecture-rules.html" → "rules.html + folio-self-spec.html"
図 3phase-flowfolio-self-spec.html §7.1変更なし
図 4specialist-spawnfolio-self-spec.html §7.2変更なし
図 5caller-marker-flowfolio-self-spec.html §7.3変更なし
図 6defense-pipelinefolio-self-spec.html §7.4変更なし
図 7ci-gate-pipelinefolio-self-spec.html §7.5変更なし
図 8plugin-integrationfolio-self-spec.html §8変更なし

constitution 内 mermaid 図の処理:

constitution 元 図番号処理
図 1 philosophy-divergenceconstitution に保持 (constitution §1 残存)
図 2 principles-tierconstitution に保持 (constitution §2 残存)
図 3 layer-architecture削除 (architecture-rules.html 図 1 に統合済のため重複)
図 4 plugin-structure削除 (architecture-rules.html 図 8 に統合済のため重複)

figure caption 番号: folio-self-spec.html 内で図 1 から再採番。 constitution 図 3 + 図 4 は削除済のため移植は不要 (folio-self-spec.html 図 1 (元 architecture-rules 図 1) + 図 8 (元 architecture-rules 図 8) が機能を担う)。

§3. Consequences

§3.1 Positive

§3.2 Negative

§3.3 Neutral

§4. Alternatives Considered

案採用しなかった理由
A. self-application を Phase X2 で直接実施bootstrap paradox。 Phase X3 以降で再検討。
B. keep + 内部境界明示のみ名前と内容の乖離未解消。
C. Phase X2 完了直前に splitplugin 実装中の参照修正大規模化。
D. Phase X1.5 として独立 phase 化「0.5 等の小数点表記不採用」 と非整合。
E. constitution §3 §4 完全削除独立読可能性低下。
F. constitution renumber外部 cross-ref 不変性優先。
G. §9 Bindings を rules.html に配置SSoT 違反 (binding location が .claude-plugin/ 配下)。
H. §7 全体を folio-self-spec へ (MUST cross-ref のみ)reader experience 劣化。
I. §7 全体を rules.html へfolio-self-spec が欠陥、 純粋性違反。
J. MUST を §10 ではなく §4-§6 に inline 分散discoverability 低。
K. P-2/3/11/12 plain text 保留 (ADR-0002 で別途)一時的不整合発生。
L. P-2/3/11/12 plain text 抽象化のみreader が具体 file 名判別不能。
M. main 直接 commit (ADR v2 想定)broken link time window high severity。 feature branch 採用。
N. squash merge4 commit の独立性が git history から失われる。 normal merge 採用。

§5. Trace