ADR-0022 (X4-0) で canonical layout (architecture/{spec,decisions,research,assets} + verification/ sibling + hooks/ + .claude-plugin/) を確定し、 spec (folio-self-spec §2 / rules §2) に反映した。 ただし 物理実体は scratch/ のままで、 spec が architecture/ を記述しつつ実体が scratch/ という divergence が残存している (P-1 未来理想 anchor として許容、 plugin.json の spec_path=scratch/specs/ binding が実体を指す)。 ADR-0022 §2.3 / §5 はこの物理移動を 後続 (SPAWN, X4-C) と明示した。
X4-C はその物理移動を実行し divergence を解消する = 試作卒業 (scratch → 完成形 layout)。 folio 全 session を通じて最大の破壊的変更 (約 25 の HTML 移動 + 全クロス参照 rewrite + CLI/script path + CLAUDE.md + golden 全再生成) であり、 user 主導 MUST。 段取りは本 session の AskUq で確定: ① scratch 完全撤去 + 作業 doc を research/ 退避 (Q1) ② 本 ADR-0023 起票 (Q2、 起票自体が user 承認) ③ 単一 atomic SPAWN で実行 (Q3)。
| from (現 scratch) | to (canonical) | 根拠 |
|---|---|---|
scratch/specs/{rules,folio-self-spec,relations,verification,README}.html | architecture/spec/ | F1 (framework-core flat) |
scratch/constitution.html | architecture/spec/constitution.html | F1 (scratch root → spec/ flat) |
scratch/decisions/* (ADR 群 + README) | architecture/decisions/ | 3-domain (WHY) |
scratch/research/* | architecture/research/ | 3-domain (exploration) |
scratch/assets/* (mermaid vendor) | architecture/assets/ | support (domain でない) |
scratch/verification/ | verification/ (repo-root) | P-3/P-11 (executable HOW、 architecture sibling) |
constitution.html が scratch root (specs/ の親) から architecture/spec/ (framework-core の sibling) へ移ることで相対 topology が変化する。 全 HTML の href + JSON-LD @id を以下規則で rewrite し、 folio validate の link-integrity を維持する:
architecture/spec/ に着地する file 内: ../spec/constitution.html → ./constitution.html (同 dir 化)architecture/decisions/ に着地する file 内: ../spec/constitution.html → ../spec/constitution.html、 ../spec/ → ../spec/architecture/research/ に着地する file 内: scratch-root 相対 (./specs/…, ./constitution.html) → ../spec/…./other.html#anchor) と ../decisions/ ../research/ は topology 不変 (rewrite 不要)。 fragment anchor は全保持。scratch/x4-plan.html + scratch/constitution-x4-amendment-proposal.html (共に doc-type=planning) → architecture/research/ へ退避 (planning trail を historical に保全)。 退避時 doc-type=planning 保持 + status=superseded 化、 JSON-LD refs を architecture topology へ rewrite。 research/ scan 対象に入るため inventory に historical entry として計上される。scratch/README.html (doc-type=scratch-readme) → 削除 (scratch cluster 消滅で無意味化)。scratch/ dir は空になり消滅 (git は空 dir を追跡しない)。bin/folio: 走査 base realpath -m scratch → architecture、 scan dirs ("specs" "decisions" "research") → ("spec" "decisions" "research")、 validate default root "scratch" → "architecture"、 message/comment の scratch/ 表記。plugin-lib.sh の FOLIO_SPEC_PATH 既定 scratch/specs/ → architecture/spec/、 check-*.sh の reference path (5 本)、 inject-inventory.sh の comment。plugin.json: spec_path.default scratch/specs/ → architecture/spec/ + description。inventory.json: 出力先を repo-root inventory.json (x4-plan §5 SSoT) に変更。 走査 base (architecture/) と出力先 (repo root) を decouple。 .gitignore の scratch/inventory.json → inventory.json、 golden path comment (scratch/verification/baselines/… → verification/baselines/…) も更新。X4-0 で意図的に据え置いた skew を解消: folio-self-spec / rules / relations / spec-README / decisions-README を 0.5.0-draft に揃える (constitution + plugin.json は既に 0.5.0-draft)。
root CLAUDE.md (Markdown 例外、 P-2) は全面 scratch 前提で書かれている。 X4-C で scratch 制約 → architecture/ 運用へ改訂: §2「architecture/ を作らない」禁止の解除、 §3/§4 作業場所を architecture/spec/ 等へ、 §6 Directory Layout tree を canonical へ、 marker / spec_path 記述の更新。
単一 atomic SPAWN (session:spawn --worktree + feature-dev:feature-dev) で §2.1〜§2.6 を一括実行。 物理移動は中間状態で validate が壊れる (分割不可) ため、 worktree 内で完遂 → GREEN 確認後に git merge --ff-only し、 main を中間 RED 状態にしない。 migration では人工的な RED-first golden を作らず、 既存 verification suite の post-migration GREEN を受け入れ契約とする:
bin/folio validate clean — link-integrity がクロス参照 rewrite (§2.2) の正しさを保証runner.sh --accept) 後、 inventory/prime-digest/validate-clean が architecture path を反映spec_path = architecture/spec/ 解決 + CLAUDE_PLUGIN_ROOT)git merge --ff-onlyarchitecture/ に確定 (旧 design-philosophy で指摘された「永続 constitution と一時 spec が同 location」問題に決着)CLAUDE.md + golden 全再生成を atomic に実施。 rewrite 漏れは validate (link-integrity) が捕捉するが手作業 review 必須CLAUDE_PLUGIN_ROOT / spec_path 解決)。 §2.7(c) で gatearchitecture/research/ に status=superseded の historical entry として inventory に計上される (exploration domain に archived planning trail)| 案 | 採用可否 |
|---|---|
| 単一 atomic SPAWN (採用) | 物理移動は分割不可。 worktree 完遂 → GREEN → ff-merge で main を中間 RED にしない (Q3) |
| 段階分割 SPAWN (C1 移動+code / C2 CLAUDE.md+align) | 不採用 — 各段階で main を green に保つ調整コスト増、 移動の atomic 性が崩れる (Q3) |
| scratch/ を空箱として残置 | 不採用 — canonical layout (x4-plan §5) に scratch なし、 永続/一時混在が再発 (Q1) |
| planning doc を削除 | 不採用 — user は research/ 退避を選択、 planning trail を historical に保全 (Q1) |
inventory を architecture/inventory.json に配置 | 不採用 — x4-plan §5 SSoT が repo-root を指定。 走査 base と出力先を decouple |
git merge --ff-only。