本 amendment の核心は 「constitution から可変な instance (具体ファイル名) と bootstrap prefix を剥がし、 不変の framework 語彙 (3 domain 構造 + WHAT/WHY/HOW/verification model) だけを残す」。 これにより constitution が layout 不変になり、 X4 migration (scratch→architecture) が constitution を触らずに完了できる。
constitution / rules / folio-self-spec という folio 自身の可変ファイル名を本文に焼き込んでいる。 P-7 は spec/ decisions/ changes/ research/ という dir 名を焼き込む。architecture-rules.html → rules.html+folio-self-spec.html の file split だけが理由で PATCH bump を強いられたことを自認している。 これは結合 (coupling) の定義そのもの。| 変更 | §5 分類 |
|---|---|
| P-13 新設 (原則追加) | MAJOR |
| P-7 semantic 変更 (4→3 domain) | MAJOR 級 |
| P-2/P-3/P-11 脱-instance (文言改訂、 semantic 影響あり) | MINOR |
| §6 Amendment Procedure 書き換え | MINOR |
dominant = MAJOR (P-13 追加)。 1.0.0 未満は boundary 緩和 (§5) のため、 提案 version = 0.5.0-draft (0.x における MAJOR 級 bump)。 post-1.0 なら真の MAJOR。
plugin.json + constitution.html のみ 0.5.0-draft へ bump (framework 核 + bundle)。 rules/self-spec/relations/README の編集は PATCH 級整合 fix のため version 据え置き、 X4-0 rework 時に 0.5.0 へ align。規範文面のドラフト。 ✏ = 文言変更、 ✚ = 新設。 portability test など「不変の核」は verbatim 保持し、 instance 列挙のみ category 語へ置換する。
before: format は HTML + common.css のみ — spec / ADR / spec writing documents (constitution / rules / folio-self-spec) / changes proposal を含む全文書は HTML で記述する。 Markdown 例外は (a) FOLIO.md root marker、 (b) README.md、 (c) CLAUDE.md、 (d) folio.config.yaml 等の YAML config に限る。
after: 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) に委譲する。
変更点: (constitution / rules / folio-self-spec) + changes proposal 削除。 具体 file 列挙 → category + 委譲。 外部規約 file は example として残す (folio instance でなく安定した外部慣習)。
before: spec / constitution / rules / folio-self-spec に platform 固有 HOW を記述しない。 判定基準: 同等の framework を別 AI platform に移植する際に書き直しが必要であれば HOW 漏れである。
after: design-intent 文書に platform 固有 HOW を記述しない。 判定基準: 同等の framework を別 AI platform に移植する際に書き直しが必要であれば HOW 漏れである。
変更点: enumeration → 「design-intent 文書」。 portability test (判定基準) は verbatim 保持。
before: spec 本文は現在形の declarative narrative で記述する。 過去 narration、 未来 narration、 wave-specific note は spec から禁止する。 これらは changes/ proposal、 decisions/ ADR、 research/ に分離する。
after: spec 本文は現在形の declarative narrative で記述する。 過去 narration、 未来 narration、 wave-specific note は spec から禁止する。 これらは decision record (ADR)、 exploration note、 version control の review に分離する。
変更点: 「changes/ proposal」 削除 (changes/ 廃止)。 grep [A] で発見した proposal 当初の見落とし。
before: 4 領域は内容を排他的に保持する: spec/ = what (構造・不変条件) / decisions/ = why (frozen ADR) / changes/ = proposal (進行中の更新提案) / research/ = exploration (spec 反映前の探索)。
after: design-intent 空間は 3 領域が内容を排他的に保持する: design intent (WHAT) = 構造・不変条件 / decision (WHY) = frozen rationale / exploration = spec 反映前の探索。 これらは declarative な design-intent 文書であり、 executable な HOW (実装 + verification) は本空間の外に置く (P-13)。 更新提案は専用領域を持たず、 ADR (why) + delta marker (trace) + version control の review で表現する (changes/ 廃止、 §6)。
変更点 + 根拠: changes/ 削除。 folio の P-1 (spec = 未来理想 anchor) は OpenSpec の「現在挙動 SSoT + 未適用 delta staging」モデルと異なり、 spec を直接編集すればよく専用 staging dir が不要。 review surface = git PR、 why = ADR、 trace = delta marker が既に担う。 経験的にも X1〜X3 全 spec 編集で changes/ は未使用。 dir 名 (spec/decisions/research) は本文から外し self-spec §2 / rules §2 に委譲 (Q3: 構造固定・location override 可)。
before: spec / constitution / rules / folio-self-spec に HOW を書かない — P-3 を絶対禁止 tier に escalate。 platform 固有 primitives (tool 名、 binary path、 OS-specific command、 env var の具体値) を本文に直接記述しない。 これらは .claude-plugin/ harness または CLAUDE.md (P-2 例外) に隔離する。
after: design-intent 文書に HOW を書かない — P-3 を絶対禁止 tier に escalate。 platform 固有 primitives (tool 名、 binary path、 OS-specific command、 env var の具体値) を本文に直接記述しない。 これらは implementation harness または AI-agent instruction file (P-2 例外) に隔離する。 HOW の正しさ確立と WHAT への束縛は P-13 に従う。
変更点: enumeration → 「design-intent 文書」。 .claude-plugin/ → 「implementation harness」、 CLAUDE.md → 「AI-agent instruction file」(category 化)。 P-13 へ cross-ref 追加。
new: 実装 (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 でなければならない。
根拠: ① TDD 慣習 (tests/ ≠ docs/ ≠ src/) と P-3/P-11 (HOW を design-intent 空間外へ) の整合。 ② REQ-ID を universal join key とし test を materialize された橋にすることで「linkage 簡単 / 修正容易 / SSoT (手保守の registry 不要) / AI 可読 (grep REQ-ID)」を満たす。 ③ verification の中身は project 固有 (一般化しない) だが、 spec 適合性層と linkage 規約は普遍 → 原則として全 folio/consumer に適用可。
"principles": 12 → 13、 "tiers": {"Always": 7 → 8, ...}、 "version": "0.4.2-draft" → "0.5.0-draft"。 図 2 (principles-tier mermaid) の Always tier ラベルに P-13 追記。before (5 step、 changes/ + archive/ 使用): ① changes/ に proposal 起案 → ② user 承認 → ③ ADR Accepted → ④ constitution 編集 + SemVer + delta marker → ⑤ changes package を archive/ へ移動。
after (専用 dir なし):
changes/ dir は持たない)。archive/ への移動は行わない — git 履歴が archive を兼ねる)。本 proposal 自身がこの新手続きの dogfood: scratch/ 直下 planning doc として起案 (step 1)、 これから user 承認 (step 2)。
Q3 の回答 (構造のみ固定・root location override 可) の実装方法:
spec_path が担う。 consumer は .folio/spec/ 等に override 可能 (self-spec §8.2 の既存機構を維持)。architecture/spec/ か scratch/specs/ か .folio/spec/ か」は binding。 → layout 不変、 migration は binding の付け替えのみ。| file | 編集内容 | 区分 |
|---|---|---|
| relations.html §4.4.1 | scan 対象から changes/ 言及を除去 (現状 X3+ で changes/ を挙げている) | must-now (changes/ 廃止の即時整合) |
| rules.html §2 | consumer layout から changes/ + archive/ 除去、 verification を sibling に、 3-domain 反映 (Diátaxis howto/tutorial/explanation + steering/ の扱いは別途検討) | X4-0 layout 作業と重複 |
| folio-self-spec.html §2 | folio Layer 0 layout を canonical 構造 (architecture/{spec,decisions,research} + verification sibling + .claude-plugin harness) に rework。 §7.1 7-phase の changes/ 言及も整理 | X4-0 layout 作業 |
| verification.html | verification 実体が architecture/ の sibling である旨を明記 (契約=spec / 実体=sibling の分離)。 P-13 への cross-ref | follow-on |
| specs/README.html / decisions/README.html | domain 説明・番号体系メモの整合 | follow-on |
| CLAUDE.md (project) | changes/ 言及があれば整合 (要確認) | verify-after |
| inventory / golden | constitution は scratch/ 直下で inventory 非対象 → golden 不変。 ただし ripple で specs の meta summary が変われば再生成 (header 不変なら不要) | verify-after |
scope 分離: 本 amendment の core = constitution (P-2/3/7/11/13 + §6 + metadata) + relations §4.4.1 (changes/ 即時整合)。 self-spec §2 / rules §2 の layout rework は本質的に X4-0 layout 確定であり、 constitution が layout 不変になった後に X4-0 で実施 (本 amendment が X4-0 を unblock する関係)。
分担原則: declarative (spec / ADR / constitution / RED scenario / design 決定 / review / merge) = PARENT (本 session)。 executable な実装 (bin/folio / scripts / hooks のコード) = SPAWN (session:spawn + feature-dev:feature-dev)。 この fault line は P-13 の WHAT/HOW 分離の workflow 形 — parent が WHAT + RED test を確定し、 spawn が HOW を GREEN にする。 Phase 1 (amendment) は実装ゼロのため parent のみ、 spawn は X4-C (migration) から発火する。
| Phase | 内容 | 担当 | 実装 |
|---|---|---|---|
| P1 — amendment | ADR-0021 + constitution 編集 + changes/ 全 purge + count fix + plugin.json version | PARENT | なし (全 spec/doc) |
| X4-0 — layout | self-spec §2/§7.1 + rules §2 を canonical 構造 rework + X4-0 ADR + version align | PARENT | なし (spec + 設計) |
| X4-C — migration | scratch→architecture 物理移動 + bin/folio scan dir + scripts spec_path + golden 再生成 | SPAWN | あり (parent: spec+RED+review+merge) |
| (任意) folio trace | P-13 traceability index tool (test req_id scan → REQ→spec→test→impl + gap 検出) | SPAWN | あり (parent: REQ-VER+ADR+RED) |
| X4-A/B/D/E | init / fix / architect / e2e (x4-plan §2) | SPAWN | あり (同 pattern) |
実行結果: ADR-0021 起票 + constitution v0.5.0-draft (13 原則、 P-13 新設、 changes/ 廃止、 脱-instance P-2/3/4/11) + cascade (decisions/README 3-domain 化・手続き整合 / rules §2-3 changes purge / relations §4.4.1 + count / specs/README + self-spec count / plugin.json version)。 検証: validate 18 files/75 relations clean、 sandbox 8/8 GREEN、 golden 3件 (inventory/prime-digest/validate-clean) 再生成。 実装コード変更なし (grep 実測通り)。 次 = X4-0 (§6.2)。
X4-0 (layout 確定) を PARENT で着手 — constitution が layout 不変になったため self-spec §2 / rules §2 の canonical rework が安全に行える (x4-plan §3 論点表の解決)。 その後 X4-C (migration) から実装を SPAWN + feature-dev に委譲する。 X4 全体の分解は x4-plan.html を参照。