devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/playwright_workflow/dag.py

@@ -0,0 +1,1317 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from devflow_engine.stores.execution_store import ExecutionStore
+
+DAG_ID = "post_integration_playwright_workflow"
+DAG_VERSION = "0.1"
+UI_SOURCE_SUFFIXES = {".tsx", ".jsx", ".vue", ".svelte", ".html"}
+BUSINESS_CONTROL_CATEGORIES = {
+    "navigation",
+    "filter-state",
+    "mutation",
+    "workflow-step",
+    "role-gated",
+    "status-gated",
+    "seeded-content",
+    "external-action",
+}
+EXCLUDED_DIR_PARTS = {
+    ".devflow",
+    ".git",
+    ".next",
+    "build",
+    "coverage",
+    "dist",
+    "node_modules",
+    "playwright-report",
+    "test-results",
+}
+
+
+@dataclass(frozen=True)
+class PostIntegrationPlaywrightDagResult:
+    exit_code: int
+    message: str
+    run_id: str
+    pipeline_dir: Path
+    artifacts: dict[str, str]
+
+
+def run_post_integration_playwright_dag(
+    *,
+    repo_root: Path,
+    store: ExecutionStore,
+    project_id: str,
+    trigger_run_id: str | None = None,
+) -> PostIntegrationPlaywrightDagResult:
+    """Create post-integration Playwright planning artifacts from the implemented UI."""
+    repo_root = repo_root.resolve()
+    run = store.start_run(
+        kind="worker.post_integration_playwright",
+        repo_root=repo_root,
+        args={"project_id": project_id, "trigger_run_id": trigger_run_id, "dag_id": DAG_ID, "dag_version": DAG_VERSION},
+    )
+    pipeline_dir = repo_root / ".devflow" / "post_integration_playwright" / f"run_{run.run_id}"
+    current_dir = repo_root / ".devflow" / "post_integration_playwright" / "current"
+    pipeline_dir.mkdir(parents=True, exist_ok=True)
+    current_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        guidance = _find_playwright_guidance(repo_root)
+        inventory = _merge_persisted_inventory(
+            current_inventory=_catalogue_interactables(repo_root=repo_root),
+            prior_inventory_path=current_dir / "ui_interactable_inventory.json",
+        )
+        filtered = _filter_business_logic_interactables(inventory)
+        workflows = _trace_workflows(filtered)
+        ledger = _build_ui_element_ledger(inventory=inventory, filtered=filtered, workflows=workflows)
+        verifier = _build_coverage_verifier(ledger=ledger)
+        generation_plan = _build_playwright_generation_plan(
+            repo_root=repo_root,
+            guidance_path=guidance,
+            inventory=inventory,
+            filtered=filtered,
+            workflows=workflows,
+            ledger=ledger,
+            verifier=verifier,
+            prior_preview_manifest_path=current_dir / "workflow_preview_manifest.json",
+        )
+        generated_files = _write_playwright_expectation_stubs(pipeline_dir=pipeline_dir, workflows=workflows)
+        generated_preview_files = _write_playwright_preview_specs(
+            pipeline_dir=pipeline_dir,
+            workflows=workflows,
+            preview_manifest=generation_plan["preview_video_driver"]["manifest"],
+        )
+
+        artifacts = {
+            "ui_interactable_inventory": _write_json(pipeline_dir / "ui_interactable_inventory.json", inventory),
+            "business_logic_interactable_filter": _write_json(
+                pipeline_dir / "business_logic_interactable_filter.json",
+                filtered,
+            ),
+            "ui_workflow_trace": _write_json(pipeline_dir / "ui_workflow_trace.json", workflows),
+            "ui_element_ledger": _write_json(pipeline_dir / "ui_element_ledger.json", ledger),
+            "playwright_coverage_verifier": _write_json(
+                pipeline_dir / "playwright_coverage_verifier.json",
+                verifier,
+            ),
+            "playwright_generation_plan": _write_json(
+                pipeline_dir / "playwright_generation_plan.json",
+                generation_plan,
+            ),
+            "generated_playwright_expectations": _write_json(
+                pipeline_dir / "generated_playwright_expectations.json",
+                {"files": generated_files},
+            ),
+            "generated_playwright_previews": _write_json(
+                pipeline_dir / "generated_playwright_previews.json",
+                {"files": generated_preview_files},
+            ),
+            "workflow_preview_manifest": _write_json(
+                pipeline_dir / "workflow_preview_manifest.json",
+                generation_plan["preview_video_driver"]["manifest"],
+            ),
+        }
+        _write_current_artifacts(
+            current_dir=current_dir,
+            inventory=inventory,
+            filtered=filtered,
+            workflows=workflows,
+            ledger=ledger,
+            verifier=verifier,
+            generation_plan=generation_plan,
+            generated_files=generated_files,
+            generated_preview_files=generated_preview_files,
+        )
+        store.mark_run_finished(run_id=run.run_id, status="succeeded")
+        return PostIntegrationPlaywrightDagResult(
+            exit_code=0,
+            message="post-integration Playwright workflow artifacts created",
+            run_id=run.run_id,
+            pipeline_dir=pipeline_dir,
+            artifacts=artifacts,
+        )
+    except Exception as exc:
+        error_path = pipeline_dir / "error.json"
+        error_path.write_text(json.dumps({"error": str(exc)}, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+        store.mark_run_finished(run_id=run.run_id, status="failed")
+        return PostIntegrationPlaywrightDagResult(
+            exit_code=1,
+            message=str(exc),
+            run_id=run.run_id,
+            pipeline_dir=pipeline_dir,
+            artifacts={"error": str(error_path)},
+        )
+
+
+def _write_json(path: Path, payload: Any) -> str:
+    path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return str(path)
+
+
+def _write_current_artifacts(
+    *,
+    current_dir: Path,
+    inventory: dict[str, Any],
+    filtered: dict[str, Any],
+    workflows: dict[str, Any],
+    ledger: dict[str, Any],
+    verifier: dict[str, Any],
+    generation_plan: dict[str, Any],
+    generated_files: list[dict[str, str]],
+    generated_preview_files: list[dict[str, str]],
+) -> None:
+    _write_json(current_dir / "ui_interactable_inventory.json", inventory)
+    _write_json(current_dir / "business_logic_interactable_filter.json", filtered)
+    _write_json(current_dir / "ui_workflow_trace.json", workflows)
+    _write_json(current_dir / "ui_element_ledger.json", ledger)
+    _write_json(current_dir / "playwright_coverage_verifier.json", verifier)
+    _write_json(current_dir / "playwright_generation_plan.json", generation_plan)
+    _write_json(current_dir / "generated_playwright_expectations.json", {"files": generated_files})
+    _write_json(current_dir / "generated_playwright_previews.json", {"files": generated_preview_files})
+    _write_json(current_dir / "workflow_preview_manifest.json", generation_plan["preview_video_driver"]["manifest"])
+
+
+def _source_files(repo_root: Path) -> list[Path]:
+    files: list[Path] = []
+    for path in repo_root.rglob("*"):
+        if not path.is_file() or path.suffix not in UI_SOURCE_SUFFIXES:
+            continue
+        if any(part in EXCLUDED_DIR_PARTS for part in path.relative_to(repo_root).parts):
+            continue
+        files.append(path)
+    return sorted(files)
+
+
+def _catalogue_interactables(*, repo_root: Path) -> dict[str, Any]:
+    interactables: list[dict[str, Any]] = []
+    for path in _source_files(repo_root):
+        text = path.read_text(encoding="utf-8", errors="ignore")
+        relative = path.relative_to(repo_root).as_posix()
+        seen_signatures: dict[str, int] = {}
+        for match in _find_interactable_tags(text):
+            signature = _interactable_signature(relative=relative, item=match)
+            seen_signatures[signature] = seen_signatures.get(signature, 0) + 1
+            item_id = _stable_id(signature, str(seen_signatures[signature]))
+            interactables.append(
+                {
+                    "id": item_id,
+                    "path": relative,
+                    "identity_signature": signature,
+                    "logical_signature": _interactable_logical_signature(item=match),
+                    **match,
+                }
+            )
+
+    return {
+        "kind": "ui_interactable_inventory.v1",
+        "process_step": 1,
+        "source_files_scanned": len(_source_files(repo_root)),
+        "interactables": interactables,
+        "summary": {"total": len(interactables)},
+    }
+
+
+def _merge_persisted_inventory(*, current_inventory: dict[str, Any], prior_inventory_path: Path) -> dict[str, Any]:
+    current_items = list(current_inventory.get("interactables") or [])
+    prior_items: dict[str, dict[str, Any]] = {}
+    prior_missing: list[dict[str, Any]] = []
+    if prior_inventory_path.exists():
+        try:
+            prior_payload = json.loads(prior_inventory_path.read_text(encoding="utf-8"))
+        except Exception:
+            prior_payload = {}
+        if isinstance(prior_payload, dict):
+            prior_items = {
+                str(item.get("id")): dict(item)
+                for item in prior_payload.get("interactables", [])
+                if isinstance(item, dict) and item.get("id")
+            }
+            prior_missing = [
+                dict(item)
+                for item in prior_payload.get("missing_interactables", [])
+                if isinstance(item, dict) and item.get("id")
+            ]
+
+    moved: list[dict[str, str]] = []
+    claimed_prior_ids: set[str] = set()
+    prior_by_logical: dict[str, list[dict[str, Any]]] = {}
+    for prior in prior_items.values():
+        logical_signature = str(prior.get("logical_signature") or "")
+        if logical_signature:
+            prior_by_logical.setdefault(logical_signature, []).append(prior)
+
+    normalized_current_items: list[dict[str, Any]] = []
+    for current in current_items:
+        current_item = dict(current)
+        current_id = str(current_item.get("id") or "")
+        if current_id not in prior_items:
+            prior_match = _match_moved_prior_item(
+                current_item=current_item,
+                prior_candidates=prior_by_logical.get(str(current_item.get("logical_signature") or ""), []),
+                claimed_prior_ids=claimed_prior_ids,
+            )
+            if prior_match is not None:
+                prior_id = str(prior_match["id"])
+                current_item["id"] = prior_id
+                current_item["previous_path"] = str(prior_match.get("path") or "")
+                current_item["movement_status"] = "moved"
+                claimed_prior_ids.add(prior_id)
+                moved.append(
+                    {
+                        "id": prior_id,
+                        "from_path": str(prior_match.get("path") or ""),
+                        "to_path": str(current_item.get("path") or ""),
+                    }
+                )
+        normalized_current_items.append(current_item)
+
+    current_items = normalized_current_items
+    current_ids = {str(item.get("id")) for item in current_items}
+    prior_ids = set(prior_items)
+    added_ids = sorted(current_ids.difference(prior_ids))
+    removed_ids = sorted(prior_ids.difference(current_ids))
+    moved_ids = {item["id"] for item in moved}
+    unchanged_ids = sorted(current_ids.intersection(prior_ids).difference(moved_ids))
+
+    active_items = [{**item, "status": "active"} for item in current_items]
+    missing_by_id = {str(item["id"]): {**item, "status": "missing"} for item in prior_missing}
+    for removed_id in removed_ids:
+        missing_by_id[removed_id] = {**prior_items[removed_id], "status": "missing"}
+
+    return {
+        **current_inventory,
+        "interactables": active_items,
+        "missing_interactables": sorted(missing_by_id.values(), key=lambda item: str(item.get("id"))),
+        "changes": {
+            "added_interactable_ids": added_ids,
+            "removed_interactable_ids": removed_ids,
+            "moved_interactable_ids": sorted(moved_ids),
+            "moved_interactables": moved,
+            "unchanged_interactable_ids": unchanged_ids,
+        },
+        "summary": {
+            "total": len(active_items),
+            "active": len(active_items),
+            "missing": len(missing_by_id),
+            "added": len(added_ids),
+            "removed": len(removed_ids),
+            "moved": len(moved),
+            "unchanged": len(unchanged_ids),
+        },
+    }
+
+
+def _match_moved_prior_item(
+    *,
+    current_item: dict[str, Any],
+    prior_candidates: list[dict[str, Any]],
+    claimed_prior_ids: set[str],
+) -> dict[str, Any] | None:
+    current_path = str(current_item.get("path") or "")
+    for prior in prior_candidates:
+        prior_id = str(prior.get("id") or "")
+        if prior_id in claimed_prior_ids:
+            continue
+        if str(prior.get("path") or "") != current_path:
+            return prior
+    return None
+
+
+def _interactable_signature(*, relative: str, item: dict[str, Any]) -> str:
+    payload = json.loads(_interactable_logical_signature(item=item))
+    payload["path"] = relative
+    return json.dumps(payload, sort_keys=True)
+
+
+def _interactable_logical_signature(*, item: dict[str, Any]) -> str:
+    attrs = item.get("attributes") if isinstance(item.get("attributes"), dict) else {}
+    signature_attrs = {
+        key: attrs.get(key)
+        for key in ("aria-label", "data-testid", "name", "id", "href", "to", "type", "placeholder", "value")
+        if attrs.get(key)
+    }
+    return json.dumps(
+        {
+            "tag": item.get("tag"),
+            "label": item.get("label"),
+            "attributes": signature_attrs,
+        },
+        sort_keys=True,
+    )
+
+
+def _find_interactable_tags(text: str) -> list[dict[str, Any]]:
+    pattern = re.compile(
+        r"<(?P<tag>button|a|input|select|textarea|form)\b(?P<attrs>[^>]*)>|role=[\"'](?P<role>button|link|checkbox|switch|tab|menuitem)[\"']",
+        re.IGNORECASE | re.MULTILINE,
+    )
+    items: list[dict[str, Any]] = []
+    for match in pattern.finditer(text):
+        attrs = match.group("attrs") or ""
+        tag = (match.group("tag") or match.group("role") or "role").lower()
+        line = text.count("\n", 0, match.start()) + 1
+        attributes = _parse_attributes(attrs)
+        raw_excerpt = text[match.start() : min(match.end() + 120, len(text))]
+        label = _derive_label(attributes=attributes, raw=raw_excerpt, tag=tag)
+        logic_signals = _logic_signals(tag=tag, attributes=attributes)
+        items.append(
+            {
+                "tag": tag,
+                "line": line,
+                "label": label,
+                "attributes": attributes,
+                "logic_signals": logic_signals,
+                "raw_excerpt": " ".join(text[match.start() : min(match.end() + 120, len(text))].split())[:240],
+            }
+        )
+    return items
+
+
+def _parse_attributes(attrs: str) -> dict[str, str]:
+    parsed: dict[str, str] = {}
+    for name, value in re.findall(r"([:@A-Za-z0-9_\-\.]+)(?:=\{?['\"]?([^'\"\}\s>]+)['\"]?\}?)?", attrs):
+        parsed[name] = value or "true"
+    return parsed
+
+
+def _derive_label(*, attributes: dict[str, str], raw: str, tag: str) -> str:
+    for key in ("aria-label", "data-testid", "name", "id", "placeholder", "href", "to", "value"):
+        value = attributes.get(key)
+        if value and value != "true":
+            return value
+    text_match = re.search(r">([^<>{]{1,80})<", raw)
+    if text_match:
+        return " ".join(text_match.group(1).split())
+    return tag
+
+
+def _logic_signals(*, tag: str, attributes: dict[str, str]) -> list[str]:
+    signals: list[str] = []
+    for key in attributes:
+        lowered = key.lower()
+        if (
+            lowered.startswith("on")
+            or lowered in {"action", "href", "to", "name", "formaction", "type", "checked", "value"}
+            or lowered.startswith("data-testid")
+        ):
+            signals.append(key)
+    if tag in {"form", "select", "textarea"}:
+        signals.append(f"tag:{tag}")
+    return sorted(set(signals))
+
+
+def _filter_business_logic_interactables(inventory: dict[str, Any]) -> dict[str, Any]:
+    kept: list[dict[str, Any]] = []
+    dropped: list[dict[str, Any]] = []
+    for item in inventory.get("interactables", []):
+        decision = _business_logic_decision(item)
+        output = {**item, "decision_reason": decision["reason"]}
+        if decision["keep"]:
+            kept.append(output)
+        else:
+            dropped.append(output)
+    return {
+        "kind": "business_logic_interactable_filter.v1",
+        "process_step": 2,
+        "kept": kept,
+        "dropped": dropped,
+        "summary": {"kept": len(kept), "dropped": len(dropped)},
+    }
+
+
+def _business_logic_decision(item: dict[str, Any]) -> dict[str, Any]:
+    attrs = item.get("attributes") if isinstance(item.get("attributes"), dict) else {}
+    signals = set(item.get("logic_signals") or [])
+    tag = str(item.get("tag") or "")
+    input_type = str(attrs.get("type") or "").lower()
+    if attrs.get("disabled") == "true" or attrs.get("aria-disabled") == "true":
+        return {"keep": False, "reason": "disabled interactable does not currently affect behavior"}
+    if tag == "a" and attrs.get("href") not in {None, "", "#"}:
+        return {"keep": True, "reason": "navigation changes application state or workflow route"}
+    if tag == "button" and (
+        input_type == "submit"
+        or any(str(signal).lower().startswith("on") for signal in signals)
+        or {"formaction", "action", "href", "to"}.intersection(signals)
+    ):
+        return {"keep": True, "reason": "button submits, routes, or has an event handler"}
+    if tag == "input" and input_type in {"hidden", "button", "reset", "image"}:
+        return {"keep": False, "reason": f"input type {input_type} is not a user business input"}
+    if tag in {"input", "select", "textarea", "form"} and (signals or attrs.get("name") or attrs.get("data-testid")):
+        return {"keep": True, "reason": "form control participates in submitted or persisted user state"}
+    if signals:
+        return {"keep": True, "reason": "event or routing attribute indicates business behavior"}
+    return {"keep": False, "reason": "no business logic signal detected"}
+
+
+def _trace_workflows(filtered: dict[str, Any]) -> dict[str, Any]:
+    grouped: dict[str, list[dict[str, Any]]] = {}
+    for item in filtered.get("kept", []):
+        grouped.setdefault(_workflow_key(item), []).append(item)
+
+    workflows: list[dict[str, Any]] = []
+    covered: set[str] = set()
+    for key, items in sorted(grouped.items()):
+        workflow_id = _stable_id("workflow", key)
+        item_ids = [str(item["id"]) for item in items]
+        covered.update(item_ids)
+        workflows.append(
+            {
+                "workflow_id": workflow_id,
+                "basis": "feature" if len(items) > 1 else "user",
+                "name": key.replace("/", " ").replace("-", " ").replace("_", " ").strip() or "ui workflow",
+                "source_paths": sorted({str(item["path"]) for item in items}),
+                "covered_interactable_ids": item_ids,
+                "seed_data_requirements": [
+                    "Create baseline authenticated/authorized state when the UI route requires it.",
+                    "Create each needed record, permission, or status inside the test before assertions.",
+                ],
+                "expectation_contract": [
+                    "Assert the initial UI state before interacting.",
+                    "Interact through accessible roles, labels, or stable test ids.",
+                    "Assert the business effect in UI state and persisted/API-visible state when available.",
+                ],
+            }
+        )
+
+    return {
+        "kind": "ui_workflow_trace.v1",
+        "process_step": 3,
+        "workflows": workflows,
+        "coverage": {
+            "kept_interactable_ids": [str(item["id"]) for item in filtered.get("kept", [])],
+            "covered_interactable_ids": sorted(covered),
+            "uncovered_interactable_ids": sorted(
+                {str(item["id"]) for item in filtered.get("kept", [])}.difference(covered)
+            ),
+        },
+    }
+
+
+def _build_ui_element_ledger(
+    *,
+    inventory: dict[str, Any],
+    filtered: dict[str, Any],
+    workflows: dict[str, Any],
+) -> dict[str, Any]:
+    kept_ids = {str(item.get("id")) for item in filtered.get("kept", [])}
+    workflow_by_interactable = _workflow_by_interactable(workflows)
+    rows: list[dict[str, Any]] = []
+    all_items = [*list(inventory.get("interactables", [])), *list(inventory.get("missing_interactables", []))]
+    for item in all_items:
+        item_id = str(item.get("id") or "")
+        category = _classify_ui_element(item=item, kept=item_id in kept_ids)
+        source_path = str(item.get("path") or "")
+        selector = _preferred_selector(item)
+        expected_behavior_source, confidence, assumption = _expected_behavior_source(category=category, item=item)
+        required_proof = _required_proof_for_category(category)
+        workflow_id = workflow_by_interactable.get(item_id)
+        priority = _priority_for_category(category)
+        coverage_status = _coverage_status(
+            category=category,
+            workflow_id=workflow_id,
+            item=item,
+        )
+        test_id = f"PW-{item_id}" if coverage_status == "covered" and category in BUSINESS_CONTROL_CATEGORIES else None
+        rows.append(
+            {
+                "id": item_id,
+                "route": _route_for_item(item),
+                "source": source_path,
+                "sourceCitation": f"{source_path}:{item.get('line')}",
+                "element": str(item.get("label") or item.get("tag") or ""),
+                "selector": selector,
+                "role": _role_for_item(item),
+                "href": _item_attrs(item).get("href") or _item_attrs(item).get("to"),
+                "handler": _handler_for_item(item),
+                "apiBoundary": _api_boundary_for_item(item),
+                "stateTouched": _state_touched_for_item(item),
+                "conditionalRule": _conditional_rule_for_item(item),
+                "dataSource": _data_source_for_item(item),
+                "currentBehavior": _current_behavior_for_item(category=category, item=item),
+                "expectedBehavior": _expected_behavior_for_item(category=category, item=item),
+                "expectedBehaviorSource": expected_behavior_source,
+                "confidence": confidence,
+                "assumption": assumption,
+                "classification": category,
+                "priority": priority,
+                "requiredProof": required_proof,
+                "testId": test_id,
+                "coverageStatus": coverage_status,
+                "workflowId": workflow_id,
+                "evidence": _ledger_evidence(
+                    coverage_status=coverage_status,
+                    workflow_id=workflow_id,
+                    source_path=source_path,
+                ),
+            }
+        )
+
+    return {
+        "kind": "ui_element_ledger.v1",
+        "process_step": 4,
+        "rows": rows,
+        "summary": {
+            "total": len(rows),
+            "business_controls": sum(1 for row in rows if row["classification"] in BUSINESS_CONTROL_CATEGORIES),
+            "high_medium_business_controls": sum(
+                1
+                for row in rows
+                if row["classification"] in BUSINESS_CONTROL_CATEGORIES and row["priority"] in {"HIGH", "MEDIUM"}
+            ),
+            "unknown": sum(1 for row in rows if row["classification"] == "unknown"),
+            "covered": sum(1 for row in rows if row["coverageStatus"] == "covered"),
+            "uncovered": sum(1 for row in rows if row["coverageStatus"] == "uncovered"),
+        },
+    }
+
+
+def _build_coverage_verifier(*, ledger: dict[str, Any]) -> dict[str, Any]:
+    rows = [row for row in ledger.get("rows", []) if isinstance(row, dict)]
+
+    def count_where(predicate: Any) -> int:
+        return sum(1 for row in rows if predicate(row))
+
+    failure_conditions = {
+        "unknown_count": count_where(lambda row: row.get("classification") == "unknown"),
+        "business_control_without_requiredProof": count_where(
+            lambda row: _is_business_row(row) and not row.get("requiredProof")
+        ),
+        "business_control_without_expectedBehaviorSource": count_where(
+            lambda row: _is_business_row(row) and not row.get("expectedBehaviorSource")
+        ),
+        "best_practice_assumption_without_assumption_note": count_where(
+            lambda row: row.get("expectedBehaviorSource") == "best-practice-assumption" and not row.get("assumption")
+        ),
+        "low_confidence_expected_behavior_not_surfaced": count_where(
+            lambda row: row.get("confidence") == "low" and not row.get("assumption")
+        ),
+        "business_control_without_test_or_disabled_note": count_where(
+            lambda row: _is_business_row(row)
+            and row.get("priority") in {"HIGH", "MEDIUM"}
+            and row.get("coverageStatus") not in {"covered", "intentionally-disabled"}
+        ),
+        "covered_row_without_test_id": count_where(
+            lambda row: _is_business_row(row) and row.get("coverageStatus") == "covered" and not row.get("testId")
+        ),
+        "seeded_content_allows_empty_state": count_where(
+            lambda row: row.get("classification") == "seeded-content"
+            and "fail when required seeded data is missing" not in str(row.get("requiredProof") or "")
+        ),
+        "status_gated_without_matrix": count_where(
+            lambda row: row.get("classification") == "status-gated"
+            and "show/hide action matrix" not in str(row.get("requiredProof") or "")
+        ),
+        "filter_state_without_reset_assertion": count_where(
+            lambda row: row.get("classification") == "filter-state"
+            and "reset" not in str(row.get("requiredProof") or "").lower()
+        ),
+        "mutation_without_state_or_request_assertion": count_where(
+            lambda row: row.get("classification") == "mutation"
+            and "durable state" not in str(row.get("requiredProof") or "")
+        ),
+        "role_gated_without_negative_assertion": count_where(
+            lambda row: row.get("classification") == "role-gated"
+            and "disallowed role" not in str(row.get("requiredProof") or "")
+        ),
+        "external_action_without_observable_side_effect": count_where(
+            lambda row: row.get("classification") == "external-action"
+            and "observable side effect" not in str(row.get("requiredProof") or "")
+        ),
+    }
+    unresolved = {key: value for key, value in failure_conditions.items() if value > 0}
+    return {
+        "kind": "playwright_coverage_verifier.v1",
+        "process_step": 5,
+        "passed": not unresolved,
+        "failure_conditions": failure_conditions,
+        "unresolved_failure_conditions": unresolved,
+        "stopping_rule": (
+            "Post-integration Playwright coverage is incomplete while any verifier failure condition is non-zero "
+            "unless each remaining row is explicitly promoted to a source-cited TODO with a test plan."
+        ),
+    }
+
+
+def _workflow_by_interactable(workflows: dict[str, Any]) -> dict[str, str]:
+    mapping: dict[str, str] = {}
+    for workflow in workflows.get("workflows", []):
+        workflow_id = str(workflow.get("workflow_id") or "")
+        for item_id in workflow.get("covered_interactable_ids", []):
+            mapping[str(item_id)] = workflow_id
+    return mapping
+
+
+def _is_business_row(row: dict[str, Any]) -> bool:
+    return str(row.get("classification") or "") in BUSINESS_CONTROL_CATEGORIES
+
+
+def _item_attrs(item: dict[str, Any]) -> dict[str, str]:
+    attrs = item.get("attributes")
+    return attrs if isinstance(attrs, dict) else {}
+
+
+def _classify_ui_element(*, item: dict[str, Any], kept: bool) -> str:
+    attrs = _item_attrs(item)
+    tag = str(item.get("tag") or "").lower()
+    raw = str(item.get("raw_excerpt") or "").lower()
+    signals = {str(signal).lower() for signal in item.get("logic_signals") or []}
+    if attrs.get("disabled") == "true" or attrs.get("aria-disabled") == "true":
+        return "display-only"
+    if attrs.get("href") or attrs.get("to"):
+        return "navigation"
+    if tag in {"select"} or any(token in raw for token in ("filter", "sort", "search", "combobox")):
+        return "filter-state"
+    if tag == "form" or attrs.get("type") == "submit" or attrs.get("action") or attrs.get("formaction"):
+        return "mutation"
+    if any(token in raw for token in ("dialog", "modal", "drawer", "wizard", "menu", "dropdown")):
+        return "workflow-step"
+    if any(token in raw for token in ("role", "permission", "admin", "manager", "viewer")):
+        return "role-gated"
+    if any(token in raw for token in ("status", "draft", "scheduled", "active", "completed", "closed")):
+        return "status-gated"
+    if any(token in raw for token in ("download", "copy", "clipboard", "upload", "email", "calendar", "qr")):
+        return "external-action"
+    if any(token in raw for token in ("seed", "record", "team", "user", "report", "analysis", "score")):
+        return "seeded-content"
+    if kept:
+        return "workflow-step" if tag in {"button", "input", "textarea"} or signals else "navigation"
+    return "display-only"
+
+
+def _priority_for_category(category: str) -> str:
+    if category in {"mutation", "workflow-step", "role-gated", "status-gated", "filter-state"}:
+        return "HIGH"
+    if category in {"navigation", "seeded-content", "external-action"}:
+        return "MEDIUM"
+    if category == "display-only":
+        return "SKIP"
+    return "LOW"
+
+
+def _required_proof_for_category(category: str) -> str:
+    proof = {
+        "display-only": "Render check only when the content is review-critical or visually fragile.",
+        "navigation": "Click reaches the correct route/surface and preserves required org/group/entity context.",
+        "filter-state": "Options render from real data; selecting changes downstream records; reset restores scope.",
+        "mutation": "Trigger causes durable state change, API request, or visible confirmed result.",
+        "workflow-step": (
+            "Surface opens, validates required fields, advances/cancels correctly, and asserts final state."
+        ),
+        "role-gated": "Allowed role sees/uses the control; disallowed role cannot see or use it before mutation.",
+        "status-gated": "Every relevant status has a show/hide action matrix with positive and negative assertions.",
+        "seeded-content": "Real seeded data renders and tests fail when required seeded data is missing.",
+        "external-action": "Download/copy/upload/email/provider action has an observable side effect.",
+        "unknown": "Investigate source until the element can be classified or source-cited as disabled/TODO.",
+    }
+    return proof.get(category, proof["unknown"])
+
+
+def _expected_behavior_source(*, category: str, item: dict[str, Any]) -> tuple[str, str, str | None]:
+    if category == "display-only":
+        return "class-2-code-implementation", "high", None
+    if category in BUSINESS_CONTROL_CATEGORIES:
+        return "class-2-code-implementation", "medium", None
+    return (
+        "best-practice-assumption",
+        "low",
+        "Classification could not be resolved from source; inspect source docs, implementation, and adjacent patterns.",
+    )
+
+
+def _preferred_selector(item: dict[str, Any]) -> str:
+    attrs = _item_attrs(item)
+    if attrs.get("data-testid"):
+        return f"[data-testid=\"{attrs['data-testid']}\"]"
+    label = str(attrs.get("aria-label") or item.get("label") or "").strip()
+    role = _role_for_item(item)
+    if label and role:
+        return f"page.getByRole('{role}', {{ name: /{_regex_safe(label)}/i }})"
+    if label:
+        return f"page.getByLabel(/{_regex_safe(label)}/i)"
+    return f"{item.get('tag') or 'element'} at {item.get('path')}:{item.get('line')}"
+
+
+def _role_for_item(item: dict[str, Any]) -> str | None:
+    tag = str(item.get("tag") or "").lower()
+    attrs = _item_attrs(item)
+    if attrs.get("role"):
+        return attrs["role"]
+    if tag == "button":
+        return "button"
+    if tag == "a":
+        return "link"
+    if tag == "select":
+        return "combobox"
+    if tag in {"input", "textarea"}:
+        return "textbox"
+    return None
+
+
+def _handler_for_item(item: dict[str, Any]) -> str | None:
+    attrs = _item_attrs(item)
+    handlers = [key for key in sorted(attrs) if key.lower().startswith("on") or key in {"action", "formaction"}]
+    return ",".join(handlers) if handlers else None
+
+
+def _api_boundary_for_item(item: dict[str, Any]) -> str | None:
+    attrs = _item_attrs(item)
+    return attrs.get("action") or attrs.get("formaction") or None
+
+
+def _state_touched_for_item(item: dict[str, Any]) -> list[str]:
+    attrs = _item_attrs(item)
+    return [value for key, value in sorted(attrs.items()) if key in {"name", "value", "checked"} and value]
+
+
+def _conditional_rule_for_item(item: dict[str, Any]) -> str | None:
+    raw = str(item.get("raw_excerpt") or "")
+    for token in ("disabled", "aria-disabled", "role", "permission", "status"):
+        if token in raw:
+            return f"source excerpt contains {token}"
+    return None
+
+
+def _data_source_for_item(item: dict[str, Any]) -> str | None:
+    attrs = _item_attrs(item)
+    return attrs.get("name") or attrs.get("href") or attrs.get("to") or None
+
+
+def _current_behavior_for_item(*, category: str, item: dict[str, Any]) -> str:
+    label = str(item.get("label") or item.get("tag") or "element")
+    return f"{label} is present in source and classified as {category} from its tag/attributes."
+
+
+def _expected_behavior_for_item(*, category: str, item: dict[str, Any]) -> str:
+    label = str(item.get("label") or item.get("tag") or "element")
+    return f"{label} should satisfy the {category} proof requirement: {_required_proof_for_category(category)}"
+
+
+def _coverage_status(*, category: str, workflow_id: str | None, item: dict[str, Any]) -> str:
+    attrs = _item_attrs(item)
+    if item.get("status") == "missing":
+        return "uncovered"
+    if attrs.get("disabled") == "true" or attrs.get("aria-disabled") == "true":
+        return "intentionally-disabled"
+    if category == "display-only":
+        return "covered"
+    if workflow_id:
+        return "covered"
+    return "uncovered"
+
+
+def _ledger_evidence(*, coverage_status: str, workflow_id: str | None, source_path: str) -> str:
+    if coverage_status == "covered" and workflow_id:
+        return f"Mapped to generated workflow {workflow_id}; replace scaffold with calibrated Playwright proof."
+    if coverage_status == "intentionally-disabled":
+        return f"Source marks control disabled in {source_path}; keep source-cited disabled note."
+    return f"Source-cited from {source_path}; needs workflow/test mapping or source-cited TODO."
+
+
+def _route_for_item(item: dict[str, Any]) -> str:
+    path = str(item.get("path") or "")
+    if path.startswith("app/"):
+        route = path.removeprefix("app/")
+        for suffix in ("/page.tsx", "/page.jsx", "/page.vue", "/page.svelte", "/page.html"):
+            route = route.removesuffix(suffix)
+        return "/" + route.strip("/")
+    return _workflow_key(item)
+
+
+def _regex_safe(value: str) -> str:
+    return re.escape(value.strip("/") or value)
+
+
+def _workflow_key(item: dict[str, Any]) -> str:
+    path = str(item.get("path") or "")
+    parts = Path(path).parts
+    for marker in ("app", "pages", "routes", "src"):
+        if marker in parts:
+            idx = parts.index(marker)
+            return "/".join(parts[idx + 1 : -1] or parts[idx + 1 :] or [path])
+    return str(Path(path).parent)
+
+
+def _build_playwright_generation_plan(
+    *,
+    repo_root: Path,
+    guidance_path: Path | None,
+    inventory: dict[str, Any],
+    filtered: dict[str, Any],
+    workflows: dict[str, Any],
+    ledger: dict[str, Any],
+    verifier: dict[str, Any],
+    prior_preview_manifest_path: Path,
+) -> dict[str, Any]:
+    rewrite_driver = _build_playwright_rewrite_driver(inventory=inventory, workflows=workflows)
+    preview_video_driver = _build_preview_video_driver(
+        repo_root=repo_root,
+        workflows=workflows,
+        rewrite_driver=rewrite_driver,
+        prior_preview_manifest_path=prior_preview_manifest_path,
+    )
+    return {
+        "kind": "playwright_generation_plan.v1",
+        "process_step": 4,
+        "playwright_guidance": {
+            "path": str(guidance_path.relative_to(repo_root)) if guidance_path else None,
+            "status": "found" if guidance_path else "missing",
+            "lookup_names": ["how to playwright right.md", "HOW_TO_PLAYWRIGHT_RIGHT.md"],
+        },
+        "inputs": {
+            "inventory_total": inventory.get("summary", {}).get("total", 0),
+            "business_logic_interactables": filtered.get("summary", {}).get("kept", 0),
+            "workflow_count": len(workflows.get("workflows", [])),
+            "ledger_rows": ledger.get("summary", {}).get("total", 0),
+            "verifier_passed": verifier.get("passed"),
+        },
+        "rewrite_driver": rewrite_driver,
+        "coverage_verifier": verifier,
+        "ledger_summary": ledger.get("summary", {}),
+        "flow_doc_contract": _flow_doc_contract(),
+        "proof_calibration_plan": _proof_calibration_plan(),
+        "deep_business_control_pass": _deep_business_control_pass(ledger=ledger),
+        "preview_video_driver": preview_video_driver,
+        "test_authoring_rules": [
+            (
+                "Every visible UI element must be represented in ui_element_ledger before Playwright tests are "
+                "claimed complete."
+            ),
+            "Every HIGH/MEDIUM business control must map to a Playwright test id or source-cited disabled/TODO note.",
+            "Seeded/demo workflows must fail when required seed data is missing; empty states are explicit tests only.",
+            "Write expectations against business outcomes, not page load, clickability, labels, or mock behavior.",
+            "For filters, prove options, scoped data change, reset/unselect, and restored downstream state.",
+            "For mutations, assert durable state, request/API boundary, or visible confirmed result.",
+            "For role/status gates, assert both allowed and forbidden behavior.",
+            (
+                "Classify calibration failures as test-bug, implementation-gap, seed-fixture-gap, "
+                "route-config-gap, or environment-gap."
+            ),
+            "Generate workflow videos only after calibrated E2E proof and no unresolved HIGH/MEDIUM ledger gaps.",
+            "Prefer accessibility locators, then labels, then stable data-testid locators.",
+        ],
+        "output_target": ".devflow/post_integration_playwright/<run_id>/generated_tests",
+    }
+
+
+def _flow_doc_contract() -> dict[str, Any]:
+    return {
+        "required_sections": [
+            "Mermaid Diagram",
+            "Context",
+            "Key Data Shapes",
+            "API Summary Table",
+            "State Transitions",
+            "Error Handling",
+            "Role Rules",
+            "Test Assertions",
+            "Coverage Matrix",
+        ],
+        "coverage_matrix_columns": [
+            "Control",
+            "Category",
+            "Preconditions",
+            "Expected browser behavior",
+            "Test file",
+            "Test ID",
+        ],
+        "source_of_truth": "Code is source of truth; update docs when docs and shipped code disagree.",
+    }
+
+
+def _proof_calibration_plan() -> dict[str, Any]:
+    return {
+        "status": "required_after_verifier_zero",
+        "failure_classes": {
+            "test-bug": "Wrong/brittle locator or assertion; fix test and rerun.",
+            "implementation-gap": "Expected behavior is missing or broken; keep failing proof and document gap.",
+            "seed-fixture-gap": "Required seeded/demo data is absent or malformed; document fixture requirement.",
+            "route-config-gap": "Route/control expected by source/docs is not deployed or configured.",
+            "environment-gap": "Auth/service/browser/provider setup blocks execution; document rerun command/env.",
+        },
+        "completion_rule": (
+            "All test-bug failures are fixed and rerun; remaining failures are classified as product, seed, route, "
+            "or environment gaps without weakening assertions."
+        ),
+    }
+
+
+def _deep_business_control_pass(*, ledger: dict[str, Any]) -> dict[str, Any]:
+    rows = [
+        row
+        for row in ledger.get("rows", [])
+        if isinstance(row, dict)
+        and row.get("classification") in BUSINESS_CONTROL_CATEGORIES
+        and row.get("priority") in {"HIGH", "MEDIUM"}
+    ]
+    return {
+        "status": "required",
+        "row_count": len(rows),
+        "ledger_row_ids": [str(row.get("id")) for row in rows],
+        "requirements_by_category": {
+            "workflow-step": (
+                "Open surface, assert title/content, required fields, submit/cancel/back, final visible state."
+            ),
+            "filter-state": "Options/data render, selection changes records, reset restores scope.",
+            "mutation": "Observe request/API boundary or durable state plus success/error UI.",
+            "role-gated": "Allowed role sees/uses; disallowed role does not see or is blocked before mutation.",
+            "status-gated": "Assert show/hide matrix for each relevant status.",
+            "navigation": "Reach expected route and preserve required context.",
+            "external-action": "Observe download/copy/upload/email/provider side effect.",
+            "seeded-content": "Real seeded data renders; missing seed data fails early.",
+        },
+    }
+
+
+def _build_preview_video_driver(
+    *,
+    repo_root: Path,
+    workflows: dict[str, Any],
+    rewrite_driver: dict[str, Any],
+    prior_preview_manifest_path: Path,
+) -> dict[str, Any]:
+    e2e_status = _read_e2e_status(repo_root=repo_root)
+    manifest = _build_preview_manifest(
+        repo_root=repo_root,
+        workflows=workflows,
+        rewrite_driver=rewrite_driver,
+        prior_preview_manifest_path=prior_preview_manifest_path,
+        e2e_status=e2e_status,
+    )
+    return {
+        "status": "ready_to_record" if e2e_status["status"] == "passed" else "waiting_for_e2e_pass",
+        "e2e_gate": e2e_status,
+        "policy": {
+            "record_when": "all_e2e_pass",
+            "preserve_existing_video_when": "workflow_fingerprint_unchanged_and_video_exists",
+            "refresh_when": [
+                "new_workflow",
+                "impacted_by_rewrite_driver",
+                "missing_video",
+                "workflow_fingerprint_changed",
+            ],
+        },
+        "manifest": manifest,
+        "record_command": (
+            "npx playwright test .devflow/post_integration_playwright/current/generated_preview_specs "
+            "--config=playwright.config.ts"
+        ),
+    }
+
+
+def _read_e2e_status(*, repo_root: Path) -> dict[str, Any]:
+    status_path = repo_root / ".devflow" / "post_integration_playwright" / "current" / "e2e_status.json"
+    if status_path.exists():
+        try:
+            payload = json.loads(status_path.read_text(encoding="utf-8"))
+        except Exception:
+            payload = {}
+        if isinstance(payload, dict) and payload.get("status"):
+            return {
+                "status": str(payload.get("status")),
+                "source": str(status_path.relative_to(repo_root)),
+                "run_id": payload.get("run_id"),
+            }
+    return {"status": "unknown", "source": None, "run_id": None}
+
+
+def _build_preview_manifest(
+    *,
+    repo_root: Path,
+    workflows: dict[str, Any],
+    rewrite_driver: dict[str, Any],
+    prior_preview_manifest_path: Path,
+    e2e_status: dict[str, Any],
+) -> dict[str, Any]:
+    prior_by_workflow = _read_prior_preview_records(prior_preview_manifest_path)
+    impacted = set(str(workflow_id) for workflow_id in rewrite_driver.get("impacted_workflow_ids", []))
+    records: list[dict[str, Any]] = []
+    stale: list[str] = []
+    fresh: list[str] = []
+    waiting: list[str] = []
+    for workflow in workflows.get("workflows", []):
+        workflow_id = str(workflow.get("workflow_id"))
+        fingerprint = _workflow_fingerprint(workflow)
+        prior = prior_by_workflow.get(workflow_id, {})
+        prior_video_path = str(prior.get("video_path") or "")
+        prior_video_exists = bool(prior_video_path) and (repo_root / prior_video_path).exists()
+        unchanged = prior.get("workflow_fingerprint") == fingerprint
+        needs_refresh = workflow_id in impacted or not prior_video_exists or not unchanged
+        if not needs_refresh:
+            status = "fresh"
+            fresh.append(workflow_id)
+            video_path = prior_video_path
+        elif e2e_status.get("status") == "passed":
+            status = "needs_recording"
+            stale.append(workflow_id)
+            video_path = _preview_video_path(workflow_id)
+        else:
+            status = "waiting_for_e2e_pass"
+            waiting.append(workflow_id)
+            video_path = prior_video_path or _preview_video_path(workflow_id)
+        records.append(
+            {
+                "workflow_id": workflow_id,
+                "workflow_fingerprint": fingerprint,
+                "status": status,
+                "video_path": video_path,
+                "preview_spec_path": (
+                    ".devflow/post_integration_playwright/current/generated_preview_specs/"
+                    f"{workflow_id}.preview.spec.ts"
+                ),
+                "covered_interactable_ids": list(workflow.get("covered_interactable_ids", [])),
+                "source_paths": list(workflow.get("source_paths", [])),
+                "refresh_reasons": _preview_refresh_reasons(
+                    workflow_id=workflow_id,
+                    impacted=impacted,
+                    prior_video_exists=prior_video_exists,
+                    unchanged=unchanged,
+                ),
+            }
+        )
+    prior_ids = set(prior_by_workflow)
+    active_ids = {str(workflow.get("workflow_id")) for workflow in workflows.get("workflows", [])}
+    retired_ids = sorted(prior_ids.difference(active_ids))
+    return {
+        "kind": "workflow_preview_manifest.v1",
+        "e2e_gate_status": e2e_status.get("status"),
+        "records": records,
+        "summary": {
+            "total": len(records),
+            "fresh": len(fresh),
+            "needs_recording": len(stale),
+            "waiting_for_e2e_pass": len(waiting),
+            "retired": len(retired_ids),
+        },
+        "retired_workflow_ids": retired_ids,
+    }
+
+
+def _read_prior_preview_records(path: Path) -> dict[str, dict[str, Any]]:
+    if not path.exists():
+        return {}
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+    if not isinstance(payload, dict):
+        return {}
+    return {
+        str(record.get("workflow_id")): dict(record)
+        for record in payload.get("records", [])
+        if isinstance(record, dict) and record.get("workflow_id")
+    }
+
+
+def _workflow_fingerprint(workflow: dict[str, Any]) -> str:
+    return _stable_id(
+        json.dumps(
+            {
+                "workflow_id": workflow.get("workflow_id"),
+                "source_paths": workflow.get("source_paths", []),
+                "covered_interactable_ids": workflow.get("covered_interactable_ids", []),
+                "seed_data_requirements": workflow.get("seed_data_requirements", []),
+                "expectation_contract": workflow.get("expectation_contract", []),
+            },
+            sort_keys=True,
+        )
+    )
+
+
+def _preview_video_path(workflow_id: str) -> str:
+    return f".devflow/post_integration_playwright/current/videos/{workflow_id}.webm"
+
+
+def _preview_refresh_reasons(
+    *,
+    workflow_id: str,
+    impacted: set[str],
+    prior_video_exists: bool,
+    unchanged: bool,
+) -> list[str]:
+    reasons: list[str] = []
+    if workflow_id in impacted:
+        reasons.append("impacted_by_rewrite_driver")
+    if not prior_video_exists:
+        reasons.append("missing_video")
+    if not unchanged:
+        reasons.append("workflow_fingerprint_changed")
+    return reasons
+
+
+def _build_playwright_rewrite_driver(*, inventory: dict[str, Any], workflows: dict[str, Any]) -> dict[str, Any]:
+    changes = inventory.get("changes") if isinstance(inventory.get("changes"), dict) else {}
+    added_ids = list(changes.get("added_interactable_ids") or [])
+    removed_ids = list(changes.get("removed_interactable_ids") or [])
+    moved_items = list(changes.get("moved_interactables") or [])
+    moved_ids = [str(item.get("id")) for item in moved_items if isinstance(item, dict)]
+    impacted_workflows = _impacted_workflows(
+        changed_ids=set(added_ids + removed_ids + moved_ids),
+        workflows=workflows,
+    )
+    return {
+        "status": "rewrite_required" if added_ids or removed_ids or moved_items else "no_rewrite_needed",
+        "added_interactable_ids": added_ids,
+        "removed_interactable_ids": removed_ids,
+        "moved_interactables": moved_items,
+        "impacted_workflow_ids": impacted_workflows,
+        "rewrite_actions": _rewrite_actions(
+            added_ids=added_ids,
+            removed_ids=removed_ids,
+            moved_items=moved_items,
+            impacted_workflow_ids=impacted_workflows,
+        ),
+    }
+
+
+def _impacted_workflows(*, changed_ids: set[str], workflows: dict[str, Any]) -> list[str]:
+    impacted: list[str] = []
+    for workflow in workflows.get("workflows", []):
+        covered = {str(item_id) for item_id in workflow.get("covered_interactable_ids", [])}
+        if changed_ids.intersection(covered):
+            impacted.append(str(workflow.get("workflow_id")))
+    return sorted(set(impacted))
+
+
+def _rewrite_actions(
+    *,
+    added_ids: list[str],
+    removed_ids: list[str],
+    moved_items: list[Any],
+    impacted_workflow_ids: list[str],
+) -> list[dict[str, Any]]:
+    actions: list[dict[str, Any]] = []
+    if added_ids:
+        actions.append(
+            {
+                "action": "add_expectations",
+                "interactable_ids": added_ids,
+                "workflow_ids": impacted_workflow_ids,
+                "instruction": "Add workflow coverage and assertions for newly active business interactables.",
+            }
+        )
+    if removed_ids:
+        actions.append(
+            {
+                "action": "remove_or_replace_expectations",
+                "interactable_ids": removed_ids,
+                "workflow_ids": impacted_workflow_ids,
+                "instruction": "Remove stale locators or replace them with active workflow-preserving interactables.",
+            }
+        )
+    if moved_items:
+        actions.append(
+            {
+                "action": "rewrite_moved_locators",
+                "moved_interactables": moved_items,
+                "workflow_ids": impacted_workflow_ids,
+                "instruction": "Update route, fixture setup, and locator scope for interactables that moved surfaces.",
+            }
+        )
+    return actions
+
+
+def _write_playwright_expectation_stubs(*, pipeline_dir: Path, workflows: dict[str, Any]) -> list[dict[str, str]]:
+    generated_dir = pipeline_dir / "generated_tests"
+    generated_dir.mkdir(parents=True, exist_ok=True)
+    files: list[dict[str, str]] = []
+    for workflow in workflows.get("workflows", []):
+        workflow_id = str(workflow["workflow_id"])
+        test_path = generated_dir / f"{workflow_id}.spec.ts"
+        test_path.write_text(_playwright_stub(workflow), encoding="utf-8")
+        files.append({"workflow_id": workflow_id, "path": str(test_path)})
+    return files
+
+
+def _write_playwright_preview_specs(
+    *,
+    pipeline_dir: Path,
+    workflows: dict[str, Any],
+    preview_manifest: dict[str, Any],
+) -> list[dict[str, str]]:
+    generated_dir = pipeline_dir / "generated_preview_specs"
+    generated_dir.mkdir(parents=True, exist_ok=True)
+    records_by_workflow = {
+        str(record.get("workflow_id")): record
+        for record in preview_manifest.get("records", [])
+        if isinstance(record, dict) and record.get("workflow_id")
+    }
+    files: list[dict[str, str]] = []
+    for workflow in workflows.get("workflows", []):
+        workflow_id = str(workflow["workflow_id"])
+        record = records_by_workflow.get(workflow_id, {})
+        if record.get("status") == "fresh":
+            continue
+        test_path = generated_dir / f"{workflow_id}.preview.spec.ts"
+        test_path.write_text(_playwright_preview_stub(workflow=workflow, manifest_record=record), encoding="utf-8")
+        files.append({"workflow_id": workflow_id, "path": str(test_path), "status": str(record.get("status") or "")})
+    return files
+
+
+def _playwright_stub(workflow: dict[str, Any]) -> str:
+    name = str(workflow.get("name") or "ui workflow")
+    ids = ", ".join(str(item_id) for item_id in workflow.get("covered_interactable_ids", []))
+    return (
+        "import { test, expect } from '@playwright/test';\n\n"
+        f"test.describe('{_ts_string(name)}', () => {{\n"
+        f"  test('covers business interactables: {_ts_string(ids)}', async ({{ page }}) => {{\n"
+        "    // Replace this scaffold with calibrated proof from ui_element_ledger.json.\n"
+        "    // Seed required business data first and fail early if expected seed records are missing.\n"
+        "    // Assert business state changes, negative role/status behavior, and reset/cancel paths as required.\n"
+        "    await page.goto('/');\n"
+        "    await expect(page).toHaveURL(/.*/);\n"
+        "  });\n"
+        "});\n"
+    )
+
+
+def _playwright_preview_stub(*, workflow: dict[str, Any], manifest_record: dict[str, Any]) -> str:
+    name = str(workflow.get("name") or "ui workflow")
+    workflow_id = str(workflow.get("workflow_id") or "")
+    video_path = str(manifest_record.get("video_path") or _preview_video_path(workflow_id))
+    ids = ", ".join(str(item_id) for item_id in workflow.get("covered_interactable_ids", []))
+    return (
+        "import { test, expect } from '@playwright/test';\n\n"
+        "test.use({ video: 'on' });\n\n"
+        f"test.describe('{_ts_string(name)} preview', () => {{\n"
+        f"  test('records workflow preview for {_ts_string(workflow_id)}', async ({{ page }}, testInfo) => {{\n"
+        "    test.skip(process.env.DEVFLOW_E2E_PASSED !== '1', 'Preview videos record only after E2E passes.');\n"
+        f"    testInfo.annotations.push({{ type: 'devflow-video-path', description: '{_ts_string(video_path)}' }});\n"
+        f"    testInfo.annotations.push({{ type: 'devflow-interactables', description: '{_ts_string(ids)}' }});\n"
+        "    // Record only after the expectation spec has calibrated real business-control proof.\n"
+        "    // Do not use video as source evidence or as a substitute for assertions.\n"
+        "    await page.goto('/');\n"
+        "    await expect(page).toHaveURL(/.*/);\n"
+        "  });\n"
+        "});\n"
+    )
+
+
+def _ts_string(value: str) -> str:
+    return value.replace("\\", "\\\\").replace("'", "\\'")
+
+
+def _find_playwright_guidance(repo_root: Path) -> Path | None:
+    exact_names = {"how to playwright right.md", "HOW_TO_PLAYWRIGHT_RIGHT.md"}
+    candidates: list[Path] = []
+    for path in repo_root.rglob("*.md"):
+        if any(part in EXCLUDED_DIR_PARTS for part in path.relative_to(repo_root).parts):
+            continue
+        if path.name in exact_names:
+            return path
+        lower = path.name.lower()
+        if "playwright" in lower and "right" in lower:
+            candidates.append(path)
+    return sorted(candidates)[0] if candidates else None
+
+
+def _stable_id(*parts: str) -> str:
+    raw = ":".join(parts)
+    return hashlib.sha1(raw.encode("utf-8")).hexdigest()[:12]