From 8a201337f7ad1e02e5bbefee3d1b703ea6f5550d Mon Sep 17 00:00:00 2001
From: kyeongmin <b24009@hanmaceng.co.kr>
Date: Wed, 6 May 2026 17:01:47 +0900
Subject: [PATCH] Add Phase Z B4 gatekeeper feature flag

- gate V4/B4 mismatch zones via PHASE_Z_B4_GATEKEEPER env (default OFF)
- record mismatch as adapter_needed_units with reason and mismatch_detail
- preserve render path byte-identical when flag unset
---
 src/phase_z2_pipeline.py | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/src/phase_z2_pipeline.py b/src/phase_z2_pipeline.py
index 5f9f57f..d6cb393 100644
--- a/src/phase_z2_pipeline.py
+++ b/src/phase_z2_pipeline.py
@@ -26,6 +26,7 @@ MVP-1.5b spec :
 """
 
 import json
+import os
 import re
 import shutil
 import sys
@@ -1089,6 +1090,30 @@ def run_phase_z2_mvp1(mdx_path: Path, run_id: Optional[str] = None) -> Path:
         }
         # ─── end trace-only runtime 연결 v0 ───
 
+        # ─── B4 gatekeeper (Q-V4B4 / PHASE_Z_B4_GATEKEEPER, default OFF) ───
+        if (
+            os.environ.get("PHASE_Z_B4_GATEKEEPER", "").strip().lower()
+            in {"1", "true", "yes"}
+            and not matches_mapper
+        ):
+            adapter_record = {
+                "position": position,
+                "source_section_ids": unit.source_section_ids,
+                "merge_type": unit.merge_type,
+                "template_id": unit.frame_template_id,
+                "reason": "v4_b4_mismatch",
+                "mismatch_detail": {
+                    "v4_template_id": mapper_frame_template_id,
+                    "b4_selected_template_id": placement_plan.selected_template_id,
+                    "match_note": match_note,
+                },
+            }
+            adapter_needed_units.append(adapter_record)
+            print(f"  adapter : zone--{position} {unit.source_section_ids} → "
+                  f"{unit.frame_template_id} v4_b4_mismatch → adapter_needed (skip render)")
+            continue
+        # ─── end B4 gatekeeper ───
+
         # mapper 시도 — 실패 (FitError) 시 zone 을 adapter_needed 로 표시하고 skip
         try:
             slot_payload = map_mdx_to_slots(synth_section, unit.frame_template_id)
@@ -1098,6 +1123,7 @@ def run_phase_z2_mvp1(mdx_path: Path, run_id: Optional[str] = None) -> Path:
                 "source_section_ids": unit.source_section_ids,
                 "merge_type": unit.merge_type,
                 "template_id": unit.frame_template_id,
+                "reason": "fit_error",
                 "fit_error": str(e),
             }
             adapter_needed_units.append(adapter_record)