fix: clarify platform transition wbs failure notes

tools/validate_platform_transition_wbs_v1.py

@@ -86,6 +86,36 @@ def _check_p1() -> dict[str, Any]:
     }
 
 
+def _humanize_check_failure(key: str, result: dict[str, Any]) -> str:
+    evidence = result.get("evidence") if isinstance(result.get("evidence"), dict) else {}
+    errors = result.get("errors") if isinstance(result.get("errors"), list) else []
+    if key == "P1_kis_core_api_collector":
+        summary = evidence.get("summary_path", "")
+        db = evidence.get("db_path", "")
+        return (
+            "P1 failed: missing or empty KIS collector evidence. "
+            f"Expected {summary} and {db} to exist with collection_runs>=1 and collection_snapshots>=1. "
+            "Fix: run the KIS collection job first, or restore the collector artifacts before this validator."
+        )
+    if key == "P2_sqlite_canonical_store":
+        db = evidence.get("db_path", "")
+        return (
+            "P2 failed: SQLite round-trip evidence is missing. "
+            f"Expected {db} to contain collection_runs and collection_snapshots. "
+            "Fix: regenerate the collector DB or restore Temp/test_kis_data_collection.db before this validator."
+        )
+    if key == "P4_gas_thin_adapter_minimize":
+        validation_path = evidence.get("validation_path", "")
+        return (
+            "P4 failed: thin-adapter validation output is missing or incomplete. "
+            f"Expected {validation_path} with gate=PASS and function_inventory_coverage_pct=100.0. "
+            "Fix: run tools/validate_gas_thin_adapter_v1.py before the platform-transition gate."
+        )
+    if errors:
+        return f"{key} failed: " + ", ".join(str(item) for item in errors)
+    return f"{key} failed: evidence gate did not pass."
+
+
 def _check_p2() -> dict[str, Any]:
     from src.quant_engine.data_collection_backend_v1 import CollectionStoreSpec, normalize_store_spec
 
@@ -272,6 +302,7 @@ def main() -> int:
     }
 
     missing_criteria: list[str] = []
+    failure_notes: list[str] = []
     for key, result in checks.items():
         spec_row = phase.get(key) or {}
         criteria = spec_row.get("success_criteria") or {}
@@ -285,6 +316,7 @@ def main() -> int:
             missing_criteria.append(f"{key}.verification_commands")
         if result["gate"] != "PASS":
             missing_criteria.append(f"{key}.evidence_gate")
+            failure_notes.append(_humanize_check_failure(key, result))
 
     roadmap_mentions = [
         "Phase 5 데이터 플랫폼 전환 WBS 성공값",
@@ -299,14 +331,21 @@ def main() -> int:
     payload = {
         "formula_id": "PLATFORM_TRANSITION_WBS_V1",
         "gate": "PASS" if not missing_criteria and not roadmap_missing else "FAIL",
+        "message": (
+            "Platform transition WBS check passed."
+            if not missing_criteria and not roadmap_missing
+            else "Platform transition WBS check failed. See failure_notes for the exact missing evidence and recovery step."
+        ),
         "spec_path": str(SPEC_PATH),
         "roadmap_doc_path": str(ROADMAP_DOC_PATH),
         "missing_criteria": missing_criteria,
+        "failure_notes": failure_notes,
         "roadmap_missing": roadmap_missing,
         "checks": checks,
     }
     out = ROOT / "Temp" / "platform_transition_wbs_v1.json"
     out.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+    print(payload["message"])
     print(json.dumps(payload, ensure_ascii=False, indent=2))
     return 0 if payload["gate"] == "PASS" else 1