Phase X4 分解 + 着手計画

planning memo · status: superseded · 2026-05-25 · X4 = 試作卒業フェーズの分解 (実装前の計画、 自由形式 scratch memo)

§1. X4 とは

X4 = folio を scratch/ 試作 → 完成形 layout へ移行し、 harness (CLI init/fix + folio-architect SKILL) を完成させる「試作卒業」 フェーズ。 folio-self-spec §2 の target layout + P-12 (Layer 0 一体配布) が完成形の基準。 architecture/ dir の作成は CLAUDE.md §3 で「Phase X4+ に user 主導」 と明記されており、 X4 の中核 (layout 確定 + migration) は user 主導の意思決定を要する。

§2. 分解 (X4-0 〜 X4-E)

id内容user 主導depends on実装方式
X4-0完成形 layout の確定 (§3 の論点を reconcile)MUST (ADR + amendment + architecture/ 作成決定)—設計 session (ADR 起票)
X4-Abin/folio init — consumer の architecture/spec/ + folio.config.yaml scaffoldADR 承認X4-0spec→spawn (ADR + REQ-VER + cli-golden)
X4-Bbin/folio fix (or doctor) — 双方向 link 等の自動修正 (validate の対)ADR 承認X4-0 (命名) + validate (済)spec→spawn
X4-Cscratch→architecture migration (folio init を folio 自身に self-referential 適用)MUST (最大の破壊的変更、 scratch 撤去)X4-0 + X4-A段階的・親主導 (検証必須)
X4-Dfolio-architect full 7-Phase SKILL + 8 specialist agents (§7.1/§7.2)ADR 承認(独立、 migration 後 layout が clean)spec→spawn (大)
X4-Ee2e use case 拡張 (現 6 = S-A〜S-F → 完成形全 use case、 目標数は verification §4.1 で要確認)—init/fix/architect が揃ってからe2e runbook 追加

critical path & 並行

X4-0 (layout 確定, user 主導) ──→ X4-A (init) ──→ X4-C (migration, user 主導)   ← critical path
                              ├─→ X4-B (fix)
                              ├─→ X4-D (architect full)      X4-0 後に並行可
                              └─→ X4-E (e2e 拡張)            (migration 後 layout での実装/検証が clean)

§3. X4-0 で確定すべき layout 論点 (user 主導)

folio-self-spec §2 の target layout を、 relations/verification framework 追加後の現状と reconcile する。 §2 は relations.html / verification.html / scratch/verification/ framework / research/ を想定していないため、 これらの配置は未決:

論点§2 の記述現状要決定
constitution / rules / folio-self-specroot 直下scratch/ (constitution は scratch 直下、 rules/self-spec は scratch/specs/)root へ移すか
decisions/ (ADR)root 直下scratch/decisions/root か
relations.html / verification.html記載なしscratch/specs/配置先 (root? architecture/? specs として残す?)
scratch/verification/ framework (scenarios/fixtures/baselines/runner.sh)記載なしscratch/verification/移植先 (architecture/verification/? .claude-plugin/?)
research/記載なしscratch/research/扱い (保持? archive?)
spec_path (caller-marker gate 対象)architecture/spec/ (consumer 用)scratch/specs/ (暫定 override)folio 自身は self-spec を root に持つ → self-host 時の spec_path 解釈 (folio の「spec」 は何か)
CLI 命名 (自動修正)doctor (§2 bin/)fix (ADR-0003 §2.1 + bin/folio help)fix vs doctor 統一

これらは constitution / folio-self-spec の amendment を伴う可能性があり (P-10 / 既存 ADR frozen)、 X4-0 で ADR 起票 (user 承認 MUST) として確定する。

§4. 着手時の state 参照 (2026-05-25 時点)

§5. X4-0 layout 確定結果 (2026-05-25)

Phase 1 (constitution amendment ADR-0021) + dig を経て、 §3 の全 layout 論点が解決した (user 承認: F1/F3/F4 + Q3 + amendment 議論)。 canonical 構造を以下に確定。 これを self-spec §2 / rules §2 に反映 + ADR-0022 起票 = X4-0 残作業 (PARENT)、 物理移動 = X4-C (SPAWN)。

確定した canonical layout

folio Layer 0 (self-host):
folio/
├── FOLIO.md / README.md / CLAUDE.md / common.css   # root (外部規約 + style)
├── architecture/
│   ├── spec/        # design intent: constitution / rules / folio-self-spec / relations / verification / README
│   ├── decisions/   # decision (ADR)
│   ├── research/    # exploration
│   └── assets/      # mermaid (support、 domain でない)
├── verification/    # HOW-test sibling (scenarios/ fixtures/ baselines/ e2e/ runner.sh)
├── hooks/ + .claude-plugin/   # HOW-impl (harness)
└── inventory.json   # generated (gitignore)

consumer Layer 1:
<consumer>/
├── README.md / CLAUDE.md / folio.config.yaml
├── architecture/{spec,decisions,research}/   # 3-domain (Diátaxis/steering は除去)
├── verification/   # HOW-test
└── <impl>/         # src/ skills/ 等

論点解決 (§3 table)

論点確定根拠
constitution/rules/self-spec 配置architecture/spec/ に flat (folio 完全 self-host)F1
decisions/ 配置architecture/decisions/3-domain
relations/verification.html 配置contract = architecture/spec/ (design intent)amendment 議論
verification framework 実体 移植先repo-root verification/ sibling (architecture/ 外、 executable HOW)P-3/P-11 + TDD
research/ 扱いarchitecture/research/ (exploration domain、 保持)3-domain
spec_path 解釈architecture/spec/ canonical、 location は override 可。 folio self-host = architecture/spec/Q3
CLI 命名 (自動修正)fix (doctor 不採用)F4
Diátaxis (howto/tutorial/explanation) + Kiro steering/canonical から除去 (triad に絞る)。 一般 docs/AI-context は consumer 自由領域、 folio 非 governF3

X4-0 残作業 (PARENT) → X4-C (SPAWN)

  1. ✅ ADR-0022 起票 + decisions/README 登録
  2. ✅ self-spec §2 rework (architecture/{spec,decisions,research} self-host + verification sibling + hooks/ root + 図2 mermaid + doctor→fix)
  3. ✅ rules §2 rework (Diátaxis/steering 除去 + 3-domain + verification sibling + folio govern 範囲注記) + constitution §7 narrowing
  4. ⏳ (X4-C, SPAWN) 物理移動 scratch→architecture + bin/folio scan dir + scripts/plugin.json spec_path + golden 再生成 + self-spec/rules version align (-draft skew 据え置き中)

X4-0 完了 (2026-05-25): spec が canonical layout を記述。 物理実体は scratch のまま (P-1、 X4-C で追従)。 検証: validate 19 files/81 relations clean、 sandbox 8/8 GREEN。