diff --git a/docs/development/current/main/design/planfrag-freeze-taxonomy.md b/docs/development/current/main/design/planfrag-freeze-taxonomy.md new file mode 100644 index 00000000..4ff6162c --- /dev/null +++ b/docs/development/current/main/design/planfrag-freeze-taxonomy.md @@ -0,0 +1,44 @@ +# Plan/Frag Freeze Taxonomy (SSOT) + +Status: Draft (Phase 29ai P2) +Scope: Facts → Plan（仕様不変） + +目的: `Result, Freeze>` の “None と Freeze の境界” を規約として固定し、実装者の解釈差で挙動が揺れるのを防ぐ。 + +## Return Contract (SSOT) + +### `Ok(None)` = NotApplicable + +「plan 化の対象ではない」ため、既存経路に委譲して良い。 + +- 例: + - region が単純直列で、Plan/Frag を挟む必然がない + - 必須の入口条件が揃っていない（loop/header/exit が確定できない等）※ただし “対象っぽい” 場合は Freeze + +### `Ok(Some(plan))` = Unique plan + +候補が一意に確定し、emit に必要な情報が揃っている。 + +### `Err(Freeze)` = Fail-Fast（silent fallback 禁止） + +“対象っぽい” のに plan が一意化できない、または契約違反/禁止形が観測された。 + +## Tags (recommended) + +- `plan/freeze:contract` + - 形が契約を破っている（例: 必須 step が欠落、join 入力の整合が崩れている） +- `plan/freeze:ambiguous` + - 複数候補が成立し、一意化できない（将来のルール追加で解消される可能性がある） +- `plan/freeze:unsupported` + - 一意に判定できるが、未実装で扱えない（“未対応” を誤って None にしない） +- `plan/freeze:bug` + - 不変条件が壊れている/到達してはいけない状態（実装バグ・内部矛盾） + +## Message format (SSOT) + +コード側の `Display` は安定化する（例）: + +- `"[plan/freeze:{tag}] {message}"` + +必要なら hint を別枠で付ける（ログで検知しやすくする）。 + diff --git a/docs/development/current/main/design/planfrag-ssot-registry.md b/docs/development/current/main/design/planfrag-ssot-registry.md new file mode 100644 index 00000000..e858625d --- /dev/null +++ b/docs/development/current/main/design/planfrag-ssot-registry.md @@ -0,0 +1,23 @@ +# Plan/Frag SSOT Registry (SSOT) + +Status: Draft (Phase 29ai P2) +Scope: JoinIR plan/frag 導線（仕様不変） + +目的: “真実の所在（SSOT）” を表で固定し、層が勝手に再解析/再推論して SSOT が崩れるのを防ぐ。 + +## SSOT Table + +| Layer | SSOT (Truth) | Forbidden (Must Not) | Verification (Fail-Fast) | +|---|---|---|---| +| Facts | CFG/Terminator/境界情報から抽出した “観測” と “導出” を分離した Facts | planner が CFG を再走査する前提の不足した Facts を作る / emit が CFG を覗いて “穴埋め” | Facts 収集時: 契約違反は `Freeze(contract)`（strict/dev は即Fail） | +| Normalize | Facts の表現ゆれ除去（純変換） | 追加の解析（CFG/AST を見に行く） / 値の意味を変える変形 | normalize 後の不変条件を `verify_*` で検証（strict/dev） | +| Planner | Canonical Facts → Plan（候補集合→一意化） | pattern 名で入口分岐を公開APIに漏らす / emit の都合で再解析 | 0候補=Ok(None), 1候補=Ok(Some), 2+=Freeze(ambiguous) | +| Plan | emit に必要な骨格（entry/exit/join/region参照） | CFG 再解析が必要な “情報欠落” Plan | emit 前に Plan の構造不変条件を検証（strict/dev） | +| Emit | Plan → Frag（生成のみ） | Facts/CFG に戻って再推論 / silent fallback | emit は入力不足を Freeze(bug/contract) で落とす（strict/dev） | +| Frag | 生成結果（EdgeCFG/JoinIR lowering の出力） | Frag が “真実” として再利用されること（派生物） | 既存の frag verifier / contract_checks を入口で実行 | + +## Notes + +- “Forbidden” は将来の if 地獄 / hidden fallback を防ぐための境界ガード。 +- Verification は既存の `contract_checks` と整合する形で増やす（既定挙動は変えない）。 + diff --git a/docs/development/current/main/phases/phase-29ai/P2-SSOT-REGISTRY-FREEZE-TAXONOMY-INSTRUCTIONS.md b/docs/development/current/main/phases/phase-29ai/P2-SSOT-REGISTRY-FREEZE-TAXONOMY-INSTRUCTIONS.md new file mode 100644 index 00000000..fa84ad6c --- /dev/null +++ b/docs/development/current/main/phases/phase-29ai/P2-SSOT-REGISTRY-FREEZE-TAXONOMY-INSTRUCTIONS.md @@ -0,0 +1,49 @@ +# Phase 29ai P2: SSOT Registry + Freeze Taxonomy (docs-only) — Instructions + +Status: Ready for execution +Scope: docs-first（仕様不変） + +## Goal + +Phase 29ai の “single-planner” を長期で壊れない形にするために、SSOT（真実の所在）と Freeze（Fail-Fast）の分類規約を +1枚に固定する。 + +## Non-goals + +- コード変更（docs-only） +- 既存エラー文言の変更 +- 新しいトグル/環境変数の追加 + +## Deliverables + +1) SSOT Registry（真実の所在の表）を追加 + - 新規: `docs/development/current/main/design/planfrag-ssot-registry.md` + - 最低限含める項目（列）: + - Layer（Facts / Normalize / Planner / Plan / Emit / Frag） + - SSOT（真実）: どのデータが唯一の根拠か + - Forbidden（禁止）: その層が“覗いてはいけない”もの（再解析/再推論など） + - Verification（検証）: 破れたらどこで Fail-Fast するか（strict/dev の扱いも） + +2) Freeze taxonomy（分類）を SSOT 化 + - 新規: `docs/development/current/main/design/planfrag-freeze-taxonomy.md` + - 最低限のタグ（推奨）: + - `plan/freeze:contract`（契約違反・形が崩れている） + - `plan/freeze:ambiguous`（複数解釈で一意化できない） + - `plan/freeze:unsupported`（対象だが未対応、将来対応予定） + - `plan/freeze:bug`（不変条件が壊れている/到達してはいけない状態） + - `Ok(None)` と `Err(Freeze)` の境界を例つきで固定する + +3) Phase 29ai README を更新（P2 のリンク追加） + +## References (SSOT) + +- Plan/Frag の設計入口: `docs/development/current/main/design/edgecfg-fragments.md` +- Pattern6/7 契約: `docs/development/current/main/design/pattern6-7-contracts.md` +- Phase 29ai 入口: `docs/development/current/main/phases/phase-29ai/README.md` +- Phase 29ai P1（Freeze/候補集合のコード側規約）: `docs/development/current/main/phases/phase-29ai/P1-PLANNER-CANDIDATES-FREEZE-SSOT-INSTRUCTIONS.md` + +## Acceptance Criteria + +- docs-only 変更であること（ビルド不要だが、`./tools/smokes/v2/run.sh --profile quick` が緑を維持） +- 新規2文書が “入口SSOTとして参照される前提” で読める（表 + 例 + 禁止事項が明確） + diff --git a/docs/development/current/main/phases/phase-29ai/README.md b/docs/development/current/main/phases/phase-29ai/README.md index 5a9f44a4..ae35ffc7 100644 --- a/docs/development/current/main/phases/phase-29ai/README.md +++ b/docs/development/current/main/phases/phase-29ai/README.md @@ -12,6 +12,11 @@ Goal: pattern 名による分岐を外部APIから消し、Facts（事実）→ - 指示書: `docs/development/current/main/phases/phase-29ai/P1-PLANNER-CANDIDATES-FREEZE-SSOT-INSTRUCTIONS.md` - ねらい: `Ok(None)` / `Err(Freeze)` の境界と “候補集合→一意化” をSSOT化（未接続のまま、仕様不変） +## P2: SSOT Registry + Freeze Taxonomy（docs-only） + +- 指示書: `docs/development/current/main/phases/phase-29ai/P2-SSOT-REGISTRY-FREEZE-TAXONOMY-INSTRUCTIONS.md` +- ねらい: “真実の所在” と Freeze 分類を1枚に固定して、後続実装の迷子を防ぐ（仕様不変） + ## Verification (SSOT) - `cargo build --release`