folio constitution

v0.6.0-draft · status: draft · 14 immutable principles, 3-tier boundary declarations

§0. Reader's Guide — Stakeholder Perspectives (ISO/IEC/IEEE 42010:2022)

folio は 3 種類の reader を第一級 stakeholder として明示する。 各 spec file の <meta name="folio-stakeholders"> 属性で対象 persona を宣言する。

§1. Purpose

folio は architecture specification を書くための framework である。 大規模 project でユーザーもしくは AI が当初の設計要件を見失い、 場当たり的修正が積み重なって設計破綻に至るのを防ぐ。 spec は「常に参照され続ける自然言語の design intent reference」 として機能する。

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 する。

folio の核心は 未来理想 anchor (future-ideal anchor):

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#2a4d6e', 'primaryTextColor': '#ffffff', 'lineColor': '#2a4d6e', 'secondaryColor': '#5ac8b8', 'tertiaryColor': '#f5f8fa'}}}%%
graph LR
  accTitle: architecture spec の SSoT 解釈 3 派の比較
  accDescr: folio は未来理想 anchor、 OpenSpec は現在挙動 SSoT、 BDD はテスト挙動 SSoT を採用する。 drift の扱いも異なる
  S["architecture spec"]
  F["folio
未来理想 anchor
drift = 想定内
(P-1)"]
  O["OpenSpec
現在挙動 SSoT
drift = bug"]
  B["BDD
テスト挙動 SSoT
drift = test fail"]
  S --> F
  S --> O
  S --> B
  style F fill:#5ac8b8,color:#08131a
  style O fill:#f5f8fa,color:#08131a
  style B fill:#f5f8fa,color:#08131a
図 1. architecture spec の SSoT 解釈 3 派。 folio は未来理想 anchor (P-1)、 OpenSpec / BDD と分岐する。

§2. Fourteen Immutable Principles

folio は 14 の不変原則を 3 tier に分類する。

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#2a4d6e'}}}%%
graph TD
  accTitle: 14 原則 3-tier 構造
  accDescr: Always tier 9 原則 (P-1 から P-7 + P-13/P-14)、 Ask-first tier 3 原則 (P-8 から P-10)、 Never tier 2 原則 (P-11 から P-12)
  A["Always tier
P-1〜P-7 + P-13/P-14 (9 原則)
不変、 例外なし"]
  B["Ask-first tier
P-8〜P-10 (3 原則)
user 承認後変更可"]
  C["Never tier
P-11〜P-12 (2 原則)
絶対禁止"]
  A --> B
  B --> C
  style A fill:#e6f6f2,color:#08131a
  style B fill:#fefbea,color:#08131a
  style C fill:#fdf3f3,color:#08131a
図 2. 14 原則の 3-tier 構造。

§2.1 Always Tier (P-1〜P-7 + P-13/P-14)

P-1: spec は未来理想の anchor である
spec 配下の全文書は到達すべき設計の最終形を declarative に記述する。 drift の検証は AI dialog accountability (P-8) で行う。
P-2: format は HTML + common.css のみ
全 design-intent 文書 (design intent / decision record / exploration note) は HTML で記述する。 Markdown / YAML 例外は外部 platform 規約に従う file (例: VCS host の README、 AI-agent instruction file、 YAML config) に限り、 確定列挙は folio-self-spec §2 (Layer 0) / rules §3 (Layer 1) に委譲する。
P-3: WHAT-only
design-intent 文書に platform 固有 HOW を記述しない。 判定基準: 同等の framework を別 AI platform に移植する際に書き直しが必要であれば HOW 漏れである。
P-4: Declarative form
spec 本文は現在形の declarative narrative で記述する。 過去 narration、 未来 narration、 wave-specific note は spec から禁止する。 これらは decision record (ADR)、 exploration note、 version control の review に分離する。
P-5: 1 entity = 1 canonical name
同一概念に複数の名称を使用しない。 canonical name と forbidden synonyms は consumer project の vocabulary file で宣言する。
P-6: Link integrity
spec 配下の全 file は inbound link を 1 以上持つ。 各 cluster の README.html (entry point) のみ例外。 broken link、 orphan、 trace_extra は CI gate で 0 を強制する。
P-7: Content domain exclusivity
design-intent 空間は 3 領域が内容を排他的に保持する: design intent (WHAT) = 構造・不変条件 / decision (WHY) = frozen rationale / exploration = spec 反映前の探索。 これらは declarative な design-intent 文書であり、 executable な HOW (実装 + verification) は本空間の外に置く (P-13)。 更新提案は専用領域を持たず、 decision record (ADR) + delta marker (trace) + version control の review で表現する。 具体 dir 名は folio-self-spec §2 / rules §2 に委譲する。
P-13: Verification & Traceability
実装 (HOW) とその executable verification は design-intent 空間の外に置く (P-3 / P-11 と整合)。 WHAT (design-intent 文書中の要件) は安定した requirement ID を介して verification に束縛され、 この ID 束縛が WHAT↔HOW の単一の真実源 (SSoT) link となる。 verification は (a) spec 適合性 (design-intent 文書自身の well-formed 検証、 framework 提供・普遍) と (b) 実装適合性 (HOW が WHAT を満たすかの検証、 project 固有) の 2 層を含む。 requirement ID から spec / verification / 実装への trace は machine-navigable でなければならない。
P-14: Human Readability
folio の design-intent 文書とその生成物は、 機械可読性と同格に人間可読性を保つ。 各ページ種別には主たる人間読者層が定義されていなければならず (具体の定義と割当は rules が規定する)、 ページはその読者が当該ページの仕事を果たせる形で提示される。 人間可読性は検証対象であり、 決定的 floor gate と review ceiling の二層で継続的に検証する。 機械可読性のための構造が人間への提示を損なうこと、 およびその逆を認めない。

§2.2 Ask-First Tier (P-8〜P-10)

P-8: AI dialog accountability
AI Agent は spec を読んで実装案を提示する際、 constitution / spec との矛盾・divergence を natural language reasoning で user に提示する責務を負う。 AI の自然言語推論が drift 検出 mechanism として機能する。
P-9: Layer 1 consumer 固有 config 変更前 user 確認
consumer project の folio.config.yaml や vocabulary file 変更時は user 承認を取得する。
P-10: Constitution 自身への変更前 user 確認
本 constitution への変更 (原則追加・削除・文言変更・tier 変更) は user 承認 MUST。 SemVer 判定は §5 に従う。

§2.3 Never Tier (P-11〜P-12)

P-11: design-intent 文書に HOW を書かない
P-3 を絶対禁止 tier に escalate した規律。 platform 固有 primitives (specific tool 名、 binary path、 OS-specific command、 env var の具体値) を本文に直接記述しない。 これらは implementation harness または AI-agent instruction file (P-2 例外) に隔離する。 HOW の正しさ確立と WHAT への束縛は P-13 に従う。
P-12: Layer 0 = rules + plugin harness 一体配布
folio Layer 0 は rules (constitution + rules + folio-self-spec) と plugin harness (.claude-plugin/) を一体として配布する。 Layer 1 consumer project は別 git repo として展開され、 folio repo 内に同居しない。

§3. Layer Architecture

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 を参照。

§4. Folio as a Plugin

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

§5. Versioning Policy

本 constitution は Semantic Versioning 2.0.0 に準拠する。

bump条件
MAJOR原則の追加 / 削除 / tier 変更
MINOR原則の文言改訂 (semantic 影響あり)
PATCH誤記修正、 typo、 cross-ref 補正

1.0.0 未満は development phase として MAJOR/MINOR/PATCH の boundary を緩める。 1.0.0 以降は strict SemVer。

変更時は ADR を起票し、 本 constitution 内に delta marker を inline 保存する (rules.html §5)。

§6. Amendment Procedure

  1. 変更提案を proposal として起案 (review 用、 version control branch 上。 専用 changes/ dir は持たない)。
  2. user 承認を取得 (P-10)。
  3. ADR を Accepted status で作成。
  4. constitution を編集し、 SemVer bump + delta marker を inline 追加。
  5. version control の review (PR / diff) で trace を確定する (archive/ への移動は行わない — git 履歴が archive を兼ねる)。

各 step の具体的 mechanism は folio-self-spec.html §7.1 7-phase PR Cycle に規定する。

§7. Citations