devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/integration/dag.py

@@ -0,0 +1,3539 @@
+from __future__ import annotations
+
+import json
+import hashlib
+import logging
+import os
+from urllib.error import HTTPError
+import re
+import subprocess
+import uuid
+from collections.abc import Callable as _Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+from urllib.request import Request, urlopen
+
+from pydantic import BaseModel, Field
+
+from ..idea.paths import get_idea_paths
+from ..vendor.datalumina_genai.core.nodes.agent import AgentConfig, AgentNode
+from ..vendor.datalumina_genai.core.nodes.base import Node
+from ..vendor.datalumina_genai.core.schema import NodeConfig, WorkflowSchema
+from ..vendor.datalumina_genai.core.task import TaskContext
+from ..vendor.datalumina_genai.core.workflow import Workflow
+from ..project_registry import find_project_for_repo_root, resolve_project_entry
+from ..project_registration.dag import _infer_owner_repo, _lookup_supabase_project_uuid
+from ..devflow_state import _is_uuid_like, publish_devflow_state
+from . import agentic as integration_agentic
+from .prompts import load_integration_node_instruction
+
+logger = logging.getLogger(__name__)
+
+INTEGRATION_RESUME_METADATA = "resume_fingerprint.json"
+_SOURCE_EVIDENCE_EXTENSIONS = {".py", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"}
+_SOURCE_ROOT_NAMES = ("app", "src")
+_PROJECT_MANIFESTS = ("pyproject.toml", "package.json", "setup.py", "setup.cfg", "requirements.txt", "Pipfile")
+_IGNORED_EVIDENCE_DIR_NAMES = {".devflow", ".git", "node_modules", "dist", "build", "coverage", "__pycache__", ".venv", "venv"}
+_STORY_CODE_PATH_KEYS = {"file_targets", "implementation_targets", "paths", "path", "file_path", "files", "written_paths", "validator_input_paths", "seams", "preferred_pathways"}
+_PROJECT_CODE_ROOT_METADATA_KEYS = ("implementation_roots", "implementation_root", "source_roots", "source_root", "code_roots", "code_root", "app_roots", "app_root", "backend_root", "frontend_root")
+
+
+def _sha256_json(payload: dict[str, Any] | list[Any]) -> str:
+    return hashlib.sha256(
+        json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    ).hexdigest()
+
+
+def _sha256_file(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def _relative_repo_path(*, repo_root: Path, path: Path) -> str:
+    try:
+        return str(path.relative_to(repo_root))
+    except ValueError:
+        return str(path)
+
+
+def _story_code_paths(payload: Any) -> list[str]:
+    results: list[str] = []
+
+    def _push(value: Any) -> None:
+        if isinstance(value, str):
+            candidate = value.strip()
+            if candidate:
+                results.append(candidate)
+        elif isinstance(value, dict):
+            path_value = value.get("path")
+            if isinstance(path_value, str) and path_value.strip():
+                results.append(path_value.strip())
+        elif isinstance(value, list):
+            for item in value:
+                _push(item)
+
+    def _walk(node: Any) -> None:
+        if isinstance(node, dict):
+            for key, value in node.items():
+                if str(key or "").strip().lower() in _STORY_CODE_PATH_KEYS:
+                    _push(value)
+                _walk(value)
+        elif isinstance(node, list):
+            for item in node:
+                _walk(item)
+
+    _walk(payload)
+    return results
+
+
+def _story_code_root(repo_root: Path, raw_path: str) -> Path | None:
+    candidate = raw_path.strip()
+    if not candidate:
+        return None
+    path = Path(candidate)
+    if path.is_absolute():
+        try:
+            path = path.relative_to(repo_root)
+        except ValueError:
+            return None
+    parts = path.parts
+    if not parts or parts[0].startswith('.') or parts[0] in {'tests', 'ai_docs'}:
+        return None
+    for index, part in enumerate(parts[:-1]):
+        if part in _SOURCE_ROOT_NAMES:
+            return repo_root.joinpath(*parts[: index + 1])
+    if len(parts) > 1:
+        return repo_root.joinpath(*parts[:-1])
+    return None
+
+
+def _project_configured_code_roots(repo_root: Path) -> list[Path]:
+    project_entry = find_project_for_repo_root(repo_root)
+    metadata = (project_entry or {}).get("metadata")
+    if not isinstance(metadata, dict):
+        return []
+
+    roots: list[Path] = []
+    for key in _PROJECT_CODE_ROOT_METADATA_KEYS:
+        raw = metadata.get(key)
+        values = raw if isinstance(raw, list) else [raw]
+        for value in values:
+            if not isinstance(value, str) or not value.strip():
+                continue
+            candidate = Path(value.strip())
+            if not candidate.is_absolute():
+                candidate = repo_root / candidate
+            try:
+                resolved = candidate.resolve()
+                resolved.relative_to(repo_root.resolve())
+            except Exception:
+                continue
+            if resolved.is_dir():
+                roots.append(resolved)
+    return sorted(set(roots))
+
+
+def _find_manifest_project_roots(repo_root: Path) -> list[Path]:
+    project_roots: list[Path] = []
+    candidates = [repo_root]
+    candidates.extend(
+        path
+        for path in repo_root.iterdir()
+        if path.is_dir() and path.name not in _IGNORED_EVIDENCE_DIR_NAMES and not path.name.startswith(".")
+    )
+    for path in candidates:
+        if any((path / name).exists() for name in _PROJECT_MANIFESTS):
+            project_roots.append(path)
+    return sorted(set(project_roots))
+
+
+def _expand_project_code_roots(project_roots: list[Path]) -> list[Path]:
+    roots: list[Path] = []
+    for project_root in project_roots:
+        nested_roots = [project_root / name for name in _SOURCE_ROOT_NAMES if (project_root / name).is_dir()]
+        if nested_roots:
+            roots.extend(nested_roots)
+            continue
+        direct_files = [child for child in project_root.iterdir() if child.is_file() and child.suffix in _SOURCE_EVIDENCE_EXTENSIONS]
+        if direct_files:
+            roots.append(project_root)
+    return sorted(set(root for root in roots if root.exists()))
+
+
+def _implementation_code_roots(*, repo_root: Path, implemented_stories: list[dict[str, Any]]) -> list[Path]:
+    story_roots = sorted({
+        root
+        for story in implemented_stories
+        for raw_path in _story_code_paths(story)
+        for root in [_story_code_root(repo_root, raw_path)]
+        if root is not None and root.exists()
+    })
+    if story_roots:
+        return story_roots
+
+    configured_roots = _project_configured_code_roots(repo_root)
+    if configured_roots:
+        return configured_roots
+
+    project_roots = _find_manifest_project_roots(repo_root)
+    nested_project_roots = [root for root in project_roots if root != repo_root]
+    manifest_roots = _expand_project_code_roots(nested_project_roots or project_roots)
+    if manifest_roots:
+        return manifest_roots
+
+    return [path for path in (repo_root / 'app', repo_root / 'src') if path.is_dir()]
+
+
+def _iter_code_evidence_files(*, repo_root: Path, implemented_stories: list[dict[str, Any]]) -> list[Path]:
+    files: list[Path] = []
+    seen: set[Path] = set()
+    for root in _implementation_code_roots(repo_root=repo_root, implemented_stories=implemented_stories):
+        for dirpath, dirnames, filenames in os.walk(root):
+            dirnames[:] = [name for name in dirnames if name not in _IGNORED_EVIDENCE_DIR_NAMES and not name.startswith('.')]
+            current_root = Path(dirpath)
+            for filename in filenames:
+                file_path = current_root / filename
+                if file_path.suffix not in _SOURCE_EVIDENCE_EXTENSIONS or file_path in seen:
+                    continue
+                files.append(file_path)
+                seen.add(file_path)
+    return sorted(files)
+
+
+def _integration_snapshot_paths(*, repo_root: Path, idea_id: str) -> list[Path]:
+    idea_dir = repo_root / ".devflow" / "ideas" / idea_id
+    paths: list[Path] = []
+    idea_json_path = idea_dir / "idea.json"
+    if idea_json_path.exists():
+        paths.append(idea_json_path)
+    story_sets_dir = idea_dir / "devflow_story_sets"
+    implemented_stories: list[dict[str, Any]] = []
+    if story_sets_dir.exists():
+        for path in sorted(story_sets_dir.rglob("*.json")):
+            if path.name == "manifest.json":
+                continue
+            paths.append(path)
+            try:
+                story_data = json.loads(path.read_text(encoding="utf-8"))
+            except Exception:
+                continue
+            if isinstance(story_data, dict):
+                implemented_stories.append(story_data)
+    paths.extend(_iter_code_evidence_files(repo_root=repo_root, implemented_stories=implemented_stories))
+    ai_docs_dir = repo_root / "ai_docs"
+    if ai_docs_dir.exists():
+        paths.extend(sorted(ai_docs_dir.rglob("*.md")))
+    return paths
+
+
+def _compute_integration_freshness(
+    *,
+    repo_root: Path,
+    idea_id: str,
+    payload_body: dict[str, Any],
+) -> dict[str, Any]:
+    payload_sha256 = _sha256_json(payload_body)
+    repo_files: list[dict[str, str]] = []
+    for path in _integration_snapshot_paths(repo_root=repo_root, idea_id=idea_id):
+        repo_files.append({"path": _relative_repo_path(repo_root=repo_root, path=path), "sha256": _sha256_file(path)})
+    repo_snapshot_sha256 = _sha256_json(repo_files)
+    fingerprint = _sha256_json(
+        {
+            "idea_id": idea_id,
+            "payload_sha256": payload_sha256,
+            "repo_snapshot_sha256": repo_snapshot_sha256,
+        }
+    )
+    return {
+        "fingerprint": fingerprint,
+        "payload_sha256": payload_sha256,
+        "repo_snapshot_sha256": repo_snapshot_sha256,
+    }
+
+
+def _payload_body_without_freshness(payload: dict[str, Any]) -> dict[str, Any]:
+    body = dict(payload)
+    body.pop("freshness", None)
+    return body
+
+
+def _load_resume_metadata(run_dir: Path) -> dict[str, Any] | None:
+    path = run_dir / INTEGRATION_RESUME_METADATA
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _resume_dir_matches_fingerprint(*, run_dir: Path, expected_fingerprint: str | None) -> bool:
+    if not expected_fingerprint:
+        return False
+    metadata = _load_resume_metadata(run_dir)
+    if metadata is None:
+        return False
+    return str(metadata.get("fingerprint") or "") == expected_fingerprint
+
+
+def _write_resume_metadata(run_dir: Path, freshness: dict[str, Any]) -> Path:
+    path = run_dir / INTEGRATION_RESUME_METADATA
+    _write_json(path, freshness)
+    return path
+
+
+def prepare_integration_payload(*, repo_root: Path, idea_id: str) -> Path:
+    """Build and write integration_payload.json for the given idea.
+
+    Scans idea.json, devflow_story_sets, app/src Python files, and ai_docs markdown.
+    Returns the path to the written payload file.
+    """
+    idea_dir = repo_root / '.devflow' / 'ideas' / idea_id
+    idea_json_path = idea_dir / 'idea.json'
+    if not idea_json_path.exists():
+        raise ValueError(f'idea.json not found: {idea_json_path}')
+    implemented_idea = json.loads(idea_json_path.read_text(encoding='utf-8'))
+
+    story_sets_dir = idea_dir / 'devflow_story_sets'
+    implemented_stories: list[dict[str, Any]] = []
+    if story_sets_dir.exists():
+        for story_path in sorted(story_sets_dir.rglob('*.json')):
+            if story_path.name == 'manifest.json':
+                continue
+            try:
+                story_data = json.loads(story_path.read_text(encoding='utf-8'))
+                story_id = str(story_data.get('story_id') or story_data.get('id') or story_path.stem)
+                title = str(story_data.get('title') or story_data.get('name') or story_id)
+                summary = {
+                    'story_id': story_id,
+                    'title': title,
+                    'side_effect_ids': list(story_data.get('side_effect_ids') or []),
+                    'required_planes': list(story_data.get('required_planes') or []),
+                }
+                for key in _STORY_CODE_PATH_KEYS:
+                    if key in story_data:
+                        summary[key] = story_data.get(key)
+                implemented_stories.append(summary)
+            except Exception:
+                pass
+
+    code_evidence: list[dict[str, Any]] = []
+    for code_path in _iter_code_evidence_files(repo_root=repo_root, implemented_stories=implemented_stories):
+        code_evidence.append({'path': _relative_repo_path(repo_root=repo_root, path=code_path), 'side_effect_ids': [], 'interaction_points': []})
+
+    source_docs: list[dict[str, Any]] = []
+    ai_docs_dir = repo_root / 'ai_docs'
+    if ai_docs_dir.exists():
+        for md_path in sorted(ai_docs_dir.rglob('*.md')):
+            try:
+                rel = str(md_path.relative_to(repo_root))
+            except ValueError:
+                rel = str(md_path)
+            source_docs.append({'path': rel})
+
+    payload: dict[str, Any] = {
+        'idea_id': idea_id,
+        'implemented_idea': implemented_idea,
+        'implemented_stories': implemented_stories,
+        'code_evidence': code_evidence,
+        'source_docs': source_docs,
+    }
+    payload['freshness'] = _compute_integration_freshness(
+        repo_root=repo_root,
+        idea_id=idea_id,
+        payload_body=payload,
+    )
+    payload_path = idea_dir / 'integration_payload.json'
+    payload_path.parent.mkdir(parents=True, exist_ok=True)
+    payload_path.write_text(json.dumps(payload, indent=2, sort_keys=True) + '\n', encoding='utf-8')
+    return payload_path
+
+
+def _keychain_get(service: str, account: str) -> str | None:
+    try:
+        proc = subprocess.run(
+            ["security", "find-generic-password", "-s", service, "-a", account, "-w"],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=10,
+        )
+    except Exception:
+        return None
+    if proc.returncode != 0:
+        return None
+    return proc.stdout.strip() or None
+
+
+def _resolve_supabase_rest_config() -> tuple[str, str] | None:
+    if os.environ.get("PYTEST_CURRENT_TEST"):
+        return None
+    url = (
+        os.environ.get("DEVFLOW_SUPABASE_URL")
+        or os.environ.get("SUPABASE_URL")
+        or _keychain_get("Supabase URL", "Clarity")
+    )
+    key = (
+        os.environ.get("DEVFLOW_SUPABASE_SERVICE_KEY")
+        or os.environ.get("SUPABASE_SERVICE_ROLE_KEY")
+        or os.environ.get("SUPABASE_SERVICE_KEY")
+        or _keychain_get("Supabase Service Key", "Clarity")
+    )
+    if not url or not key:
+        return None
+    return url.rstrip("/"), key
+
+
+def _postgrest_request(
+    *,
+    method: str,
+    url: str,
+    key: str,
+    body: Any | None = None,
+    prefer: str | None = None,
+) -> Any:
+    payload = None if body is None else json.dumps(body).encode("utf-8")
+    req = Request(url, data=payload, method=method)
+    req.add_header("apikey", key)
+    req.add_header("Authorization", f"Bearer {key}")
+    if body is not None:
+        req.add_header("Content-Type", "application/json")
+    if prefer:
+        req.add_header("Prefer", prefer)
+    with urlopen(req, timeout=30) as resp:
+        raw = resp.read().decode("utf-8")
+        return json.loads(raw) if raw else None
+
+@dataclass(frozen=True)
+class Stage:
+    node_id: str
+    name: str
+    deps: list[str]
+
+
+@dataclass(frozen=True)
+class IntegrationDagResult:
+    exit_code: int
+    message: str
+    pipeline_dir: Path
+    artifacts: dict[str, str]
+    iterations_used: int
+
+
+CANONICAL_ACTOR_ALLOWED_COMBINATIONS: set[tuple[str, str, str]] = {
+    ("human", "open", "public"),
+    ("human", "organization", "authenticated"),
+    ("human", "organization", "admin"),
+    ("human", "global", "super_user"),
+    ("ai", "organization", "authenticated"),
+    ("ai", "organization", "admin"),
+    ("system", "organization", "authenticated"),
+    ("system", "organization", "admin"),
+    ("system", "global", "super_user"),
+}
+
+
+class CanonicalActor(BaseModel):
+    kind: str
+    scope: str
+    authority: str
+    rationale: str = ""
+
+
+class DeniedActorCandidate(BaseModel):
+    kind: str
+    scope: str
+    authority: str
+    reason: str
+
+
+class SideEffectArtifactItem(BaseModel):
+    id: str
+    summary: str
+    story_ids: list[str] = Field(default_factory=list)
+    rationale: str = ""
+    interaction_points: list[dict[str, Any]] = Field(default_factory=list)
+    needed_interaction_points: list[dict[str, Any]] = Field(default_factory=list)
+    process_sequence: list[str] = Field(default_factory=list)
+    branches: list[dict[str, Any]] = Field(default_factory=list)
+    resulting_artifacts: list[str] = Field(default_factory=list)
+
+
+class SideEffectsArtifact(BaseModel):
+    idea_id: str
+    side_effects: list[SideEffectArtifactItem]
+    alignment_context: dict[str, Any] = Field(default_factory=dict)
+
+
+class ImplicatedUsersArtifact(BaseModel):
+    idea_id: str
+    implicated_users: list[CanonicalActor]
+    denied_candidates: list[DeniedActorCandidate] = Field(default_factory=list)
+
+
+class StoryBackingItem(BaseModel):
+    story_id: str
+    title: str
+
+
+class WorkflowArtifact(BaseModel):
+    workflow_id: str
+    idea_id: str
+    side_effect: dict[str, str]
+    implicated_users: list[dict[str, Any]]
+    story_backing: list[dict[str, Any]] = Field(default_factory=list)
+    code_backing: list[dict[str, Any]] = Field(default_factory=list)
+    source_doc_backing: list[dict[str, Any]] = Field(default_factory=list)
+    interaction_points: list[dict[str, Any]] = Field(default_factory=list)
+    needed_interaction_points: list[dict[str, Any]] = Field(default_factory=list)
+    process_sequence: list[str] = Field(default_factory=list)
+    branches: list[dict[str, Any]] = Field(default_factory=list)
+    resulting_artifacts: list[str] = Field(default_factory=list)
+    mermaid: str | None = None
+
+
+class WorkflowSetArtifact(BaseModel):
+    idea_id: str
+    workflows: list[WorkflowArtifact]
+
+
+class ValidateEnrichFinding(BaseModel):
+    workflow_id: str
+    severity: str
+    summary: str
+    details: list[str] = Field(default_factory=list)
+    blocking: bool = False
+
+
+class ValidateRepairDeltaLedger(BaseModel):
+    verdict_changes: list[str] = Field(default_factory=list)
+    evidence_changes: list[str] = Field(default_factory=list)
+    newly_resolved_seams: list[str] = Field(default_factory=list)
+    contradiction_citations: list[str] = Field(default_factory=list)
+
+
+class IdeaAcceptanceCoverageEntry(BaseModel):
+    criterion_index: int
+    criterion: str
+    verdict: str
+    proof_summary: str = ""
+    story_ids: list[str] = Field(default_factory=list)
+    workflow_ids: list[str] = Field(default_factory=list)
+    side_effect_ids: list[str] = Field(default_factory=list)
+    evidence_refs: list[str] = Field(default_factory=list)
+    gaps: list[str] = Field(default_factory=list)
+    missing_seams: list[str] = Field(default_factory=list)
+
+
+class IdeaAcceptanceCoverageArtifact(BaseModel):
+    idea_id: str
+    summary: str
+    criteria: list[IdeaAcceptanceCoverageEntry] = Field(default_factory=list)
+    protected_sections: list[dict[str, Any]] = Field(default_factory=list)
+    do_not_touch: list[str] = Field(default_factory=list)
+    execution_lineage: dict[str, Any] | None = None
+
+
+class VegIdeaAcceptanceBuilderArtifact(BaseModel):
+    idea_id: str
+    summary: str
+    enriched_workflows: list[WorkflowArtifact]
+    findings: list[ValidateEnrichFinding] = Field(default_factory=list)
+    idea_acceptance_coverage: IdeaAcceptanceCoverageArtifact
+    repair_delta_ledger: ValidateRepairDeltaLedger | None = None
+
+
+class HarnessSelection(BaseModel):
+    harness_kind: str
+    interaction_point_ref: str
+    interaction_point_kind: str
+    rationale: str
+    gap_explicit: bool = False
+
+
+class IntegrationAssertion(BaseModel):
+    assertion_id: str
+    summary: str
+    evidence_anchor: str = ""
+
+
+class RedWorkflowPackage(BaseModel):
+    workflow_id: str
+    side_effect_id: str
+    status: str
+    harness_selection: HarnessSelection
+    failing_artifacts: list[dict[str, Any]] = Field(default_factory=list)
+    expected_assertions: list[IntegrationAssertion] = Field(default_factory=list)
+    implicated_user_routes: list[dict[str, Any]] = Field(default_factory=list)
+    gap_notes: list[str] = Field(default_factory=list)
+
+
+class RedArtifact(BaseModel):
+    idea_id: str
+    packages: list[RedWorkflowPackage]
+    summary: str
+
+
+class RedReviewFinding(BaseModel):
+    workflow_id: str
+    verdict: str
+    findings: list[str] = Field(default_factory=list)
+    repair_directions: list[str] = Field(default_factory=list)
+
+
+class RedReviewArtifact(BaseModel):
+    idea_id: str
+    summary: str
+    reviewed_packages: list[RedWorkflowPackage]
+    findings: list[RedReviewFinding]
+
+
+class GreenWorkflowPackage(BaseModel):
+    workflow_id: str
+    side_effect_id: str
+    implementation_changes: list[dict[str, Any]] = Field(default_factory=list)
+    harness_support_changes: list[dict[str, Any]] = Field(default_factory=list)
+    passing_strategy: list[str] = Field(default_factory=list)
+    proof_artifacts: list[dict[str, Any]] = Field(default_factory=list)
+
+
+class GreenArtifact(BaseModel):
+    idea_id: str
+    summary: str
+    packages: list[GreenWorkflowPackage]
+
+
+class GreenEnrichWorkflowPackage(BaseModel):
+    workflow_id: str
+    strengthened_assertions: list[IntegrationAssertion] = Field(default_factory=list)
+    observability_improvements: list[dict[str, Any]] = Field(default_factory=list)
+    brittleness_reductions: list[str] = Field(default_factory=list)
+
+
+class GreenEnrichArtifact(BaseModel):
+    idea_id: str
+    summary: str
+    packages: list[GreenEnrichWorkflowPackage]
+
+
+class CommitWorkflowPackage(BaseModel):
+    workflow_id: str
+    side_effect_id: str
+    included_artifacts: list[str] = Field(default_factory=list)
+    traceability: dict[str, Any] = Field(default_factory=dict)
+
+
+class CommitArtifact(BaseModel):
+    idea_id: str
+    summary: str
+    packages: list[CommitWorkflowPackage]
+    package_manifest: dict[str, Any] = Field(default_factory=dict)
+
+
+class FilePatch(BaseModel):
+    file_path: str          # relative to repo_root
+    content: str            # full file content (overwrite)
+    rationale: str = ""     # why this patch was needed
+
+
+class CodeRepairArtifact(BaseModel):
+    patches: list[FilePatch] = Field(default_factory=list)
+    updated_workflows: list[WorkflowArtifact] = Field(default_factory=list)
+    repair_summary: str = ""
+    unresolvable_failures: list[str] = Field(default_factory=list)
+
+
+def _workflow_side_effect_map(side_effects_artifact: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    return {
+        str(item.get("id") or ""): dict(item)
+        for item in (side_effects_artifact.get("side_effects") or [])
+        if str(item.get("id") or "")
+    }
+
+
+def _ground_workflow_in_side_effect(*, workflow: dict[str, Any], side_effects_artifact: dict[str, Any]) -> dict[str, Any]:
+    grounded = dict(workflow)
+    side_effect_id = str(grounded.get("side_effect", {}).get("id") or "")
+    side_effect = _workflow_side_effect_map(side_effects_artifact).get(side_effect_id)
+    if side_effect is None:
+        return grounded
+    grounded["interaction_points"] = list(side_effect.get("interaction_points") or [])
+    grounded["needed_interaction_points"] = list(side_effect.get("needed_interaction_points") or [])
+    if not grounded.get("process_sequence"):
+        grounded["process_sequence"] = list(side_effect.get("process_sequence") or [])
+    if not grounded.get("resulting_artifacts"):
+        grounded["resulting_artifacts"] = list(side_effect.get("resulting_artifacts") or [])
+    return grounded
+
+
+def _ground_workflows_in_side_effects(*, workflows: list[dict[str, Any]], side_effects_artifact: dict[str, Any]) -> list[dict[str, Any]]:
+    return [
+        _ground_workflow_in_side_effect(workflow=workflow, side_effects_artifact=side_effects_artifact)
+        for workflow in workflows
+    ]
+
+
+def _run_veg_idea_acceptance_builder(
+    *,
+    repo_root: Path,
+    pipeline_dir: Path,
+    idea_id: str,
+    implemented_idea: dict[str, Any] | None,
+    implemented_stories: list[dict[str, Any]] | None,
+    side_effects_artifact: dict[str, Any],
+    implicated_users_artifact: dict[str, Any],
+    workflows: list[dict[str, Any]],
+    code_evidence: list[dict[str, Any]] | None,
+    source_docs: list[dict[str, Any]] | None,
+    node_id: str,
+) -> VegIdeaAcceptanceBuilderArtifact:
+    artifact, envelope = integration_agentic.run_integration_agent_step(
+        repo_root=repo_root,
+        stage_name="build_idea_acceptance_coverage",
+        output_model=VegIdeaAcceptanceBuilderArtifact,
+        context_payload={
+            "idea_id": idea_id,
+            "implemented_idea": implemented_idea or {},
+            "implemented_stories": list(implemented_stories or []),
+            "side_effects_artifact": side_effects_artifact,
+            "implicated_users_artifact": implicated_users_artifact,
+            "workflows": workflows,
+            "code_evidence": list(code_evidence or []),
+            "source_docs": list(source_docs or []),
+        },
+        guidance=[],
+        timeout_seconds=_integration_agent_timeout_seconds(),
+    )
+    integration_agentic.persist_agent_run(pipeline_root=pipeline_dir, node_id=node_id, envelope=envelope)
+    return artifact
+
+
+def default_integration_stages() -> list[Stage]:
+    return [
+        Stage("resolve_side_effects", "ResolveSideEffectsAndImplicatedUsers", []),
+        Stage("write_workflows", "WriteWorkflowPerSideEffect", ["resolve_side_effects"]),
+        Stage("veg", "VEGHybridValidateEnrichGate", ["write_workflows"]),
+        Stage("red", "Red", ["veg"]),
+        Stage("redreview", "RedReview", ["red"]),
+        Stage("green", "Green", ["redreview"]),
+        Stage("greenenrich", "GreenEnrich", ["green"]),
+        Stage("commit", "Commit", ["greenenrich"]),
+    ]
+
+
+def render_stage_plan(stages: list[Stage]) -> str:
+    return "\n".join(
+        f"{stage.node_id}  ({stage.name})  deps=[{','.join(stage.deps) if stage.deps else '-'}]"
+        for stage in stages
+    ) + "\n"
+
+
+def _write_json(path: Path, payload: dict[str, Any] | list[Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def _slug(value: str) -> str:
+    text = re.sub(r"[^a-z0-9]+", "_", value.lower()).strip("_")
+    return text or "item"
+
+
+def _integration_agent_timeout_seconds() -> int:
+    raw = os.environ.get("DEVFLOW_INTEGRATION_AGENT_TIMEOUT")
+    if not raw:
+        return 1800
+    try:
+        value = int(raw)
+    except ValueError:
+        return 1800
+    return value if value > 0 else 1800
+
+
+def _preferred_harness_for_interaction_point(point: dict[str, Any]) -> str:
+    kind = str(point.get("kind") or "").strip().lower()
+    # Fallback: enriched interaction points may use "type" instead of "kind"
+    if not kind:
+        kind = _normalize_interaction_type(str(point.get("type") or "").strip().lower())
+    if kind == "ui":
+        return "playwright"
+    if kind == "endpoint":
+        return "endpoint_harness"
+    if kind == "cli":
+        return "cli_harness"
+    if kind == "artifact":
+        return "artifact_probe"
+    if kind in {"background", "event", "queue", "job"}:
+        return "background_observer"
+    return "integration_harness"
+
+
+def _normalize_interaction_type(raw_type: str) -> str:
+    """Map enriched interaction-point ``type`` values to canonical ``kind`` values.
+
+    Enrichment agents generate specific type strings (``api_boundary``,
+    ``health_check``, …) that don't match the narrow ``kind`` vocabulary used by
+    ``_preferred_harness_for_interaction_point``.  We first try an exact lookup,
+    then fall back to keyword-based family matching so newly-invented type
+    strings still resolve correctly.
+    """
+    _TYPE_TO_KIND: dict[str, str] = {
+        "api_endpoint": "endpoint",
+        "http_endpoint": "endpoint",
+        "rest_endpoint": "endpoint",
+        "graphql_endpoint": "endpoint",
+        "health_check": "endpoint",
+        "webhook": "endpoint",
+        "websocket": "endpoint",
+        "api_boundary": "endpoint",
+        "auth_boundary": "endpoint",
+        "network_boundary": "endpoint",
+        "cli_command": "cli",
+        "cli_entrypoint": "cli",
+        "ui_component": "ui",
+        "ui_page": "ui",
+        "browser": "ui",
+        "file_artifact": "artifact",
+        "artifact_output": "artifact",
+        "background_job": "background",
+        "cron_job": "background",
+        "queue_consumer": "queue",
+        "event_handler": "event",
+    }
+    exact = _TYPE_TO_KIND.get(raw_type)
+    if exact is not None:
+        return exact
+    # Keyword-family fallback for types not in the exact map
+    _FAMILY_KEYWORDS: list[tuple[tuple[str, ...], str]] = [
+        (("endpoint", "api", "http", "rest", "graphql", "health", "webhook", "websocket", "boundary"), "endpoint"),
+        (("cli",), "cli"),
+        (("ui", "browser", "page"), "ui"),
+        (("artifact", "file"), "artifact"),
+        (("background", "cron", "job"), "background"),
+        (("queue",), "queue"),
+        (("event",), "event"),
+    ]
+    for keywords, kind in _FAMILY_KEYWORDS:
+        if any(kw in raw_type for kw in keywords):
+            return kind
+    return raw_type
+
+
+def _load_code_evidence_for_workflows(
+    *,
+    workflows: list[dict[str, Any]],
+    code_evidence: list[dict[str, Any]] | None,
+    repo_root: Path,
+    max_files: int = 20,
+) -> list[dict[str, Any]]:
+    """Load actual file contents for code evidence relevant to the failing workflows."""
+    if not code_evidence:
+        return []
+    # Collect all side_effect_ids referenced by the failing workflows
+    relevant_se_ids: set[str] = set()
+    for wf in workflows:
+        se = wf.get("side_effect") or {}
+        if se.get("id"):
+            relevant_se_ids.add(str(se["id"]))
+
+    loaded: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for item in code_evidence:
+        if len(loaded) >= max_files:
+            break
+        item_se_ids = set(str(x) for x in (item.get("side_effect_ids") or []))
+        if relevant_se_ids and not relevant_se_ids.intersection(item_se_ids) and item_se_ids:
+            continue  # not relevant to these workflows
+        path_str = str(item.get("path") or "")
+        if not path_str or path_str in seen:
+            continue
+        seen.add(path_str)
+        full_path = repo_root / path_str
+        if full_path.exists():
+            try:
+                content = full_path.read_text(encoding="utf-8", errors="replace")
+                loaded.append({"path": path_str, "content": content[:8000]})  # cap per file
+            except Exception:
+                loaded.append({"path": path_str, "content": "(unreadable)"})
+        else:
+            loaded.append({"path": path_str, "content": "(file not found)"})
+    return loaded
+
+
+def _build_post_integration_playwright_request(
+    *,
+    idea_id: str,
+    trigger_run_id: str | None,
+    workflows: list[dict[str, Any]],
+    red_artifact: dict[str, Any],
+) -> dict[str, Any]:
+    red_packages = {
+        str(package.get("workflow_id") or ""): package
+        for package in red_artifact.get("packages") or []
+        if isinstance(package, dict)
+    }
+    workflow_requests: list[dict[str, Any]] = []
+    for workflow in workflows:
+        workflow_id = str(workflow.get("workflow_id") or "")
+        package = red_packages.get(workflow_id) or {}
+        harness = package.get("harness_selection") or {}
+        interaction_points = list(workflow.get("interaction_points") or [])
+        ui_points = [
+            point for point in interaction_points
+            if _preferred_harness_for_interaction_point(point) == "playwright"
+        ]
+        harness_kind = str(harness.get("harness_kind") or "")
+        requires_playwright = bool(ui_points or harness_kind == "playwright")
+        workflow_requests.append({
+            "workflow_id": workflow_id,
+            "side_effect_id": str(
+                workflow.get("side_effect", {}).get("id")
+                or package.get("side_effect_id")
+                or ""
+            ),
+            "requires_playwright": requires_playwright,
+            "harness_kind": harness_kind or ("playwright" if requires_playwright else "integration_harness"),
+            "interaction_points": ui_points if ui_points else interaction_points[:1],
+            "story_backing": list(workflow.get("story_backing") or []),
+            "required_proof": [
+                "real browser execution for visible UI controls",
+                "assert observable business results, not only clicks or page load",
+                (
+                    "verify role, status, filter, reset, and cancellation behavior "
+                    "where the workflow exposes those controls"
+                ),
+                "fail early when expected seed records are missing",
+            ] if requires_playwright else [],
+        })
+
+    required_workflows = [item for item in workflow_requests if item["requires_playwright"]]
+    return {
+        "kind": "post_integration_playwright_request.v1",
+        "idea_id": idea_id,
+        "trigger_run_id": trigger_run_id,
+        "status": "required" if required_workflows else "not_required",
+        "process": "post_integration_playwright_dag",
+        "workflow_requests": workflow_requests,
+        "required_workflow_ids": [item["workflow_id"] for item in required_workflows],
+        "expected_artifacts": [
+            "app_route_inventory.json",
+            "ui_element_ledger.json",
+            "playwright_coverage_verifier.json",
+            "playwright_generation_plan.json",
+            "generated_playwright_specs_manifest.json",
+            "workflow_preview_manifest.json",
+        ],
+        "blocking_gates": [
+            (
+                "ui_element_ledger has no uncovered mutation, navigation, destructive, "
+                "mode-toggle, filter, sort, search, or form-control rows without a "
+                "disabled/deferred rationale"
+            ),
+            "playwright_coverage_verifier.passed is true",
+            "generated specs assert business outcomes on the correct proof plane for each workflow",
+            (
+                "video/preview capture is produced only after passing E2E proof and is "
+                "not accepted as a substitute for assertions"
+            ),
+        ],
+        "worker_handoff": {
+            "queue_type": "post_integration_playwright",
+            "run_after": "successful integration queue drain with no active recovery",
+            "current_artifact_dir": ".devflow/post_integration_playwright/current",
+        },
+    }
+
+
+class IntegrationDagEvent(BaseModel):
+    repo_root: str
+    idea_id: str
+    implemented_idea: dict[str, Any]
+    implemented_stories: list[dict[str, Any]] = Field(default_factory=list)
+    code_evidence: list[dict[str, Any]] = Field(default_factory=list)
+    source_docs: list[dict[str, Any]] = Field(default_factory=list)
+    pipeline_dir: str
+    prior_run_dir: str | None = None
+    resume_freshness: dict[str, Any] = Field(default_factory=dict)
+    project_id: str | None = None
+    dag_run_id: str | None = None
+
+
+def _integration_dfs_progress(task_context: TaskContext, summary: str) -> None:
+    """Publish a progress update to DFS (devflow_state) for the current integration run."""
+    project_id = task_context.metadata.get("project_id")
+    dag_run_id = task_context.metadata.get("dag_run_id")
+    idea_id = getattr(getattr(task_context, "event", None), "idea_id", None)
+    if not project_id:
+        return
+    try:
+        publish_devflow_state(
+            project_id=project_id,
+            run_id=dag_run_id,
+            current_state="running",
+            current_status="processing",
+            run_summary=summary,
+            display="project",
+            display_path=f"idea:{idea_id}" if idea_id else None,
+        )
+    except Exception:
+        return
+
+
+def _integration_root(repo_root: Path, idea_id: str) -> Path:
+    return get_idea_paths(repo_root, idea_id=idea_id).idea_dir / "integration"
+
+
+def _integration_current_dir(repo_root: Path, idea_id: str) -> Path:
+    return _integration_root(repo_root, idea_id) / "current"
+
+
+def _integration_runs_dir(repo_root: Path, idea_id: str) -> Path:
+    return _integration_root(repo_root, idea_id) / "runs"
+
+
+def _legacy_integration_runs_dir(repo_root: Path, idea_id: str) -> Path:
+    return get_idea_paths(repo_root, idea_id=idea_id).idea_dir / "pipelines" / "integration_dag"
+
+
+def _write_integration_artifact(*, repo_root: Path, idea_id: str, pipeline_dir: Path, filename: str, data: dict[str, Any]) -> tuple[Path, Path]:
+    run_path = pipeline_dir / filename
+    current_dir = _integration_current_dir(repo_root, idea_id)
+    current_dir.mkdir(parents=True, exist_ok=True)
+    current_path = current_dir / filename
+    _write_json(run_path, data)
+    _write_json(current_path, data)
+    return run_path, current_path
+
+
+def _invalidate_integration_current_from_stage(*, current_dir: Path, stage: str) -> None:
+    ordered: dict[str, list[str]] = {
+        "resolve": [
+            "side_effects.json",
+            "implicated_users.json",
+            "workflow_inventory.json",
+            "validation_gate.json",
+            "validation_gate_agentic_review.json",
+            "idea_acceptance_coverage.json",
+            "validation_repair_clusters.json",
+            "red_package.json",
+            "red_validation.json",
+            "red_review.json",
+            "green_package.json",
+            "green_enrich.json",
+            "commit_package.json",
+        ],
+        "write_workflows": [
+            "workflow_inventory.json",
+            "validation_gate.json",
+            "validation_gate_agentic_review.json",
+            "idea_acceptance_coverage.json",
+            "validation_repair_clusters.json",
+            "red_package.json",
+            "red_validation.json",
+            "red_review.json",
+            "green_package.json",
+            "green_enrich.json",
+            "commit_package.json",
+        ],
+        "validate": [
+            "validation_gate.json",
+            "validation_gate_agentic_review.json",
+            "idea_acceptance_coverage.json",
+            "validation_repair_clusters.json",
+            "red_package.json",
+            "red_validation.json",
+            "red_review.json",
+            "green_package.json",
+            "green_enrich.json",
+            "commit_package.json",
+        ],
+        "red": [
+            "red_package.json",
+            "red_validation.json",
+            "red_review.json",
+            "green_package.json",
+            "green_enrich.json",
+            "commit_package.json",
+        ],
+        "red_review": [
+            "red_review.json",
+            "green_package.json",
+            "green_enrich.json",
+            "commit_package.json",
+        ],
+        "green": [
+            "green_package.json",
+            "green_enrich.json",
+            "commit_package.json",
+        ],
+        "green_enrich": [
+            "green_enrich.json",
+            "commit_package.json",
+        ],
+        "commit": ["commit_package.json"],
+    }
+    targets = ordered.get(stage, [])
+    for name in targets:
+        path = current_dir / name
+        if path.exists():
+            path.unlink()
+    if stage in {"resolve", "write_workflows"}:
+        for path in current_dir.glob("workflow_*.json"):
+            if path.name != "workflow_inventory.json":
+                path.unlink()
+
+
+def _current_dir_from_task(task_context: TaskContext) -> Path:
+    current_dir = task_context.metadata.get("current_dir")
+    if current_dir:
+        return Path(current_dir)
+    event = task_context.event
+    return _integration_current_dir(Path(event.repo_root), event.idea_id)
+
+
+def _read_resume_artifact(task_context: TaskContext, filename: str) -> tuple[dict[str, Any] | None, Path | None]:
+    event = task_context.event
+    repo_root = Path(event.repo_root)
+    current_dir = _integration_current_dir(repo_root, event.idea_id)
+    current_path = current_dir / filename
+    expected_fingerprint = str(task_context.metadata.get("resume_fingerprint") or "") or None
+    if current_path.exists() and _resume_dir_matches_fingerprint(run_dir=current_dir, expected_fingerprint=expected_fingerprint):
+        try:
+            return json.loads(current_path.read_text(encoding="utf-8")), current_path
+        except Exception:
+            pass
+    prior_str = task_context.metadata.get("prior_run_dir")
+    if prior_str:
+        prior_dir = Path(prior_str)
+        prior_path = prior_dir / filename
+        if prior_path.exists() and _resume_dir_matches_fingerprint(run_dir=prior_dir, expected_fingerprint=expected_fingerprint):
+            try:
+                return json.loads(prior_path.read_text(encoding="utf-8")), prior_path
+            except Exception:
+                pass
+    return None, None
+
+
+def _try_load_prior_artifact(
+    task_context: TaskContext,
+    *filenames: str,
+    validity_check: _Callable[[dict[str, Any]], bool] | None = None,
+) -> dict[str, Any] | None:
+    """Attempt to load a prior run artifact for checkpoint/resume.
+
+    Returns the parsed primary artifact (first filename) when all files exist
+    and the optional validity_check passes; otherwise returns None.
+    """
+    if task_context.metadata.get("resume_aborted"):
+        return None
+    loaded: list[tuple[dict[str, Any], Path]] = []
+    for fname in filenames:
+        data, path = _read_resume_artifact(task_context, fname)
+        if data is None or path is None:
+            return None
+        loaded.append((data, path))
+    primary = loaded[0][0]
+    if validity_check is not None and not validity_check(primary):
+        return None
+    return primary
+
+
+def _abort_resume(task_context: TaskContext) -> None:
+    """Mark resume as aborted so all downstream nodes re-run."""
+    task_context.metadata["resume_aborted"] = True
+
+
+def _score_prior_run_dir(run_dir: Path, *, expected_fingerprint: str | None = None) -> tuple[int, float]:
+    """Prefer the most complete reusable prior integration run, not newest mtime alone."""
+    if not _resume_dir_matches_fingerprint(run_dir=run_dir, expected_fingerprint=expected_fingerprint):
+        return (0, run_dir.stat().st_mtime)
+    score = 0
+    try:
+        inventory_path = run_dir / "workflow_inventory.json"
+        if inventory_path.exists():
+            inventory = json.loads(inventory_path.read_text(encoding="utf-8"))
+            side_effect_ids = [str(sid) for sid in (inventory.get("side_effect_ids") or []) if str(sid)]
+            workflow_files = [run_dir / f"workflow_{_slug(se_id)}.json" for se_id in side_effect_ids]
+            if side_effect_ids and all(path.exists() for path in workflow_files):
+                score = max(score, 1)
+        gate_path = run_dir / "validation_gate.json"
+        if gate_path.exists():
+            gate = json.loads(gate_path.read_text(encoding="utf-8"))
+            if bool(gate.get("passed")) or bool(gate.get("structural_only")):
+                score = max(score, 2)
+        red_validation_path = run_dir / "red_validation.json"
+        if (run_dir / "red_package.json").exists() and red_validation_path.exists():
+            red_validation = json.loads(red_validation_path.read_text(encoding="utf-8"))
+            if bool(red_validation.get("passed")):
+                score = max(score, 3)
+        red_review_path = run_dir / "red_review.json"
+        if red_review_path.exists():
+            red_review = json.loads(red_review_path.read_text(encoding="utf-8"))
+            if bool(red_review.get("agentic_review_clear")):
+                score = max(score, 4)
+        if (run_dir / "green_package.json").exists():
+            score = max(score, 5)
+        if (run_dir / "green_enrich.json").exists():
+            score = max(score, 6)
+        if (run_dir / "commit_package.json").exists():
+            score = max(score, 7)
+    except Exception:
+        score = 0
+    return (score, run_dir.stat().st_mtime)
+
+
+def _select_prior_run_dir(
+    runs_parent: Path,
+    current_pipeline_dir: Path,
+    fallback_runs_parent: Path | None = None,
+    *,
+    expected_fingerprint: str | None = None,
+) -> Path | None:
+    candidates = [d for d in runs_parent.iterdir() if d.is_dir() and d != current_pipeline_dir] if runs_parent.exists() else []
+    if fallback_runs_parent is not None and fallback_runs_parent.exists():
+        candidates.extend(d for d in fallback_runs_parent.iterdir() if d.is_dir() and d != current_pipeline_dir)
+    if not candidates:
+        return None
+    scored = [
+        (run_dir, *_score_prior_run_dir(run_dir, expected_fingerprint=expected_fingerprint))
+        for run_dir in candidates
+    ]
+    usable = [item for item in scored if item[1] > 0]
+    if not usable:
+        return None
+    return max(usable, key=lambda item: (item[1], item[2]))[0]
+
+
+class LoadIntegrationContextNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        event = task_context.event
+        pipeline_dir = Path(event.pipeline_dir)
+        current_dir = _integration_current_dir(Path(event.repo_root), event.idea_id)
+        current_dir.mkdir(parents=True, exist_ok=True)
+        pipeline_dir.mkdir(parents=True, exist_ok=True)
+        task_context.metadata["pipeline_dir"] = str(pipeline_dir)
+        task_context.metadata["current_dir"] = str(current_dir)
+        task_context.metadata["artifacts"] = {}
+        prior_run_dir = getattr(event, "prior_run_dir", None)
+        task_context.metadata["prior_run_dir"] = prior_run_dir
+        task_context.metadata["resume_aborted"] = False
+        task_context.metadata["project_id"] = getattr(event, "project_id", None)
+        task_context.metadata["dag_run_id"] = getattr(event, "dag_run_id", None)
+        freshness = dict(getattr(event, "resume_freshness", None) or {})
+        task_context.metadata["resume_fingerprint"] = str(freshness.get("fingerprint") or "")
+        if not _resume_dir_matches_fingerprint(
+            run_dir=current_dir,
+            expected_fingerprint=task_context.metadata["resume_fingerprint"],
+        ):
+            _invalidate_integration_current_from_stage(current_dir=current_dir, stage="resolve")
+        _write_resume_metadata(pipeline_dir, freshness)
+        _write_resume_metadata(current_dir, freshness)
+        self.save_output({"pipeline_dir": str(pipeline_dir)})
+        return task_context
+
+
+class ResolveSideEffectsAndImplicatedUsersNode(AgentNode):
+    def get_agent_config(self) -> AgentConfig:
+        return AgentConfig(
+            instructions=load_integration_node_instruction("resolve"),
+            output_type=SideEffectsArtifact,
+        )
+
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        # -- checkpoint/resume --
+        prior_se = _try_load_prior_artifact(task_context, "side_effects.json", "implicated_users.json")
+        if prior_se is not None:
+            prior_users, prior_users_path = _read_resume_artifact(task_context, "implicated_users.json")
+            side_effects_path = _current_dir_from_task(task_context) / "side_effects.json"
+            implied_path = prior_users_path or (_current_dir_from_task(task_context) / "implicated_users.json")
+            task_context.metadata["side_effects_artifact"] = prior_se
+            task_context.metadata["implicated_users_artifact"] = prior_users or {}
+            task_context.metadata["artifacts"].update({
+                "side_effects": str(side_effects_path),
+                "implicated_users": str(implied_path),
+            })
+            self.save_output({"resumed_from": str(_current_dir_from_task(task_context)), "skipped_llm": True})
+            return task_context
+        _abort_resume(task_context)
+        # -- end checkpoint/resume --
+
+        _integration_dfs_progress(task_context, "Resolving side effects")
+
+        event = task_context.event
+        repo_root = Path(event.repo_root)
+        pipeline_dir = Path(task_context.metadata["pipeline_dir"])
+        _invalidate_integration_current_from_stage(current_dir=_current_dir_from_task(task_context), stage="resolve")
+        side_effects_artifact, side_effects_envelope = integration_agentic.run_integration_agent_step(
+            repo_root=repo_root,
+            stage_name="resolve_side_effects",
+            output_model=SideEffectsArtifact,
+            context_payload={
+                "idea_id": event.idea_id,
+                "implemented_idea": event.implemented_idea,
+                "implemented_stories": event.implemented_stories,
+                "code_evidence": event.code_evidence,
+                "source_docs": event.source_docs,
+                "canonical_actor_allowed_combinations": sorted(list(CANONICAL_ACTOR_ALLOWED_COMBINATIONS)),
+            },
+            guidance=[],
+            timeout_seconds=_integration_agent_timeout_seconds(),
+        )
+        _integration_dfs_progress(task_context, "Resolving users")
+        implicated_users_artifact, users_envelope = integration_agentic.run_integration_agent_step(
+            repo_root=repo_root,
+            stage_name="resolve_implicated_users",
+            output_model=ImplicatedUsersArtifact,
+            context_payload={
+                "idea_id": event.idea_id,
+                "implemented_idea": event.implemented_idea,
+                "implemented_stories": event.implemented_stories,
+                "code_evidence": event.code_evidence,
+                "source_docs": event.source_docs,
+                "canonical_actor_allowed_combinations": sorted(list(CANONICAL_ACTOR_ALLOWED_COMBINATIONS)),
+            },
+            guidance=[],
+            timeout_seconds=_integration_agent_timeout_seconds(),
+        )
+        integration_agentic.persist_agent_run(pipeline_root=pipeline_dir, node_id="resolve_side_effects", envelope=side_effects_envelope)
+        integration_agentic.persist_agent_run(pipeline_root=pipeline_dir, node_id="resolve_implicated_users", envelope=users_envelope)
+
+        side_effects_path, _ = _write_integration_artifact(
+            repo_root=repo_root,
+            idea_id=event.idea_id,
+            pipeline_dir=pipeline_dir,
+            filename="side_effects.json",
+            data=side_effects_artifact.model_dump(),
+        )
+        implicated_users_path, _ = _write_integration_artifact(
+            repo_root=repo_root,
+            idea_id=event.idea_id,
+            pipeline_dir=pipeline_dir,
+            filename="implicated_users.json",
+            data=implicated_users_artifact.model_dump(),
+        )
+        task_context.metadata["side_effects_artifact"] = side_effects_artifact.model_dump()
+        task_context.metadata["implicated_users_artifact"] = implicated_users_artifact.model_dump()
+        task_context.metadata["artifacts"].update({
+            "side_effects": str(side_effects_path),
+            "implicated_users": str(implicated_users_path),
+        })
+        self.save_output({
+            "side_effects_ref": str(side_effects_path),
+            "implicated_users_ref": str(implicated_users_path),
+        })
+        return task_context
+
+
+class WriteWorkflowPerSideEffectNode(AgentNode):
+    def get_agent_config(self) -> AgentConfig:
+        return AgentConfig(
+            instructions=load_integration_node_instruction("write_workflows"),
+            output_type=WorkflowSetArtifact,
+        )
+
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        # -- checkpoint/resume --
+        prior_inv = _try_load_prior_artifact(task_context, "workflow_inventory.json")
+        if prior_inv is not None:
+            current_dir = _current_dir_from_task(task_context)
+            prior_se_ids = set(str(s) for s in (prior_inv.get("side_effect_ids") or []))
+            current_se_ids = {
+                str(item.get("id") or "")
+                for item in (task_context.metadata.get("side_effects_artifact") or {}).get("side_effects") or []
+                if str(item.get("id") or "")
+            }
+            prior_workflow_files = [current_dir / f"workflow_{_slug(str(se_id))}.json" for se_id in prior_se_ids]
+            if prior_se_ids == current_se_ids and all(f.exists() for f in prior_workflow_files):
+                workflows = []
+                workflow_paths: dict[str, str] = {}
+                for se_id in prior_se_ids:
+                    wf_path = current_dir / f"workflow_{_slug(str(se_id))}.json"
+                    wf = json.loads(wf_path.read_text(encoding="utf-8"))
+                    workflows.append(wf)
+                    workflow_paths[f"workflow_{_slug(str(se_id))}"] = str(wf_path)
+                task_context.metadata["workflows"] = workflows
+                task_context.metadata["artifacts"]["workflow_inventory"] = str(current_dir / "workflow_inventory.json")
+                task_context.metadata["artifacts"].update(workflow_paths)
+                self.save_output({"resumed_from": str(current_dir), "skipped_llm": True, "workflow_count": len(workflows)})
+                return task_context
+        _abort_resume(task_context)
+        # -- end checkpoint/resume --
+
+        _integration_dfs_progress(task_context, "Writing workflows")
+
+        event = task_context.event
+        repo_root = Path(event.repo_root)
+        pipeline_dir = Path(task_context.metadata["pipeline_dir"])
+        _invalidate_integration_current_from_stage(current_dir=_current_dir_from_task(task_context), stage="write_workflows")
+        artifact, envelope = integration_agentic.run_integration_agent_step(
+            repo_root=repo_root,
+            stage_name="write_workflows",
+            output_model=WorkflowSetArtifact,
+            context_payload={
+                "idea_id": event.idea_id,
+                "side_effects_artifact": task_context.metadata["side_effects_artifact"],
+                "implicated_users_artifact": task_context.metadata["implicated_users_artifact"],
+                "implemented_stories": event.implemented_stories,
+                "code_evidence": event.code_evidence,
+                "source_docs": event.source_docs,
+            },
+            guidance=[],
+            timeout_seconds=_integration_agent_timeout_seconds(),
+        )
+        integration_agentic.persist_agent_run(pipeline_root=pipeline_dir, node_id="write_workflows", envelope=envelope)
+
+        workflows = _ground_workflows_in_side_effects(
+            workflows=[item.model_dump() for item in artifact.workflows],
+            side_effects_artifact=task_context.metadata["side_effects_artifact"],
+        )
+        workflow_inventory = {
+            "idea_id": event.idea_id,
+            "workflow_ids": [workflow["workflow_id"] for workflow in workflows],
+            "side_effect_ids": [item.get("id") for item in task_context.metadata["side_effects_artifact"].get("side_effects") or []],
+            "downstream_stages": [stage.node_id for stage in default_integration_stages()[2:]],
+        }
+        workflow_inventory_path, _ = _write_integration_artifact(
+            repo_root=repo_root,
+            idea_id=event.idea_id,
+            pipeline_dir=pipeline_dir,
+            filename="workflow_inventory.json",
+            data=workflow_inventory,
+        )
+        task_context.metadata["artifacts"]["workflow_inventory"] = str(workflow_inventory_path)
+
+        workflow_paths: dict[str, str] = {}
+        for workflow in workflows:
+            path, _ = _write_integration_artifact(
+                repo_root=repo_root,
+                idea_id=event.idea_id,
+                pipeline_dir=pipeline_dir,
+                filename=f"workflow_{_slug(str(workflow['side_effect']['id']))}.json",
+                data=workflow,
+            )
+            workflow_paths[workflow["workflow_id"]] = str(path)
+        task_context.metadata["workflows"] = workflows
+        task_context.metadata["artifacts"].update(workflow_paths)
+        self.save_output({"workflow_inventory_ref": str(workflow_inventory_path), "workflow_count": len(workflows)})
+        return task_context
+
+
+class VegNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        prior_gate = _try_load_prior_artifact(
+            task_context,
+            "validation_gate.json",
+            "validation_gate_agentic_review.json",
+            "idea_acceptance_coverage.json",
+            "idea_acceptance_coverage.json",
+            validity_check=lambda d: bool(d.get("passed")) or bool(d.get("structural_only")),
+        )
+        if prior_gate is not None:
+            current_dir = _current_dir_from_task(task_context)
+            review_payload, review_path = _read_resume_artifact(task_context, "validation_gate_agentic_review.json")
+            coverage_payload, coverage_path = _read_resume_artifact(task_context, "idea_acceptance_coverage.json")
+            cluster_payload, cluster_path = _read_resume_artifact(task_context, "validation_repair_clusters.json")
+            task_context.metadata["validation_report"] = prior_gate
+            task_context.metadata["iterations_used"] = prior_gate.get("iterations_used", 1)
+            task_context.metadata["builder_review"] = review_payload or {}
+            task_context.metadata["idea_acceptance_coverage"] = coverage_payload or {}
+            task_context.metadata["workflows"] = _ground_workflows_in_side_effects(
+                workflows=list((review_payload or {}).get("enriched_workflows") or task_context.metadata.get("workflows") or []),
+                side_effects_artifact=task_context.metadata["side_effects_artifact"],
+            )
+            task_context.metadata["artifacts"]["validation_gate"] = str(current_dir / "validation_gate.json")
+            if review_path is not None:
+                task_context.metadata["artifacts"]["validation_gate_agentic_review"] = str(review_path)
+            if coverage_path is not None:
+                task_context.metadata["artifacts"]["idea_acceptance_coverage"] = str(coverage_path)
+            if cluster_payload is not None:
+                task_context.metadata["repair_clusters"] = cluster_payload
+            if cluster_path is not None:
+                task_context.metadata["artifacts"]["validation_repair_clusters"] = str(cluster_path)
+            self.save_output({"resumed_from": str(current_dir), "skipped_llm": True})
+            return task_context
+        expected_fingerprint = str(task_context.metadata.get("resume_fingerprint") or "") or None
+        failed_prior_gate: dict[str, Any] | None = None
+        failed_gate_candidates = [_current_dir_from_task(task_context) / "validation_gate.json"]
+        prior_run_dir = task_context.metadata.get("prior_run_dir")
+        if prior_run_dir:
+            failed_gate_candidates.append(Path(str(prior_run_dir)) / "validation_gate.json")
+        for gate_path in failed_gate_candidates:
+            if not gate_path.exists() or not _resume_dir_matches_fingerprint(run_dir=gate_path.parent, expected_fingerprint=expected_fingerprint):
+                continue
+            try:
+                gate_payload = json.loads(gate_path.read_text(encoding="utf-8"))
+            except Exception:
+                continue
+            if isinstance(gate_payload, dict) and not bool(gate_payload.get("passed")) and not bool(gate_payload.get("structural_only")):
+                failed_prior_gate = gate_payload
+                break
+        if failed_prior_gate is not None:
+            task_context.metadata["validation_report"] = failed_prior_gate
+            _abort_resume(task_context)
+            self.save_output({"resume_aborted": True, "reason": "prior veg gate failed"})
+            return task_context
+        _abort_resume(task_context)
+
+        _integration_dfs_progress(task_context, "VEG first pass")
+        event = task_context.event
+        repo_root = Path(event.repo_root)
+        pipeline_dir = Path(task_context.metadata["pipeline_dir"])
+        _invalidate_integration_current_from_stage(current_dir=_current_dir_from_task(task_context), stage="validate")
+
+        builder_artifact = _run_veg_idea_acceptance_builder(
+            repo_root=repo_root,
+            pipeline_dir=pipeline_dir,
+            idea_id=event.idea_id,
+            implemented_idea=event.implemented_idea,
+            implemented_stories=event.implemented_stories,
+            side_effects_artifact=task_context.metadata["side_effects_artifact"],
+            implicated_users_artifact=task_context.metadata["implicated_users_artifact"],
+            workflows=task_context.metadata["workflows"],
+            code_evidence=event.code_evidence,
+            source_docs=event.source_docs,
+            node_id="veg_builder_first_pass",
+        )
+        current_agentic_review = builder_artifact.model_dump()
+        enriched_workflows = _ground_workflows_in_side_effects(
+            workflows=[item.model_dump() for item in builder_artifact.enriched_workflows],
+            side_effects_artifact=task_context.metadata["side_effects_artifact"],
+        )
+        current_idea_acceptance_coverage = builder_artifact.idea_acceptance_coverage.model_dump()
+
+        total_interaction_points = sum(
+            len(workflow.get("interaction_points") or [])
+            for workflow in enriched_workflows
+        )
+        if total_interaction_points == 0:
+            _integration_dfs_progress(task_context, "VEG structural only")
+            workflow_count = len(enriched_workflows)
+            review_path, _ = _write_integration_artifact(
+                repo_root=repo_root,
+                idea_id=event.idea_id,
+                pipeline_dir=pipeline_dir,
+                filename="validation_gate_agentic_review.json",
+                data=current_agentic_review,
+            )
+            coverage_path, _ = _write_integration_artifact(
+                repo_root=repo_root,
+                idea_id=event.idea_id,
+                pipeline_dir=pipeline_dir,
+                filename="idea_acceptance_coverage.json",
+                data=current_idea_acceptance_coverage,
+            )
+            validation_report = {
+                "idea_id": event.idea_id,
+                "passed": True,
+                "structural_only": True,
+                "reason": "no actual interaction points across workflows",
+                "workflow_count": workflow_count,
+                "interaction_point_count": 0,
+                "agentic_review": {
+                    "summary": current_agentic_review.get("summary"),
+                    "findings": list(current_agentic_review.get("findings") or []),
+                    "blocking_findings": [
+                        finding
+                        for finding in list(current_agentic_review.get("findings") or [])
+                        if bool(finding.get("blocking")) or str(finding.get("severity") or "").lower() in {"error", "blocking", "critical"}
+                    ],
+                    "enriched_workflow_count": len(current_agentic_review.get("enriched_workflows") or enriched_workflows),
+                },
+                "idea_acceptance_coverage": current_idea_acceptance_coverage,
+                "repair_cycles": 0,
+                "repair_patches_count": 0,
+            }
+            cluster_payload = {
+                "idea_id": event.idea_id,
+                "mode": "internal_sequential_clusters",
+                "structural_only": True,
+                "iterations": [],
+                "latest_iteration": None,
+                "unresolved_cluster_ids": [],
+            }
+            cluster_path, _ = _write_integration_artifact(
+                repo_root=repo_root,
+                idea_id=event.idea_id,
+                pipeline_dir=pipeline_dir,
+                filename="validation_repair_clusters.json",
+                data=cluster_payload,
+            )
+            validation_path, _ = _write_integration_artifact(
+                repo_root=repo_root,
+                idea_id=event.idea_id,
+                pipeline_dir=pipeline_dir,
+                filename="validation_gate.json",
+                data=validation_report,
+            )
+            task_context.metadata["structural_only"] = True
+            task_context.metadata["iterations_used"] = 0
+            task_context.metadata["validation_report"] = validation_report
+            task_context.metadata["builder_review"] = current_agentic_review
+            task_context.metadata["idea_acceptance_coverage"] = current_idea_acceptance_coverage
+            task_context.metadata["repair_clusters"] = cluster_payload
+            task_context.metadata["workflows"] = enriched_workflows
+            task_context.metadata["artifacts"]["validation_gate"] = str(validation_path)
+            task_context.metadata["artifacts"]["validation_gate_agentic_review"] = str(review_path)
+            task_context.metadata["artifacts"]["idea_acceptance_coverage"] = str(coverage_path)
+            task_context.metadata["artifacts"]["validation_repair_clusters"] = str(cluster_path)
+            self.save_output({
+                "structural_only": True,
+                "workflow_count": workflow_count,
+                "interaction_point_count": 0,
+            })
+            task_context.stop_workflow()
+            return task_context
+
+        _integration_dfs_progress(task_context, "VEG deterministic gate")
+        report, iterations_used = _validate_workflows(
+            side_effects_artifact=task_context.metadata["side_effects_artifact"],
+            implicated_users_artifact=task_context.metadata["implicated_users_artifact"],
+            workflows=enriched_workflows,
+            implemented_idea=event.implemented_idea,
+            implemented_stories=event.implemented_stories,
+            idea_acceptance_coverage=current_idea_acceptance_coverage,
+            max_iterations=5,
+            agentic_review=current_agentic_review,
+            repo_root=repo_root,
+            idea_id=event.idea_id,
+            pipeline_dir=pipeline_dir,
+            repair_node_id_prefix="veg",
+            code_evidence=event.code_evidence,
+            source_docs=event.source_docs,
+        )
+
+        latest_repair_clusters = dict(report.pop("_repair_clusters", {}) or {})
+        latest_review = dict(report.pop("_full_agentic_review", current_agentic_review) or {})
+        latest_workflows = _ground_workflows_in_side_effects(
+            workflows=list(report.pop("_final_workflows", enriched_workflows) or enriched_workflows),
+            side_effects_artifact=task_context.metadata["side_effects_artifact"],
+        )
+        latest_coverage = dict(report.get("idea_acceptance_coverage") or current_idea_acceptance_coverage)
+        repair_cycles = max(0, int(iterations_used) - 1)
+        report["repair_cycles"] = repair_cycles
+        report["repair_patches_count"] = 0
+
+        review_path, _ = _write_integration_artifact(
+            repo_root=repo_root,
+            idea_id=event.idea_id,
+            pipeline_dir=pipeline_dir,
+            filename="validation_gate_agentic_review.json",
+            data=latest_review,
+        )
+        coverage_path, _ = _write_integration_artifact(
+            repo_root=repo_root,
+            idea_id=event.idea_id,
+            pipeline_dir=pipeline_dir,
+            filename="idea_acceptance_coverage.json",
+            data=latest_coverage,
+        )
+        cluster_path, _ = _write_integration_artifact(
+            repo_root=repo_root,
+            idea_id=event.idea_id,
+            pipeline_dir=pipeline_dir,
+            filename="validation_repair_clusters.json",
+            data=latest_repair_clusters,
+        )
+        validation_path, _ = _write_integration_artifact(
+            repo_root=repo_root,
+            idea_id=event.idea_id,
+            pipeline_dir=pipeline_dir,
+            filename="validation_gate.json",
+            data=report,
+        )
+        task_context.metadata["artifacts"]["validation_gate"] = str(validation_path)
+        task_context.metadata["artifacts"]["validation_gate_agentic_review"] = str(review_path)
+        task_context.metadata["artifacts"]["idea_acceptance_coverage"] = str(coverage_path)
+        task_context.metadata["artifacts"]["validation_repair_clusters"] = str(cluster_path)
+        task_context.metadata["validation_report"] = report
+        task_context.metadata["builder_review"] = latest_review
+        task_context.metadata["idea_acceptance_coverage"] = latest_coverage
+        task_context.metadata["repair_clusters"] = latest_repair_clusters
+        task_context.metadata["workflows"] = latest_workflows
+        task_context.metadata["iterations_used"] = iterations_used
+        self.save_output(report)
+        if not bool(report.get("passed")):
+            task_context.stop_workflow()
+        return task_context
+
+
+def _canonicalize_red_artifact(*, workflows: list[dict[str, Any]], red_artifact: dict[str, Any]) -> dict[str, Any]:
+    workflow_map = {str(item.get("workflow_id") or ""): item for item in workflows}
+    normalized = json.loads(json.dumps(red_artifact))
+    for package in normalized.get("packages") or []:
+        workflow_id = str(package.get("workflow_id") or "")
+        workflow = workflow_map.get(workflow_id)
+        if workflow is None:
+            continue
+        harness = dict(package.get("harness_selection") or {})
+        interaction_points = list(workflow.get("interaction_points") or [])
+        needed_points = list(workflow.get("needed_interaction_points") or [])
+        primary_point = (interaction_points or needed_points or [{}])[0]
+        expected_harness = _preferred_harness_for_interaction_point(primary_point)
+        if str(harness.get("harness_kind") or "") != expected_harness:
+            harness["harness_kind"] = expected_harness
+        package["harness_selection"] = harness
+    return normalized
+
+
+def _validate_red_packages(*, workflows: list[dict[str, Any]], red_artifact: dict[str, Any]) -> dict[str, Any]:
+    workflow_map = {str(item.get("workflow_id") or ""): item for item in workflows}
+    errors: list[str] = []
+    for package in red_artifact.get("packages") or []:
+        workflow_id = str(package.get("workflow_id") or "")
+        workflow = workflow_map.get(workflow_id)
+        if workflow is None:
+            errors.append(f"red package references unknown workflow {workflow_id}")
+            continue
+        harness = dict(package.get("harness_selection") or {})
+        actual_harness = str(harness.get("harness_kind") or "")
+        interaction_points = list(workflow.get("interaction_points") or [])
+        needed_points = list(workflow.get("needed_interaction_points") or [])
+        primary_point = (interaction_points or needed_points or [{}])[0]
+        expected_harness = _preferred_harness_for_interaction_point(primary_point)
+        if not interaction_points and not needed_points and actual_harness == "artifact_probe":
+            expected_harness = "artifact_probe"
+        if actual_harness != expected_harness:
+            errors.append(f"red harness mismatch for {workflow_id}: expected {expected_harness}")
+        if not (package.get("expected_assertions") or []):
+            errors.append(f"red expected assertions missing for {workflow_id}")
+        if not interaction_points and needed_points and not bool(harness.get("gap_explicit")):
+            errors.append(f"red gap not explicit for {workflow_id}")
+    return {"passed": not errors, "errors": errors}
+
+
+class RedNode(AgentNode):
+    def get_agent_config(self) -> AgentConfig:
+        return AgentConfig(
+            instructions=load_integration_node_instruction("red")
+        )
+
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        # -- checkpoint/resume --
+        prior_red = _try_load_prior_artifact(task_context, "red_package.json", "red_validation.json")
+        if prior_red is not None:
+            current_dir = _current_dir_from_task(task_context)
+            prior_red_val, _ = _read_resume_artifact(task_context, "red_validation.json")
+            if (prior_red_val or {}).get("passed"):
+                task_context.metadata["red_artifact"] = prior_red
+                task_context.metadata["artifacts"].update({
+                    "red_package": str(current_dir / "red_package.json"),
+                    "red_validation": str(current_dir / "red_validation.json"),
+                })
+                self.save_output({"resumed_from": str(current_dir), "skipped_llm": True})
+                return task_context
+        _abort_resume(task_context)
+        # -- end checkpoint/resume --
+
+        _integration_dfs_progress(task_context, "Generating tests")
+
+        event = task_context.event
+        repo_root = Path(event.repo_root)
+        pipeline_dir = Path(task_context.metadata["pipeline_dir"])
+        _invalidate_integration_current_from_stage(current_dir=_current_dir_from_task(task_context), stage="red")
+
+        # Step 1: Run agent to get red artifact
+        artifact, envelope = integration_agentic.run_integration_agent_step(
+            repo_root=repo_root,
+            stage_name="red",
+            output_model=RedArtifact,
+            context_payload={
+                "idea_id": event.idea_id,
+                "validated_workflows": task_context.metadata["workflows"],
+                "validation_report": task_context.metadata["validation_report"],
+                "side_effects_artifact": task_context.metadata["side_effects_artifact"],
+                "implicated_users_artifact": task_context.metadata["implicated_users_artifact"],
+                "code_evidence": event.code_evidence,
+            },
+            guidance=[],
+            timeout_seconds=_integration_agent_timeout_seconds(),
+        )
+        integration_agentic.persist_agent_run(pipeline_root=pipeline_dir, node_id="red", envelope=envelope)
+
+        # Step 2: Normalize and validate red packages
+        red_data = _canonicalize_red_artifact(
+            workflows=task_context.metadata["workflows"],
+            red_artifact=artifact.model_dump(),
+        )
+        report = _validate_red_packages(workflows=task_context.metadata["workflows"], red_artifact=red_data)
+
+        # Step 3: If fails, enter repair loop (up to 2 iterations)
+        if not report["passed"]:
+            max_repair = 2
+            for repair_iter in range(1, max_repair + 1):
+                _integration_dfs_progress(task_context, f"Repair pass {repair_iter}/{max_repair}")
+                # Identify failing packages
+                failing_packages = []
+                for pkg in red_data.get("packages") or []:
+                    wf_id = str(pkg.get("workflow_id") or "")
+                    if any(wf_id in err for err in report.get("errors") or []):
+                        failing_packages.append(pkg)
+                if not failing_packages:
+                    failing_packages = red_data.get("packages") or []
+
+                failing_workflows = [
+                    wf for wf in task_context.metadata["workflows"]
+                    if str(wf.get("workflow_id") or "") in {str(p.get("workflow_id") or "") for p in failing_packages}
+                ]
+
+                # Call repair agent
+                repair_artifact, repair_envelope = integration_agentic.run_integration_code_repair_step(
+                    repo_root=repo_root,
+                    output_model=CodeRepairArtifact,
+                    context_payload={
+                        "failing_packages": failing_packages,
+                        "validation_errors": report.get("errors") or [],
+                        "failing_workflows": failing_workflows,
+                        "side_effects_artifact": task_context.metadata["side_effects_artifact"],
+                        "implicated_users_artifact": task_context.metadata["implicated_users_artifact"],
+                        "code_evidence": event.code_evidence,
+                    },
+                    iteration=repair_iter,
+                    timeout_seconds=_integration_agent_timeout_seconds(),
+                )
+                integration_agentic.persist_agent_run(
+                    pipeline_root=pipeline_dir,
+                    node_id=f"red_code_repair_iter{repair_iter}",
+                    envelope=repair_envelope,
+                )
+
+                # Apply file patches
+                for patch in repair_artifact.patches:
+                    patch_path = repo_root / patch.file_path
+                    patch_path.parent.mkdir(parents=True, exist_ok=True)
+                    patch_path.write_text(patch.content, encoding="utf-8")
+
+                # Re-run agent step for failing workflows to re-generate their red packages
+                _integration_dfs_progress(task_context, f"Re-running tests {repair_iter}/{max_repair}")
+                re_artifact, re_envelope = integration_agentic.run_integration_agent_step(
+                    repo_root=repo_root,
+                    stage_name=f"red_repair_iter{repair_iter}",
+                    output_model=RedArtifact,
+                    context_payload={
+                        "idea_id": event.idea_id,
+                        "validated_workflows": failing_workflows,
+                        "validation_report": task_context.metadata["validation_report"],
+                        "side_effects_artifact": task_context.metadata["side_effects_artifact"],
+                        "implicated_users_artifact": task_context.metadata["implicated_users_artifact"],
+                        "code_evidence": event.code_evidence,
+                    },
+                    guidance=[],
+                    timeout_seconds=_integration_agent_timeout_seconds(),
+                )
+
+                # Merge re-generated packages back into red_data
+                re_normalized = _canonicalize_red_artifact(
+                    workflows=failing_workflows,
+                    red_artifact=re_artifact.model_dump(),
+                )
+                re_pkg_map = {str(p.get("workflow_id") or ""): p for p in re_normalized.get("packages") or []}
+                new_packages = []
+                for pkg in red_data.get("packages") or []:
+                    wf_id = str(pkg.get("workflow_id") or "")
+                    new_packages.append(re_pkg_map.pop(wf_id, pkg))
+                for leftover in re_pkg_map.values():
+                    new_packages.append(leftover)
+                red_data["packages"] = new_packages
+
+                # Re-validate
+                report = _validate_red_packages(workflows=task_context.metadata["workflows"], red_artifact=red_data)
+                if report["passed"]:
+                    break
+
+        # Step 4: Write artifacts
+        if not report["passed"]:
+            task_context.stop_workflow()
+        red_path, _ = _write_integration_artifact(
+            repo_root=repo_root,
+            idea_id=event.idea_id,
+            pipeline_dir=pipeline_dir,
+            filename="red_package.json",
+            data=red_data,
+        )
+        red_validation_path, _ = _write_integration_artifact(
+            repo_root=repo_root,
+            idea_id=event.idea_id,
+            pipeline_dir=pipeline_dir,
+            filename="red_validation.json",
+            data=report,
+        )
+        task_context.metadata["red_artifact"] = red_data
+        task_context.metadata["artifacts"].update({
+            "red_package": str(red_path),
+            "red_validation": str(red_validation_path),
+        })
+        self.save_output({"red_package_ref": str(red_path), "validation": report})
+        return task_context
+
+
+class RedReviewNode(AgentNode):
+    def get_agent_config(self) -> AgentConfig:
+        return AgentConfig(
+            instructions=load_integration_node_instruction("red_review")
+        )
+
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        # -- checkpoint/resume --
+        prior_rr = _try_load_prior_artifact(
+            task_context, "red_review.json",
+            validity_check=lambda d: bool(d.get("agentic_review_clear")),
+        )
+        if prior_rr is not None:
+            current_dir = _current_dir_from_task(task_context)
+            task_context.metadata["artifacts"]["red_review"] = str(current_dir / "red_review.json")
+            self.save_output({"resumed_from": str(current_dir), "skipped_llm": True})
+            return task_context
+        _abort_resume(task_context)
+        # -- end checkpoint/resume --
+
+        _integration_dfs_progress(task_context, "Reviewing tests")
+
+        event = task_context.event
+        repo_root = Path(event.repo_root)
+        pipeline_dir = Path(task_context.metadata["pipeline_dir"])
+        _invalidate_integration_current_from_stage(current_dir=_current_dir_from_task(task_context), stage="red_review")
+        artifact, envelope = integration_agentic.run_integration_agent_step(
+            repo_root=repo_root,
+            stage_name="red_review",
+            output_model=RedReviewArtifact,
+            context_payload={
+                "idea_id": event.idea_id,
+                "validated_workflows": task_context.metadata["workflows"],
+                "red_artifact": task_context.metadata["red_artifact"],
+                "validation_report": task_context.metadata["validation_report"],
+            },
+            guidance=[],
+            timeout_seconds=_integration_agent_timeout_seconds(),
+        )
+        integration_agentic.persist_agent_run(pipeline_root=pipeline_dir, node_id="redreview", envelope=envelope)
+        path, _ = _write_integration_artifact(
+            repo_root=repo_root,
+            idea_id=event.idea_id,
+            pipeline_dir=pipeline_dir,
+            filename="red_review.json",
+            data=artifact.model_dump(),
+        )
+        task_context.metadata["red_review_artifact"] = artifact.model_dump()
+        task_context.metadata["artifacts"]["red_review"] = str(path)
+        self.save_output({"red_review_ref": str(path)})
+        return task_context
+
+
+class GreenNode(AgentNode):
+    def get_agent_config(self) -> AgentConfig:
+        return AgentConfig(
+            instructions=load_integration_node_instruction("green")
+        )
+
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        # -- checkpoint/resume --
+        prior_green = _try_load_prior_artifact(task_context, "green_package.json")
+        if prior_green is not None:
+            current_dir = _current_dir_from_task(task_context)
+            task_context.metadata["artifacts"]["green_package"] = str(current_dir / "green_package.json")
+            self.save_output({"resumed_from": str(current_dir), "skipped_llm": True})
+            return task_context
+        _abort_resume(task_context)
+        # -- end checkpoint/resume --
+
+        _integration_dfs_progress(task_context, "Writing green tests")
+
+        event = task_context.event
+        repo_root = Path(event.repo_root)
+        pipeline_dir = Path(task_context.metadata["pipeline_dir"])
+        _invalidate_integration_current_from_stage(current_dir=_current_dir_from_task(task_context), stage="green")
+        artifact, envelope = integration_agentic.run_integration_agent_step(
+            repo_root=repo_root,
+            stage_name="green",
+            output_model=GreenArtifact,
+            context_payload={
+                "idea_id": event.idea_id,
+                "validated_workflows": task_context.metadata["workflows"],
+                "red_review_artifact": task_context.metadata["red_review_artifact"],
+                "code_evidence": event.code_evidence,
+                "implemented_stories": event.implemented_stories,
+            },
+            guidance=[],
+            timeout_seconds=_integration_agent_timeout_seconds(),
+        )
+        integration_agentic.persist_agent_run(pipeline_root=pipeline_dir, node_id="green", envelope=envelope)
+        path, _ = _write_integration_artifact(
+            repo_root=repo_root,
+            idea_id=event.idea_id,
+            pipeline_dir=pipeline_dir,
+            filename="green_package.json",
+            data=artifact.model_dump(),
+        )
+        task_context.metadata["green_artifact"] = artifact.model_dump()
+        task_context.metadata["artifacts"]["green_package"] = str(path)
+        self.save_output({"green_package_ref": str(path)})
+        return task_context
+
+
+class GreenEnrichNode(AgentNode):
+    def get_agent_config(self) -> AgentConfig:
+        return AgentConfig(
+            instructions=load_integration_node_instruction("green_enrich")
+        )
+
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        # -- checkpoint/resume --
+        prior_ge = _try_load_prior_artifact(task_context, "green_enrich.json")
+        if prior_ge is not None:
+            current_dir = _current_dir_from_task(task_context)
+            task_context.metadata["artifacts"]["green_enrich"] = str(current_dir / "green_enrich.json")
+            self.save_output({"resumed_from": str(current_dir), "skipped_llm": True})
+            return task_context
+        _abort_resume(task_context)
+        # -- end checkpoint/resume --
+
+        _integration_dfs_progress(task_context, "Enriching tests")
+
+        event = task_context.event
+        repo_root = Path(event.repo_root)
+        pipeline_dir = Path(task_context.metadata["pipeline_dir"])
+        _invalidate_integration_current_from_stage(current_dir=_current_dir_from_task(task_context), stage="green_enrich")
+        artifact, envelope = integration_agentic.run_integration_agent_step(
+            repo_root=repo_root,
+            stage_name="green_enrich",
+            output_model=GreenEnrichArtifact,
+            context_payload={
+                "idea_id": event.idea_id,
+                "validated_workflows": task_context.metadata["workflows"],
+                "green_artifact": task_context.metadata["green_artifact"],
+                "red_review_artifact": task_context.metadata["red_review_artifact"],
+            },
+            guidance=[],
+            timeout_seconds=_integration_agent_timeout_seconds(),
+        )
+        integration_agentic.persist_agent_run(pipeline_root=pipeline_dir, node_id="greenenrich", envelope=envelope)
+        path, _ = _write_integration_artifact(
+            repo_root=repo_root,
+            idea_id=event.idea_id,
+            pipeline_dir=pipeline_dir,
+            filename="green_enrich.json",
+            data=artifact.model_dump(),
+        )
+        task_context.metadata["green_enrich_artifact"] = artifact.model_dump()
+        task_context.metadata["artifacts"]["green_enrich"] = str(path)
+        self.save_output({"green_enrich_ref": str(path)})
+        return task_context
+
+
+class CommitNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        _integration_dfs_progress(task_context, "Committing")
+        event = task_context.event
+        pipeline_dir = Path(task_context.metadata["pipeline_dir"])
+        workflows = list(task_context.metadata.get("workflows") or [])
+        green_packages = {
+            str(item.get("workflow_id") or ""): item
+            for item in (task_context.metadata.get("green_artifact") or {}).get("packages") or []
+        }
+        enrich_packages = {
+            str(item.get("workflow_id") or ""): item
+            for item in (task_context.metadata.get("green_enrich_artifact") or {}).get("packages") or []
+        }
+        playwright_request = _build_post_integration_playwright_request(
+            idea_id=event.idea_id,
+            trigger_run_id=str(task_context.metadata.get("dag_run_id") or event.dag_run_id or "") or None,
+            workflows=workflows,
+            red_artifact=dict(task_context.metadata.get("red_artifact") or {}),
+        )
+        request_path, _ = _write_integration_artifact(
+            repo_root=Path(event.repo_root),
+            idea_id=event.idea_id,
+            pipeline_dir=pipeline_dir,
+            filename="post_integration_playwright_request.json",
+            data=playwright_request,
+        )
+        task_context.metadata["post_integration_playwright_request"] = playwright_request
+        task_context.metadata["artifacts"]["post_integration_playwright_request"] = str(request_path)
+        commit_packages: list[CommitWorkflowPackage] = []
+        for workflow in workflows:
+            workflow_id = str(workflow.get("workflow_id") or "")
+            commit_packages.append(
+                CommitWorkflowPackage(
+                    workflow_id=workflow_id,
+                    side_effect_id=str(workflow.get("side_effect", {}).get("id") or ""),
+                    included_artifacts=[
+                        "validation_gate.json",
+                        "red_package.json",
+                        "red_review.json",
+                        "green_package.json",
+                        "green_enrich.json",
+                        "post_integration_playwright_request.json",
+                    ],
+                    traceability={
+                        "idea_id": event.idea_id,
+                        "workflow_ref": workflow_id,
+                        "side_effect_ref": workflow.get("side_effect", {}).get("id"),
+                        "story_backing": workflow.get("story_backing") or [],
+                        "green_changes": (green_packages.get(workflow_id) or {}).get("implementation_changes") or [],
+                        "green_enrich_assertions": (
+                            enrich_packages.get(workflow_id) or {}
+                        ).get("strengthened_assertions") or [],
+                    },
+                )
+            )
+        artifact = CommitArtifact(
+            idea_id=event.idea_id,
+            summary="Integration-proof package assembled and traceably linked.",
+            packages=commit_packages,
+            package_manifest={
+                "idea_id": event.idea_id,
+                "pipeline_dir": str(pipeline_dir),
+                "workflow_ids": [item.workflow_id for item in commit_packages],
+                "artifact_refs": dict(task_context.metadata.get("artifacts") or {}),
+                "post_integration_playwright": {
+                    "status": playwright_request["status"],
+                    "required_workflow_ids": playwright_request["required_workflow_ids"],
+                    "request_ref": str(request_path),
+                },
+            },
+        )
+        path, _ = _write_integration_artifact(
+            repo_root=Path(event.repo_root),
+            idea_id=event.idea_id,
+            pipeline_dir=pipeline_dir,
+            filename="commit_package.json",
+            data=artifact.model_dump(),
+        )
+        task_context.metadata["commit_artifact"] = artifact.model_dump()
+        task_context.metadata["artifacts"]["commit_package"] = str(path)
+        self.save_output({"commit_package_ref": str(path), "workflow_count": len(commit_packages)})
+        return task_context
+
+
+class IntegrationWorkflow(Workflow):
+    workflow_schema = WorkflowSchema(
+        description="Integration DAG (agentic side-effect resolution -> workflow writing -> single hybrid VEG node with internal deterministic gate and repair loop -> real downstream red/redreview/green/greenenrich/commit chain)",
+        event_schema=IntegrationDagEvent,
+        start=LoadIntegrationContextNode,
+        nodes=[
+            NodeConfig(node=LoadIntegrationContextNode, connections=[ResolveSideEffectsAndImplicatedUsersNode]),
+            NodeConfig(node=ResolveSideEffectsAndImplicatedUsersNode, connections=[WriteWorkflowPerSideEffectNode]),
+            NodeConfig(node=WriteWorkflowPerSideEffectNode, connections=[VegNode]),
+            NodeConfig(node=VegNode, connections=[RedNode]),
+            NodeConfig(node=RedNode, connections=[RedReviewNode]),
+            NodeConfig(node=RedReviewNode, connections=[GreenNode]),
+            NodeConfig(node=GreenNode, connections=[GreenEnrichNode]),
+            NodeConfig(node=GreenEnrichNode, connections=[CommitNode]),
+            NodeConfig(node=CommitNode, connections=[]),
+        ],
+    )
+
+
+def _workflow_story_ids(workflow: dict[str, Any]) -> list[str]:
+    return [
+        str(item.get("story_id") or "").strip()
+        for item in (workflow.get("story_backing") or [])
+        if str(item.get("story_id") or "").strip()
+    ]
+
+
+def _extract_acceptance_criteria(value: Any) -> list[str]:
+    if isinstance(value, list):
+        return [str(item).strip() for item in value if str(item).strip()]
+    text = str(value or "").strip()
+    return [text] if text else []
+
+
+def _story_acceptance_index(implemented_stories: list[dict[str, Any]]) -> dict[str, dict[str, Any]]:
+    index: dict[str, dict[str, Any]] = {}
+    for story in implemented_stories:
+        story_id = str(story.get("story_id") or story.get("id") or "").strip()
+        if not story_id:
+            continue
+        criteria = _extract_acceptance_criteria(story.get("acceptance_criteria"))
+        if not criteria:
+            continue
+        index[story_id] = {
+            "story_id": story_id,
+            "title": str(story.get("title") or story.get("name") or story_id).strip(),
+            "acceptance_criteria": criteria,
+            "side_effect_ids": [str(item).strip() for item in (story.get("side_effect_ids") or []) if str(item).strip()],
+        }
+    return index
+
+
+def _idea_acceptance_criteria(implemented_idea: dict[str, Any] | None) -> list[str]:
+    if not isinstance(implemented_idea, dict):
+        return []
+    idea_block = implemented_idea.get("idea") if isinstance(implemented_idea.get("idea"), dict) else implemented_idea
+    return _extract_acceptance_criteria((idea_block or {}).get("acceptance_criteria"))
+
+
+def _determine_failing_workflow_ids(
+    *,
+    workflows: list[dict[str, Any]],
+    errors: list[str],
+    blocking_agentic_findings: list[dict[str, Any]],
+    repair_sources: list[dict[str, Any]] | None = None,
+) -> set[str]:
+    workflow_ids = {str(workflow.get("workflow_id") or "") for workflow in workflows if str(workflow.get("workflow_id") or "")}
+    side_effect_to_workflow_ids: dict[str, set[str]] = {}
+    story_to_workflow_ids: dict[str, set[str]] = {}
+    for workflow in workflows:
+        workflow_id = str(workflow.get("workflow_id") or "")
+        if not workflow_id:
+            continue
+        side_effect_id = str(workflow.get("side_effect", {}).get("id") or "")
+        if side_effect_id:
+            side_effect_to_workflow_ids.setdefault(side_effect_id, set()).add(workflow_id)
+        for story_id in _workflow_story_ids(workflow):
+            story_to_workflow_ids.setdefault(story_id, set()).add(workflow_id)
+
+    failing: set[str] = set()
+    for error in errors:
+        for workflow_id in workflow_ids:
+            if workflow_id and workflow_id in error:
+                failing.add(workflow_id)
+        for side_effect_id, mapped_ids in side_effect_to_workflow_ids.items():
+            if side_effect_id and side_effect_id in error:
+                failing.update(mapped_ids)
+        for story_id, mapped_ids in story_to_workflow_ids.items():
+            if story_id and story_id in error:
+                failing.update(mapped_ids)
+    for finding in blocking_agentic_findings:
+        workflow_id = str(finding.get("workflow_id") or "").strip()
+        if workflow_id:
+            failing.add(workflow_id)
+    for source in repair_sources or []:
+        for workflow_id in source.get("workflow_ids") or []:
+            workflow_id = str(workflow_id or "").strip()
+            if workflow_id:
+                failing.add(workflow_id)
+    return failing
+
+
+def _idea_acceptance_lineage_is_model_backed(lineage: Any) -> bool:
+    if not isinstance(lineage, dict):
+        return False
+    if bool(lineage.get("model_backed")):
+        return True
+    metadata = lineage.get("metadata")
+    return isinstance(metadata, dict) and bool(metadata.get("model_backed"))
+
+
+def _normalize_idea_acceptance_coverage(
+    *,
+    idea_acceptance_coverage: dict[str, Any] | None,
+    canonical_criteria: list[str],
+) -> dict[str, Any]:
+    coverage = dict(idea_acceptance_coverage or {})
+    raw_entries = [dict(entry) for entry in (coverage.get("criteria") or []) if isinstance(entry, dict)]
+    if not canonical_criteria:
+        coverage["criteria"] = []
+        return coverage
+
+    normalized_entries: list[dict[str, Any]] = []
+    used_positions: set[int] = set()
+    criterion_to_index = {
+        criterion: idx
+        for idx, criterion in enumerate(canonical_criteria, start=1)
+    }
+    for idx, canonical_criterion in enumerate(canonical_criteria, start=1):
+        selected_position: int | None = None
+        fallback_position: int | None = None
+        for position, entry in enumerate(raw_entries):
+            if position in used_positions:
+                continue
+            entry_index = int(entry.get("criterion_index") or 0)
+            entry_criterion = str(entry.get("criterion") or "").strip()
+            if entry_index == idx and entry_criterion == canonical_criterion:
+                selected_position = position
+                break
+            if fallback_position is None and entry_criterion == canonical_criterion:
+                fallback_position = position
+            elif fallback_position is None and entry_index == idx:
+                fallback_position = position
+        if selected_position is None:
+            selected_position = fallback_position
+        if selected_position is None:
+            continue
+        used_positions.add(selected_position)
+        normalized_entry = dict(raw_entries[selected_position])
+        normalized_entry["criterion_index"] = idx
+        normalized_entry["criterion"] = canonical_criterion
+        normalized_entries.append(normalized_entry)
+
+    for position, entry in enumerate(raw_entries):
+        if position in used_positions:
+            continue
+        entry_criterion = str(entry.get("criterion") or "").strip()
+        mapped_index = criterion_to_index.get(entry_criterion)
+        if mapped_index is None:
+            continue
+        if any(int(item.get("criterion_index") or 0) == mapped_index for item in normalized_entries):
+            continue
+        normalized_entry = dict(entry)
+        normalized_entry["criterion_index"] = mapped_index
+        normalized_entry["criterion"] = canonical_criteria[mapped_index - 1]
+        normalized_entries.append(normalized_entry)
+
+    normalized_entries.sort(key=lambda entry: int(entry.get("criterion_index") or 0))
+    coverage["criteria"] = normalized_entries
+    return coverage
+
+
+def _filter_idea_acceptance_coverage(
+    *,
+    idea_acceptance_coverage: dict[str, Any] | None,
+    criterion_indices: set[int],
+) -> dict[str, Any]:
+    filtered = dict(idea_acceptance_coverage or {})
+    filtered["criteria"] = [
+        dict(entry)
+        for entry in (filtered.get("criteria") or [])
+        if int(entry.get("criterion_index") or 0) in criterion_indices
+    ]
+    return filtered
+
+
+def _validation_convergence_state(
+    *,
+    idea_acceptance_coverage: dict[str, Any] | None,
+    deterministic_errors: list[str],
+    blocking_agentic_findings: list[dict[str, Any]],
+    acceptance_failures: list[dict[str, Any]],
+    idea_acceptance_failures: list[dict[str, Any]],
+) -> dict[str, Any]:
+    verdict_map = {
+        int(entry.get("criterion_index") or 0): str(entry.get("verdict") or "").strip().lower()
+        for entry in list((idea_acceptance_coverage or {}).get("criteria") or [])
+        if int(entry.get("criterion_index") or 0) > 0
+    }
+    finding_set = sorted({
+        *[str(error).strip() for error in deterministic_errors if str(error).strip()],
+        *[
+            f"{str(finding.get('workflow_id') or 'global').strip()}::{str(finding.get('summary') or '').strip()}"
+            for finding in blocking_agentic_findings
+            if str(finding.get("summary") or "").strip()
+        ],
+    })
+    missing_seams = sorted({
+        *[
+            f"criterion#{int(entry.get('criterion_index') or 0)}::{seam}"
+            for entry in list((idea_acceptance_coverage or {}).get("criteria") or [])
+            for seam in list(entry.get("missing_seams") or [])
+            if int(entry.get("criterion_index") or 0) > 0 and str(seam).strip()
+        ],
+        *[
+            str(failure.get("message") or "").strip()
+            for failure in acceptance_failures
+            if str(failure.get("source_type") or "").strip() == "acceptance_criterion_missing_seam"
+            and str(failure.get("message") or "").strip()
+        ],
+        *[
+            str(failure.get("message") or "").strip()
+            for failure in idea_acceptance_failures
+            if any("seam" in str(reason or "").lower() for reason in list(failure.get("reasons") or []))
+            and str(failure.get("message") or "").strip()
+        ],
+    })
+    return {
+        "verdict_map": verdict_map,
+        "finding_set": finding_set,
+        "missing_seams": missing_seams,
+    }
+
+
+def _build_validate_repair_protected_context(
+    *,
+    workflows: list[dict[str, Any]],
+    failing_workflow_ids: set[str],
+    idea_acceptance_coverage: dict[str, Any] | None = None,
+    failing_idea_criterion_indices: set[int] | None = None,
+) -> tuple[list[dict[str, Any]], list[str]]:
+    protected_sections: list[dict[str, Any]] = []
+    do_not_touch: list[str] = []
+    failing_idea_criterion_indices = set(failing_idea_criterion_indices or set())
+    for workflow in workflows:
+        workflow_id = str(workflow.get("workflow_id") or "")
+        if not workflow_id:
+            continue
+        side_effect_id = str(workflow.get("side_effect", {}).get("id") or "")
+        if workflow_id not in failing_workflow_ids:
+            protected_sections.append(
+                {
+                    "section_type": "workflow",
+                    "workflow_id": workflow_id,
+                    "side_effect_id": side_effect_id,
+                    "reason": "workflow passed deterministic validation; preserve it",
+                    "protected_fields": [
+                        "workflow_id",
+                        "side_effect",
+                        "story_backing",
+                        "code_backing",
+                        "source_doc_backing",
+                        "implicated_users",
+                        "interaction_points",
+                        "needed_interaction_points",
+                        "process_sequence",
+                        "branches",
+                        "resulting_artifacts",
+                    ],
+                }
+            )
+            do_not_touch.append(f"Do not modify passing workflow {workflow_id} (side_effect={side_effect_id or 'unknown'}).")
+            continue
+        do_not_touch.extend(
+            [
+                f"Within failing workflow {workflow_id}, preserve workflow_id and side_effect anchoring.",
+                f"Within failing workflow {workflow_id}, preserve already-supported story_backing/code_backing/source_doc_backing unless the repair source explicitly says they are wrong.",
+            ]
+        )
+    coverage_entries = list((idea_acceptance_coverage or {}).get("criteria") or [])
+    for entry in coverage_entries:
+        criterion_index = int(entry.get("criterion_index") or 0)
+        criterion = str(entry.get("criterion") or "").strip()
+        if criterion_index and criterion_index not in failing_idea_criterion_indices:
+            protected_sections.append(
+                {
+                    "section_type": "idea_acceptance_criterion",
+                    "criterion_index": criterion_index,
+                    "criterion": criterion,
+                    "reason": "idea acceptance criterion already proven; preserve its proof mapping",
+                    "protected_fields": [
+                        "criterion_index",
+                        "criterion",
+                        "verdict",
+                        "story_ids",
+                        "workflow_ids",
+                        "side_effect_ids",
+                        "evidence_refs",
+                        "proof_summary",
+                    ],
+                }
+            )
+            do_not_touch.append(f"Do not modify passing idea acceptance criterion #{criterion_index}: {criterion}")
+            do_not_touch.append(
+                f"Do not revisit already-stable idea acceptance criterion #{criterion_index} unless you can cite a contradiction in the current artifact."
+            )
+        elif criterion_index:
+            do_not_touch.append(
+                f"Within failing idea acceptance criterion #{criterion_index}, preserve criterion_index and criterion text exactly; repair only missing proof, seams, or evidence mapping."
+            )
+    return protected_sections, do_not_touch
+
+
+def _validate_workflow_repair_sources(
+    *,
+    deterministic_errors: list[str],
+    blocking_agentic_findings: list[dict[str, Any]],
+    acceptance_failures: list[dict[str, Any]] | None = None,
+    idea_acceptance_failures: list[dict[str, Any]] | None = None,
+) -> list[dict[str, Any]]:
+    repair_sources: list[dict[str, Any]] = [
+        {
+            "source_type": "deterministic_validation_error",
+            "message": error,
+        }
+        for error in deterministic_errors
+    ]
+    repair_sources.extend(
+        {
+            "source_type": "agentic_blocking_finding",
+            "workflow_id": finding.get("workflow_id"),
+            "severity": finding.get("severity"),
+            "summary": finding.get("summary"),
+            "details": list(finding.get("details") or []),
+            "blocking": bool(finding.get("blocking")),
+        }
+        for finding in blocking_agentic_findings
+    )
+    repair_sources.extend(list(acceptance_failures or []))
+    repair_sources.extend(list(idea_acceptance_failures or []))
+    return repair_sources
+
+
+def _interaction_point_seam_family(point: dict[str, Any]) -> str:
+    kind = str(point.get("kind") or "").strip().lower()
+    if not kind:
+        kind = _normalize_interaction_type(str(point.get("type") or "").strip().lower())
+    return kind or "no_seam"
+
+
+def _workflow_seam_family(workflow: dict[str, Any]) -> str:
+    for point in list(workflow.get("interaction_points") or []) + list(workflow.get("needed_interaction_points") or []):
+        family = _interaction_point_seam_family(point)
+        if family and family != "no_seam":
+            return family
+    return "missing_seam"
+
+
+def _merge_repaired_workflows(
+    *,
+    base_workflows: list[dict[str, Any]],
+    repaired_workflows: list[dict[str, Any]],
+    allowed_workflow_ids: set[str],
+    side_effects_artifact: dict[str, Any],
+) -> list[dict[str, Any]]:
+    repaired_map = {
+        str(item.get("workflow_id") or ""): dict(item)
+        for item in repaired_workflows
+        if str(item.get("workflow_id") or "")
+    }
+    merged: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for workflow in base_workflows:
+        workflow_id = str(workflow.get("workflow_id") or "")
+        if workflow_id in allowed_workflow_ids and workflow_id in repaired_map:
+            merged.append(_ground_workflow_in_side_effect(workflow=repaired_map[workflow_id], side_effects_artifact=side_effects_artifact))
+            seen.add(workflow_id)
+        else:
+            merged.append(dict(workflow))
+    for workflow_id, workflow in repaired_map.items():
+        if workflow_id in allowed_workflow_ids and workflow_id not in seen:
+            merged.append(_ground_workflow_in_side_effect(workflow=workflow, side_effects_artifact=side_effects_artifact))
+    return merged
+
+
+def _merge_repaired_idea_acceptance_coverage(
+    *,
+    base_coverage: dict[str, Any],
+    repaired_coverage: dict[str, Any],
+    allowed_criterion_indices: set[int],
+    canonical_criteria: list[str],
+) -> dict[str, Any]:
+    merged = dict(base_coverage or {})
+    base_entries = {
+        int(entry.get("criterion_index") or 0): dict(entry)
+        for entry in (merged.get("criteria") or [])
+        if int(entry.get("criterion_index") or 0) > 0
+    }
+    repaired_entries = {
+        int(entry.get("criterion_index") or 0): dict(entry)
+        for entry in (repaired_coverage.get("criteria") or [])
+        if int(entry.get("criterion_index") or 0) > 0
+    }
+    for idx in allowed_criterion_indices:
+        if idx in repaired_entries:
+            base_entries[idx] = repaired_entries[idx]
+    merged["criteria"] = [base_entries[idx] for idx in sorted(base_entries)]
+    repaired_lineage = repaired_coverage.get("execution_lineage")
+    if repaired_lineage:
+        merged["execution_lineage"] = repaired_lineage
+    return _normalize_idea_acceptance_coverage(
+        idea_acceptance_coverage=merged,
+        canonical_criteria=canonical_criteria,
+    )
+
+
+def _build_validate_repair_clusters(
+    *,
+    workflows: list[dict[str, Any]],
+    repair_sources: list[dict[str, Any]],
+    blocking_agentic_findings: list[dict[str, Any]],
+    idea_acceptance_coverage: dict[str, Any] | None = None,
+    failing_workflow_ids: set[str],
+    failing_idea_criterion_indices: set[int],
+) -> list[dict[str, Any]]:
+    workflow_map = {
+        str(workflow.get("workflow_id") or ""): dict(workflow)
+        for workflow in workflows
+        if str(workflow.get("workflow_id") or "")
+    }
+    coverage_by_index = {
+        int(entry.get("criterion_index") or 0): dict(entry)
+        for entry in list((idea_acceptance_coverage or {}).get("criteria") or [])
+        if int(entry.get("criterion_index") or 0) > 0
+    }
+
+    def cluster_key_for(*, seam_family: str, workflow_ids: set[str], criterion_indices: set[int]) -> tuple[str, str]:
+        side_effect_ids = sorted({
+            str((workflow_map.get(workflow_id) or {}).get("side_effect", {}).get("id") or "")
+            for workflow_id in workflow_ids
+            if str((workflow_map.get(workflow_id) or {}).get("side_effect", {}).get("id") or "")
+        })
+        if not side_effect_ids and criterion_indices:
+            for idx in criterion_indices:
+                entry = coverage_by_index.get(idx) or {}
+                side_effect_ids.extend(
+                    sid for sid in (str(item).strip() for item in (entry.get("side_effect_ids") or [])) if sid
+                )
+        scope = "__".join(sorted(dict.fromkeys(side_effect_ids))) or "global"
+        return seam_family or "global", scope
+
+    clusters: dict[tuple[str, str], dict[str, Any]] = {}
+
+    def ensure_cluster(*, seam_family: str, workflow_ids: set[str], criterion_indices: set[int]) -> dict[str, Any]:
+        family, scope = cluster_key_for(seam_family=seam_family, workflow_ids=workflow_ids, criterion_indices=criterion_indices)
+        key = (family, scope)
+        cluster = clusters.get(key)
+        if cluster is None:
+            cluster = {
+                "cluster_id": f"{family}__{scope}",
+                "cluster_type": "repair_cluster",
+                "seam_family": family,
+                "scope": scope,
+                "workflow_ids": set(),
+                "side_effect_ids": set(),
+                "criterion_indices": set(),
+                "repair_sources": [],
+                "blocking_findings": [],
+                "source_types": set(),
+            }
+            clusters[key] = cluster
+        cluster["workflow_ids"].update(workflow_ids)
+        cluster["criterion_indices"].update(criterion_indices)
+        for workflow_id in workflow_ids:
+            side_effect_id = str((workflow_map.get(workflow_id) or {}).get("side_effect", {}).get("id") or "")
+            if side_effect_id:
+                cluster["side_effect_ids"].add(side_effect_id)
+        return cluster
+
+    for source in repair_sources:
+        source_workflow_ids = {
+            str(item).strip()
+            for item in (source.get("workflow_ids") or [])
+            if str(item).strip()
+        }
+        source_workflow_ids.update(
+            workflow_id
+            for workflow_id in failing_workflow_ids
+            if workflow_id and workflow_id in str(source.get("message") or "")
+        )
+        source_workflow_ids.update(
+            workflow_id
+            for workflow_id in failing_workflow_ids
+            if workflow_id and workflow_id == str(source.get("workflow_id") or "").strip()
+        )
+        criterion_index = int(source.get("criterion_index") or 0)
+        if criterion_index <= 0:
+            match = re.search(r"\[#(\d+)\]", str(source.get("message") or ""))
+            if match:
+                criterion_index = int(match.group(1))
+        criterion_indices = {criterion_index} if criterion_index > 0 else set()
+        if not source_workflow_ids and criterion_indices:
+            for idx in criterion_indices:
+                entry = coverage_by_index.get(idx) or {}
+                source_workflow_ids.update(
+                    str(item).strip()
+                    for item in (entry.get("workflow_ids") or [])
+                    if str(item).strip()
+                )
+        if str(source.get("source_type") or "") == "deterministic_validation_error" and not source_workflow_ids and not criterion_indices:
+            continue
+        seam_families = {
+            _workflow_seam_family(workflow_map[workflow_id])
+            for workflow_id in source_workflow_ids
+            if workflow_id in workflow_map
+        }
+        if source.get("source_type") in {"acceptance_criterion_missing_seam", "idea_acceptance_criterion_under_proven"} and not seam_families:
+            seam_families.add("missing_seam")
+        if source.get("source_type") == "idea_acceptance_builder_not_model_backed":
+            seam_families.add("builder_lineage")
+        if not seam_families:
+            seam_families = {"global"}
+        for seam_family in seam_families:
+            cluster = ensure_cluster(seam_family=seam_family, workflow_ids=source_workflow_ids, criterion_indices=criterion_indices)
+            cluster["repair_sources"].append(dict(source))
+            source_type = str(source.get("source_type") or "deterministic_validation_error").strip()
+            if source_type:
+                cluster["source_types"].add(source_type)
+
+    for finding in blocking_agentic_findings:
+        workflow_id = str(finding.get("workflow_id") or "").strip()
+        workflow_ids = {workflow_id} if workflow_id else set()
+        seam_family = _workflow_seam_family(workflow_map[workflow_id]) if workflow_id in workflow_map else "global"
+        cluster = ensure_cluster(seam_family=seam_family, workflow_ids=workflow_ids, criterion_indices=set())
+        cluster["blocking_findings"].append(dict(finding))
+        cluster["source_types"].add("agentic_blocking_finding")
+
+    for workflow_id in sorted(failing_workflow_ids):
+        seam_family = _workflow_seam_family(workflow_map.get(workflow_id) or {})
+        ensure_cluster(seam_family=seam_family, workflow_ids={workflow_id}, criterion_indices=set())
+
+    if not clusters and (failing_workflow_ids or failing_idea_criterion_indices):
+        cluster = ensure_cluster(seam_family="global", workflow_ids=set(failing_workflow_ids), criterion_indices=set(failing_idea_criterion_indices))
+        cluster["source_types"].add("fallback_cluster")
+
+    finalized: list[dict[str, Any]] = []
+    for cluster in clusters.values():
+        workflow_ids = sorted(cluster["workflow_ids"])
+        criterion_indices = sorted(cluster["criterion_indices"])
+        if not workflow_ids and not criterion_indices and not cluster["repair_sources"] and not cluster["blocking_findings"]:
+            continue
+        finalized.append({
+            "cluster_id": cluster["cluster_id"],
+            "cluster_type": cluster["cluster_type"],
+            "seam_family": cluster["seam_family"],
+            "scope": cluster["scope"],
+            "workflow_ids": workflow_ids,
+            "side_effect_ids": sorted(cluster["side_effect_ids"]),
+            "criterion_indices": criterion_indices,
+            "repair_sources": cluster["repair_sources"],
+            "blocking_findings": cluster["blocking_findings"],
+            "source_types": sorted(cluster["source_types"]),
+            "failing_workflows": [workflow_map[workflow_id] for workflow_id in workflow_ids if workflow_id in workflow_map],
+            "failing_idea_acceptance_criteria": [coverage_by_index[idx] for idx in criterion_indices if idx in coverage_by_index],
+        })
+    finalized.sort(key=lambda item: (item["seam_family"], item["scope"], item["cluster_id"]))
+    return finalized
+
+
+def _persist_validate_repair_clusters(
+    *,
+    repo_root: Path | None,
+    idea_id: str | None,
+    pipeline_dir: Path | None,
+    payload: dict[str, Any],
+) -> None:
+    if repo_root is None or idea_id is None or pipeline_dir is None:
+        return
+    _write_integration_artifact(
+        repo_root=repo_root,
+        idea_id=idea_id,
+        pipeline_dir=pipeline_dir,
+        filename="validation_repair_clusters.json",
+        data=payload,
+    )
+
+
+def _validate_workflows(
+    *,
+    side_effects_artifact: dict[str, Any],
+    implicated_users_artifact: dict[str, Any],
+    workflows: list[dict[str, Any]],
+    implemented_idea: dict[str, Any] | None = None,
+    implemented_stories: list[dict[str, Any]] | None = None,
+    idea_acceptance_coverage: dict[str, Any] | None = None,
+    max_iterations: int = 4,
+    agentic_review: dict[str, Any] | None = None,
+    repo_root: Path | None = None,
+    idea_id: str | None = None,
+    pipeline_dir: Path | None = None,
+    repair_node_id_prefix: str = "validate",
+    code_evidence: list[dict[str, Any]] | None = None,
+    source_docs: list[dict[str, Any]] | None = None,
+) -> tuple[dict[str, Any], int]:
+    iterations_used = 0
+    validations: list[dict[str, Any]] = []
+    pending = [dict(workflow) for workflow in workflows]
+    expected_side_effect_ids = {str(item.get("id") or "") for item in side_effects_artifact.get("side_effects") or [] if str(item.get("id") or "")}
+    expected_users = {
+        (str(user.get("kind") or ""), str(user.get("scope") or ""), str(user.get("authority") or ""))
+        for user in implicated_users_artifact.get("implicated_users") or []
+    }
+    implemented_stories = list(implemented_stories or [])
+    story_acceptance = _story_acceptance_index(implemented_stories)
+    story_index = {
+        str(story.get("story_id") or story.get("id") or "").strip(): dict(story)
+        for story in implemented_stories
+        if str(story.get("story_id") or story.get("id") or "").strip()
+    }
+    idea_acceptance_criteria = _idea_acceptance_criteria(implemented_idea)
+    agentic_review = dict(agentic_review or {})
+    pending_idea_acceptance_coverage = _normalize_idea_acceptance_coverage(
+        idea_acceptance_coverage=idea_acceptance_coverage,
+        canonical_criteria=idea_acceptance_criteria,
+    )
+    agentic_findings = list(agentic_review.get("findings") or [])
+    blocking_agentic_findings = [
+        finding
+        for finding in agentic_findings
+        if bool(finding.get("blocking")) or str(finding.get("severity") or "").lower() in {"error", "blocking", "critical"}
+    ]
+
+    cluster_history: list[dict[str, Any]] = []
+    prior_convergence_state: dict[str, Any] | None = None
+    final_errors: list[str] = []
+    final_idea_acceptance_failures: list[dict[str, Any]] = []
+    final_repair_clusters_payload = {
+        "idea_id": idea_id or side_effects_artifact.get("idea_id"),
+        "mode": "internal_sequential_clusters",
+        "iterations": [],
+        "latest_iteration": None,
+        "unresolved_cluster_ids": [],
+    }
+
+    for iteration in range(1, max_iterations + 1):
+        iterations_used = iteration
+        errors: list[str] = []
+        acceptance_failures: list[dict[str, Any]] = []
+        idea_acceptance_failures: list[dict[str, Any]] = []
+        workflow_side_effect_ids = {str(item.get("side_effect", {}).get("id") or "") for item in pending}
+        if workflow_side_effect_ids != expected_side_effect_ids:
+            missing = sorted(expected_side_effect_ids - workflow_side_effect_ids)
+            if missing:
+                errors.append(f"missing workflows for side effects: {', '.join(missing)}")
+
+        attached_users = {
+            (str(user.get("kind") or ""), str(user.get("scope") or ""), str(user.get("authority") or ""))
+            for workflow in pending
+            for user in (workflow.get("implicated_users") or [])
+        }
+        if not expected_users.issubset(attached_users):
+            errors.append("all implicated users covered: false")
+
+        side_effect_map = _workflow_side_effect_map(side_effects_artifact)
+        story_to_workflow_ids: dict[str, set[str]] = {}
+        workflow_map: dict[str, dict[str, Any]] = {}
+        for workflow in pending:
+            workflow_id = str(workflow.get("workflow_id") or "")
+            if workflow_id:
+                workflow_map[workflow_id] = workflow
+            for story_id in _workflow_story_ids(workflow):
+                story_to_workflow_ids.setdefault(story_id, set()).add(workflow_id)
+        for workflow in pending:
+            wf_id = str(workflow.get("workflow_id") or "")
+            wf_se_id = str(workflow.get("side_effect", {}).get("id") or "")
+            expected_side_effect = side_effect_map.get(wf_se_id) or {}
+            if wf_se_id and wf_se_id not in expected_side_effect_ids:
+                errors.append(f"story alignment mismatch for {wf_id}")
+            if not workflow.get("story_backing"):
+                errors.append(f"story alignment missing for {wf_id}")
+            if not workflow.get("code_backing"):
+                errors.append(f"code alignment missing for {wf_id}")
+            interaction_points = list(workflow.get("interaction_points") or [])
+            needed_points = list(workflow.get("needed_interaction_points") or [])
+            expected_interaction_points = list(expected_side_effect.get("interaction_points") or [])
+            expected_needed_points = list(expected_side_effect.get("needed_interaction_points") or [])
+            if interaction_points != expected_interaction_points or needed_points != expected_needed_points:
+                errors.append(f"interaction seam drift for {wf_id}")
+            if not interaction_points and not needed_points:
+                errors.append(f"interaction points missing for {wf_id}")
+            if workflow.get("anchor_user"):
+                errors.append(f"workflow anchored to user instead of side effect for {wf_id}")
+
+        for story_id, story_contract in story_acceptance.items():
+            related_workflow_ids = sorted(story_to_workflow_ids.get(story_id) or [])
+            if not related_workflow_ids:
+                for idx, criterion in enumerate(story_contract.get("acceptance_criteria") or [], start=1):
+                    message = f"acceptance criteria uncovered for {story_id} [#{idx}]: {criterion}"
+                    errors.append(message)
+                    acceptance_failures.append(
+                        {
+                            "source_type": "acceptance_criterion_uncovered",
+                            "story_id": story_id,
+                            "story_title": story_contract.get("title"),
+                            "criterion_index": idx,
+                            "criterion": criterion,
+                            "workflow_ids": [],
+                            "message": message,
+                        }
+                    )
+                continue
+            seam_workflow_ids = [
+                workflow_id
+                for workflow_id in related_workflow_ids
+                if (workflow_map.get(workflow_id) or {}).get("interaction_points") or (workflow_map.get(workflow_id) or {}).get("needed_interaction_points")
+            ]
+            if seam_workflow_ids:
+                continue
+            for idx, criterion in enumerate(story_contract.get("acceptance_criteria") or [], start=1):
+                message = f"acceptance criterion missing seam for {story_id} [#{idx}]: {criterion}"
+                errors.append(message)
+                acceptance_failures.append(
+                    {
+                        "source_type": "acceptance_criterion_missing_seam",
+                        "story_id": story_id,
+                        "story_title": story_contract.get("title"),
+                        "criterion_index": idx,
+                        "criterion": criterion,
+                        "workflow_ids": related_workflow_ids,
+                        "message": message,
+                    }
+                )
+
+        coverage_entries = list(pending_idea_acceptance_coverage.get("criteria") or [])
+        coverage_by_index = {
+            int(entry.get("criterion_index") or 0): dict(entry)
+            for entry in coverage_entries
+            if int(entry.get("criterion_index") or 0) > 0
+        }
+        for idx, criterion in enumerate(idea_acceptance_criteria, start=1):
+            entry = coverage_by_index.get(idx)
+            if entry is None:
+                message = f"idea acceptance criterion uncovered [#{idx}]: {criterion}"
+                errors.append(message)
+                idea_acceptance_failures.append(
+                    {
+                        "source_type": "idea_acceptance_criterion_uncovered",
+                        "criterion_index": idx,
+                        "criterion": criterion,
+                        "workflow_ids": [],
+                        "story_ids": [],
+                        "message": message,
+                    }
+                )
+                continue
+            if str(entry.get("criterion") or "").strip() != criterion:
+                message = f"idea acceptance criterion drift [#{idx}]: expected '{criterion}'"
+                errors.append(message)
+                idea_acceptance_failures.append(
+                    {
+                        "source_type": "idea_acceptance_criterion_drift",
+                        "criterion_index": idx,
+                        "criterion": criterion,
+                        "workflow_ids": list(entry.get("workflow_ids") or []),
+                        "story_ids": list(entry.get("story_ids") or []),
+                        "message": message,
+                    }
+                )
+            verdict = str(entry.get("verdict") or "").strip().lower()
+            story_ids = [sid for sid in (str(item).strip() for item in (entry.get("story_ids") or [])) if sid]
+            workflow_ids = [wid for wid in (str(item).strip() for item in (entry.get("workflow_ids") or [])) if wid]
+            evidence_refs = [ref for ref in (str(item).strip() for item in (entry.get("evidence_refs") or [])) if ref]
+            mapped_story_ids = [sid for sid in story_ids if sid in story_index]
+            mapped_workflow_ids = [wid for wid in workflow_ids if wid in workflow_map]
+            seam_workflow_ids = [
+                wid for wid in mapped_workflow_ids
+                if (workflow_map.get(wid) or {}).get("interaction_points") or (workflow_map.get(wid) or {}).get("needed_interaction_points")
+            ]
+            under_proven_reasons: list[str] = []
+            if verdict != "covered":
+                under_proven_reasons.append(f"verdict={verdict or 'missing'}")
+            if not mapped_story_ids:
+                under_proven_reasons.append("missing story mapping")
+            if not mapped_workflow_ids:
+                under_proven_reasons.append("missing workflow mapping")
+            if mapped_workflow_ids and not seam_workflow_ids:
+                under_proven_reasons.append("workflow mapping has no interaction seam")
+            if not evidence_refs:
+                under_proven_reasons.append("missing evidence refs")
+            if not str(entry.get("proof_summary") or "").strip():
+                under_proven_reasons.append("missing proof summary")
+            if under_proven_reasons:
+                message = f"idea acceptance criterion under-proven [#{idx}]: {criterion} :: {', '.join(under_proven_reasons)}"
+                errors.append(message)
+                idea_acceptance_failures.append(
+                    {
+                        "source_type": "idea_acceptance_criterion_under_proven",
+                        "criterion_index": idx,
+                        "criterion": criterion,
+                        "workflow_ids": mapped_workflow_ids,
+                        "story_ids": mapped_story_ids,
+                        "message": message,
+                        "reasons": under_proven_reasons,
+                    }
+                )
+
+        lineage = pending_idea_acceptance_coverage.get("execution_lineage") if isinstance(pending_idea_acceptance_coverage, dict) else None
+        if idea_acceptance_criteria:
+            if not _idea_acceptance_lineage_is_model_backed(lineage):
+                errors.append("idea acceptance builder lineage missing model-backed proof")
+                idea_acceptance_failures.append(
+                    {
+                        "source_type": "idea_acceptance_builder_not_model_backed",
+                        "criterion_index": None,
+                        "criterion": "",
+                        "workflow_ids": [],
+                        "story_ids": [],
+                        "message": "idea acceptance builder lineage missing model-backed proof",
+                    }
+                )
+
+        if not attached_users.issubset(expected_users) and expected_users:
+            errors.append("invalid actors admitted into workflows")
+
+        deterministic_errors = list(errors)
+        errors.extend(
+            f"agentic review blocking: {finding.get('workflow_id') or 'global'} :: {finding.get('summary') or 'unspecified issue'}"
+            for finding in blocking_agentic_findings
+        )
+        repair_sources = _validate_workflow_repair_sources(
+            deterministic_errors=deterministic_errors,
+            blocking_agentic_findings=blocking_agentic_findings,
+            acceptance_failures=acceptance_failures,
+            idea_acceptance_failures=idea_acceptance_failures,
+        )
+        failing_workflow_ids = _determine_failing_workflow_ids(
+            workflows=pending,
+            errors=deterministic_errors,
+            blocking_agentic_findings=blocking_agentic_findings,
+            repair_sources=repair_sources,
+        )
+        failing_idea_criterion_indices = {
+            int(item.get("criterion_index") or 0)
+            for item in idea_acceptance_failures
+            if int(item.get("criterion_index") or 0) > 0
+        }
+        protected_sections, do_not_touch = _build_validate_repair_protected_context(
+            workflows=pending,
+            failing_workflow_ids=failing_workflow_ids,
+            idea_acceptance_coverage=pending_idea_acceptance_coverage,
+            failing_idea_criterion_indices=failing_idea_criterion_indices,
+        )
+        repair_clusters = _build_validate_repair_clusters(
+            workflows=pending,
+            repair_sources=repair_sources,
+            blocking_agentic_findings=blocking_agentic_findings,
+            idea_acceptance_coverage=pending_idea_acceptance_coverage,
+            failing_workflow_ids=failing_workflow_ids,
+            failing_idea_criterion_indices=failing_idea_criterion_indices,
+        )
+
+        iteration_record = {
+            "iteration": iteration,
+            "deterministic_errors": deterministic_errors,
+            "blocking_agentic_findings": blocking_agentic_findings,
+            "acceptance_failures": acceptance_failures,
+            "idea_acceptance_failures": idea_acceptance_failures,
+            "repair_sources": repair_sources,
+            "failing_workflow_ids": sorted(failing_workflow_ids),
+            "failing_idea_criterion_indices": sorted(failing_idea_criterion_indices),
+            "protected_sections": protected_sections,
+            "do_not_touch": do_not_touch,
+            "repair_clusters": [
+                {
+                    "cluster_id": cluster["cluster_id"],
+                    "cluster_type": cluster["cluster_type"],
+                    "seam_family": cluster["seam_family"],
+                    "scope": cluster["scope"],
+                    "workflow_ids": list(cluster["workflow_ids"]),
+                    "side_effect_ids": list(cluster["side_effect_ids"]),
+                    "criterion_indices": list(cluster["criterion_indices"]),
+                    "source_types": list(cluster["source_types"]),
+                }
+                for cluster in repair_clusters
+            ],
+            "errors": list(errors),
+        }
+        convergence_state = _validation_convergence_state(
+            idea_acceptance_coverage=pending_idea_acceptance_coverage,
+            deterministic_errors=deterministic_errors,
+            blocking_agentic_findings=blocking_agentic_findings,
+            acceptance_failures=acceptance_failures,
+            idea_acceptance_failures=idea_acceptance_failures,
+        )
+        iteration_record["convergence_state"] = convergence_state
+        validations.append(iteration_record)
+        cluster_iteration_record = {
+            "iteration": iteration,
+            "cluster_execution_mode": "internal_sequential",
+            "clusters": [],
+        }
+        final_repair_clusters_payload = {
+            "idea_id": idea_id or side_effects_artifact.get("idea_id"),
+            "mode": "internal_sequential_clusters",
+            "iterations": cluster_history + [cluster_iteration_record],
+            "latest_iteration": iteration,
+            "unresolved_cluster_ids": [cluster["cluster_id"] for cluster in repair_clusters],
+        }
+        _persist_validate_repair_clusters(
+            repo_root=repo_root,
+            idea_id=idea_id or str(side_effects_artifact.get("idea_id") or "") or None,
+            pipeline_dir=pipeline_dir,
+            payload=final_repair_clusters_payload,
+        )
+
+        final_errors = errors
+        final_idea_acceptance_failures = idea_acceptance_failures
+        if not errors:
+            iteration_record["stop_reason"] = "passed"
+            cluster_history.append(cluster_iteration_record)
+            final_repair_clusters_payload = {
+                "idea_id": idea_id or side_effects_artifact.get("idea_id"),
+                "mode": "internal_sequential_clusters",
+                "iterations": cluster_history,
+                "latest_iteration": iteration,
+                "unresolved_cluster_ids": [],
+            }
+            _persist_validate_repair_clusters(
+                repo_root=repo_root,
+                idea_id=idea_id or str(side_effects_artifact.get("idea_id") or "") or None,
+                pipeline_dir=pipeline_dir,
+                payload=final_repair_clusters_payload,
+            )
+            break
+
+        if prior_convergence_state == convergence_state:
+            iteration_record["stop_reason"] = "converged_without_delta"
+            cluster_history.append(cluster_iteration_record)
+            final_repair_clusters_payload = {
+                "idea_id": idea_id or side_effects_artifact.get("idea_id"),
+                "mode": "internal_sequential_clusters",
+                "iterations": cluster_history,
+                "latest_iteration": iteration,
+                "unresolved_cluster_ids": [cluster["cluster_id"] for cluster in repair_clusters],
+            }
+            _persist_validate_repair_clusters(
+                repo_root=repo_root,
+                idea_id=idea_id or str(side_effects_artifact.get("idea_id") or "") or None,
+                pipeline_dir=pipeline_dir,
+                payload=final_repair_clusters_payload,
+            )
+            break
+
+        prior_convergence_state = convergence_state
+
+        if iteration < max_iterations and repo_root is not None and idea_id is not None:
+            blocking_for_repair = [
+                f for f in list(agentic_review.get("findings") or [])
+                if bool(f.get("blocking")) or str(f.get("severity") or "").lower() in {"error", "blocking", "critical"}
+            ]
+            for cluster_index, cluster in enumerate(repair_clusters, start=1):
+                cluster_workflow_ids = {str(item).strip() for item in (cluster.get("workflow_ids") or []) if str(item).strip()}
+                cluster_criterion_indices = {int(item) for item in (cluster.get("criterion_indices") or []) if int(item) > 0}
+                scoped_workflows = [
+                    dict(workflow)
+                    for workflow in pending
+                    if str(workflow.get("workflow_id") or "") in cluster_workflow_ids
+                ]
+                scoped_coverage = _filter_idea_acceptance_coverage(
+                    idea_acceptance_coverage=pending_idea_acceptance_coverage,
+                    criterion_indices=cluster_criterion_indices,
+                )
+                cluster_protected_sections, cluster_do_not_touch = _build_validate_repair_protected_context(
+                    workflows=pending,
+                    failing_workflow_ids=cluster_workflow_ids,
+                    idea_acceptance_coverage=pending_idea_acceptance_coverage,
+                    failing_idea_criterion_indices=cluster_criterion_indices,
+                )
+                focused_code_evidence = _load_code_evidence_for_workflows(
+                    workflows=[workflow for workflow in pending if str(workflow.get("workflow_id") or "") in cluster_workflow_ids],
+                    code_evidence=code_evidence,
+                    repo_root=repo_root,
+                ) if cluster_workflow_ids else []
+                cluster_context = {
+                    "idea_id": idea_id,
+                    "implemented_idea": implemented_idea or {},
+                    "implemented_stories": implemented_stories,
+                    "enriched_workflows": scoped_workflows,
+                    "idea_acceptance_coverage": scoped_coverage,
+                    "repair_cluster": {
+                        "cluster_id": cluster["cluster_id"],
+                        "cluster_type": cluster["cluster_type"],
+                        "cluster_index": cluster_index,
+                        "cluster_total": len(repair_clusters),
+                        "seam_family": cluster["seam_family"],
+                        "scope": cluster["scope"],
+                        "workflow_ids": sorted(cluster_workflow_ids),
+                        "side_effect_ids": list(cluster.get("side_effect_ids") or []),
+                        "criterion_indices": sorted(cluster_criterion_indices),
+                        "repair_sources": list(cluster.get("repair_sources") or []),
+                        "blocking_findings": list(cluster.get("blocking_findings") or []),
+                        "source_types": list(cluster.get("source_types") or []),
+                    },
+                    "failing_workflows": scoped_workflows,
+                    "failing_idea_acceptance_criteria": [
+                        failure for failure in idea_acceptance_failures
+                        if int(failure.get("criterion_index") or 0) in cluster_criterion_indices
+                    ],
+                    "remaining_failing_workflow_ids": sorted(cluster_workflow_ids),
+                    "remaining_failing_idea_criterion_indices": sorted(cluster_criterion_indices),
+                    "deterministic_errors": [
+                        error for error in deterministic_errors
+                        if any(workflow_id in error for workflow_id in cluster_workflow_ids)
+                        or any(f"[#{criterion_index}]" in error for criterion_index in cluster_criterion_indices)
+                        or (not cluster_workflow_ids and not cluster_criterion_indices)
+                    ] or deterministic_errors,
+                    "blocking_findings": [
+                        finding for finding in blocking_for_repair
+                        if not cluster_workflow_ids or str(finding.get("workflow_id") or "").strip() in cluster_workflow_ids
+                    ] or list(cluster.get("blocking_findings") or []),
+                    "repair_sources": list(cluster.get("repair_sources") or []),
+                    "protected_sections": cluster_protected_sections,
+                    "do_not_touch": cluster_do_not_touch,
+                    "focused_code_evidence": focused_code_evidence,
+                    "source_docs": list(source_docs or []),
+                    "prior_iteration_convergence_state": prior_convergence_state,
+                    "required_repair_delta_ledger": {
+                        "must_state": [
+                            "what verdicts changed",
+                            "what evidence changed",
+                            "what seam was newly resolved",
+                        ],
+                        "stable_criteria_rule": "Do not revisit already-stable criteria unless you can cite a contradiction in the current artifact.",
+                    },
+                    "repair_instruction": "Repair only this internal VEG repair_cluster. Work only on remaining failing workflows and remaining failing idea-acceptance criteria. Preserve protected_sections and obey do_not_touch. Do not rewrite unrelated workflows, do not re-summarize the full artifact, and do not revisit already-stable criteria without citing a contradiction in the current artifact.",
+                }
+                repair_artifact, repair_envelope = integration_agentic.run_integration_agent_step(
+                    repo_root=repo_root,
+                    stage_name="validate_repair",
+                    output_model=VegIdeaAcceptanceBuilderArtifact,
+                    context_payload=cluster_context,
+                    guidance=[],
+                    timeout_seconds=_integration_agent_timeout_seconds(),
+                )
+                if pipeline_dir is not None:
+                    integration_agentic.persist_agent_run(
+                        pipeline_root=pipeline_dir,
+                        node_id=f"{repair_node_id_prefix}_repair_iter{iteration}_cluster{cluster_index}",
+                        envelope=repair_envelope,
+                    )
+                pending = _merge_repaired_workflows(
+                    base_workflows=pending,
+                    repaired_workflows=[item.model_dump() for item in repair_artifact.enriched_workflows],
+                    allowed_workflow_ids=cluster_workflow_ids,
+                    side_effects_artifact=side_effects_artifact,
+                )
+                pending_idea_acceptance_coverage = _merge_repaired_idea_acceptance_coverage(
+                    base_coverage=pending_idea_acceptance_coverage,
+                    repaired_coverage=repair_artifact.idea_acceptance_coverage.model_dump(),
+                    allowed_criterion_indices=cluster_criterion_indices,
+                    canonical_criteria=idea_acceptance_criteria,
+                )
+                latest_cluster_review = repair_artifact.model_dump()
+                cluster_iteration_record["clusters"].append(
+                    {
+                        "cluster_id": cluster["cluster_id"],
+                        "cluster_type": cluster["cluster_type"],
+                        "cluster_index": cluster_index,
+                        "seam_family": cluster["seam_family"],
+                        "scope": cluster["scope"],
+                        "workflow_ids": sorted(cluster_workflow_ids),
+                        "criterion_indices": sorted(cluster_criterion_indices),
+                        "source_types": list(cluster.get("source_types") or []),
+                        "repair_sources": list(cluster.get("repair_sources") or []),
+                        "protected_sections": cluster_protected_sections,
+                        "do_not_touch": cluster_do_not_touch,
+                        "agentic_review_summary": latest_cluster_review.get("summary"),
+                        "model_backed": _idea_acceptance_lineage_is_model_backed((repair_artifact.idea_acceptance_coverage.model_dump() or {}).get("execution_lineage")),
+                        "repair_delta_ledger": (
+                            repair_artifact.repair_delta_ledger.model_dump()
+                            if repair_artifact.repair_delta_ledger is not None
+                            else None
+                        ),
+                    }
+                )
+                agentic_review = latest_cluster_review
+                agentic_findings = list(agentic_review.get("findings") or [])
+                blocking_agentic_findings = [
+                    finding
+                    for finding in agentic_findings
+                    if bool(finding.get("blocking")) or str(finding.get("severity") or "").lower() in {"error", "blocking", "critical"}
+                ]
+                final_repair_clusters_payload = {
+                    "idea_id": idea_id or side_effects_artifact.get("idea_id"),
+                    "mode": "internal_sequential_clusters",
+                    "iterations": cluster_history + [cluster_iteration_record],
+                    "latest_iteration": iteration,
+                    "unresolved_cluster_ids": [item["cluster_id"] for item in repair_clusters[cluster_index:]],
+                }
+                _persist_validate_repair_clusters(
+                    repo_root=repo_root,
+                    idea_id=idea_id or str(side_effects_artifact.get("idea_id") or "") or None,
+                    pipeline_dir=pipeline_dir,
+                    payload=final_repair_clusters_payload,
+                )
+
+        cluster_history.append(cluster_iteration_record)
+        final_repair_clusters_payload = {
+            "idea_id": idea_id or side_effects_artifact.get("idea_id"),
+            "mode": "internal_sequential_clusters",
+            "iterations": cluster_history,
+            "latest_iteration": iteration,
+            "unresolved_cluster_ids": [],
+        }
+        _persist_validate_repair_clusters(
+            repo_root=repo_root,
+            idea_id=idea_id or str(side_effects_artifact.get("idea_id") or "") or None,
+            pipeline_dir=pipeline_dir,
+            payload=final_repair_clusters_payload,
+        )
+
+    return {
+        "idea_id": side_effects_artifact.get("idea_id"),
+        "passed": not final_errors,
+        "iterations_used": iterations_used,
+        "max_iterations": max_iterations,
+        "stop_reason": str((validations[-1] or {}).get("stop_reason") or ("passed" if not final_errors else "max_iterations_exhausted")) if validations else "not_started",
+        "checks": {
+            "all_implicated_users_covered": not any("all implicated users covered" in error for error in final_errors),
+            "all_side_effects_covered": not any("missing workflows for side effects" in error for error in final_errors),
+            "story_alignment": not any("story alignment" in error for error in final_errors),
+            "code_alignment": not any("code alignment" in error for error in final_errors),
+            "interaction_points_complete": not any("interaction points missing" in error for error in final_errors),
+            "acceptance_criteria_covered": not any("acceptance criteria uncovered" in error for error in final_errors),
+            "acceptance_criteria_have_seams": not any("acceptance criterion missing seam" in error for error in final_errors),
+            "idea_acceptance_criteria_covered": not any("idea acceptance criterion uncovered" in error for error in final_errors),
+            "idea_acceptance_criteria_proven": not any("idea acceptance criterion under-proven" in error or "idea acceptance criterion drift" in error for error in final_errors),
+            "idea_acceptance_builder_model_backed": not any("idea acceptance builder lineage missing model-backed proof" in error for error in final_errors),
+            "no_invalid_actors_admitted": not any("invalid actors admitted" in error for error in final_errors),
+            "agentic_review_clear": not blocking_agentic_findings,
+        },
+        "agentic_review": {
+            "summary": agentic_review.get("summary"),
+            "findings": agentic_findings,
+            "blocking_findings": blocking_agentic_findings,
+            "enriched_workflow_count": len(agentic_review.get("enriched_workflows") or pending),
+        },
+        "idea_acceptance_coverage": pending_idea_acceptance_coverage,
+        "acceptance_criteria": {
+            "idea_count": len(idea_acceptance_criteria),
+            "story_count": sum(len(item.get("acceptance_criteria") or []) for item in story_acceptance.values()),
+            "story_ids_with_acceptance": sorted(story_acceptance.keys()),
+            "failing_idea_criterion_indices": sorted({int(item.get("criterion_index") or 0) for item in final_idea_acceptance_failures if int(item.get("criterion_index") or 0) > 0}),
+        },
+        "validation_history": validations,
+        "errors": final_errors,
+        "next_stages": [stage.node_id for stage in default_integration_stages()[3:]],
+        "_final_workflows": pending,
+        "_full_agentic_review": agentic_review,
+        "_repair_clusters": final_repair_clusters_payload,
+    }, iterations_used
+
+def run_integration_dag(
+    *,
+    repo_root: Path,
+    idea_id: str,
+    implemented_idea: dict[str, Any],
+    implemented_stories: list[dict[str, Any]],
+    code_evidence: list[dict[str, Any]] | None = None,
+    source_docs: list[dict[str, Any]] | None = None,
+    project_id: str | None = None,
+    dag_run_id: str | None = None,
+) -> IntegrationDagResult:
+    code_evidence = list(code_evidence or [])
+    source_docs = list(source_docs or [])
+    resume_freshness = _compute_integration_freshness(
+        repo_root=repo_root,
+        idea_id=idea_id,
+        payload_body={
+            "idea_id": idea_id,
+            "implemented_idea": implemented_idea,
+            "implemented_stories": implemented_stories,
+            "code_evidence": code_evidence,
+            "source_docs": source_docs,
+        },
+    )
+    runs_parent = _integration_runs_dir(repo_root, idea_id)
+    runs_parent.mkdir(parents=True, exist_ok=True)
+    pipeline_dir = runs_parent / f"run_{uuid.uuid4().hex[:12]}"
+    pipeline_dir.mkdir(parents=True, exist_ok=True)
+
+    # Detect most useful prior run for checkpoint/resume
+    prior_run_dir = _select_prior_run_dir(
+        runs_parent,
+        pipeline_dir,
+        fallback_runs_parent=_legacy_integration_runs_dir(repo_root, idea_id),
+        expected_fingerprint=str(resume_freshness.get("fingerprint") or "") or None,
+    )
+
+    wf = IntegrationWorkflow()
+    ctx = wf.run({
+        "repo_root": str(repo_root),
+        "idea_id": idea_id,
+        "implemented_idea": implemented_idea,
+        "implemented_stories": implemented_stories,
+        "code_evidence": code_evidence,
+        "source_docs": source_docs,
+        "pipeline_dir": str(pipeline_dir),
+        "prior_run_dir": str(prior_run_dir) if prior_run_dir else None,
+        "resume_freshness": resume_freshness,
+        "project_id": project_id,
+        "dag_run_id": dag_run_id,
+    })
+
+    artifacts = dict(ctx.metadata.get("artifacts") or {})
+    validation_report = dict(ctx.metadata.get("validation_report") or {})
+    iterations_used = int(ctx.metadata.get("iterations_used") or 0)
+    if ctx.metadata.get("structural_only"):
+        return IntegrationDagResult(
+            exit_code=0,
+            message="integration dag complete; structural-only idea (no integration seams)\n",
+            pipeline_dir=pipeline_dir,
+            artifacts=artifacts,
+            iterations_used=iterations_used,
+        )
+    if not ctx.should_stop:
+        return IntegrationDagResult(
+            exit_code=0,
+            message="integration dag complete; downstream red/redreview/green/greenenrich/commit artifacts written\n",
+            pipeline_dir=pipeline_dir,
+            artifacts=artifacts,
+            iterations_used=iterations_used,
+        )
+    return IntegrationDagResult(
+        exit_code=1,
+        message="integration dag failed\n",
+        pipeline_dir=pipeline_dir,
+        artifacts=artifacts,
+        iterations_used=iterations_used,
+    )
+
+
+def backfill_integration_current(*, repo_root: Path, idea_id: str) -> dict[str, Any]:
+    current_dir = _integration_current_dir(repo_root, idea_id)
+    current_dir.mkdir(parents=True, exist_ok=True)
+    runs_dir = _integration_runs_dir(repo_root, idea_id)
+    legacy_runs_dir = _legacy_integration_runs_dir(repo_root, idea_id)
+    payload = json.loads(prepare_integration_payload(repo_root=repo_root, idea_id=idea_id).read_text(encoding="utf-8"))
+    resume_freshness = _compute_integration_freshness(
+        repo_root=repo_root,
+        idea_id=idea_id,
+        payload_body=_payload_body_without_freshness(payload),
+    )
+    selected = _select_prior_run_dir(
+        runs_dir,
+        current_dir / "_ignore",
+        fallback_runs_parent=legacy_runs_dir,
+        expected_fingerprint=str(resume_freshness.get("fingerprint") or "") or None,
+    )
+    copied: list[str] = []
+    if selected is None:
+        return {
+            "idea_id": idea_id,
+            "selected_run": None,
+            "current_dir": str(current_dir),
+            "copied": copied,
+        }
+    for path in sorted(selected.iterdir()):
+        if not path.is_file() or path.name.endswith("_agent_run.json"):
+            continue
+        target = current_dir / path.name
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except Exception:
+            continue
+        _write_json(target, data)
+        copied.append(path.name)
+    _write_resume_metadata(current_dir, resume_freshness)
+    return {
+        "idea_id": idea_id,
+        "selected_run": str(selected),
+        "current_dir": str(current_dir),
+        "copied": copied,
+    }
+
+
+def _describe_postgrest_exception(exc: Exception) -> str:
+    if isinstance(exc, HTTPError):
+        try:
+            body = exc.read().decode("utf-8", errors="replace").strip()
+        except Exception:
+            body = ""
+        if body:
+            return f"HTTP {exc.code}: {body}"
+        return f"HTTP {exc.code}: {exc.reason}"
+    return str(exc) or exc.__class__.__name__
+
+
+def _sync_integration_to_supabase(
+    *,
+    idea_id: str,
+    project_id: str,
+    run_id: str,
+    repo_root: Path | None = None,
+    result: IntegrationDagResult | None = None,
+    status: str = "running",
+) -> None:
+    config = _resolve_supabase_rest_config()
+    if config is None:
+        return
+    if not project_id or project_id.startswith("unregistered:"):
+        return
+    url, key = config
+    resolved_project_id = str(project_id or "").strip()
+    if not _is_uuid_like(resolved_project_id):
+        if repo_root is None:
+            project_entry = resolve_project_entry(project_id)
+            repo_root_value = str((project_entry or {}).get("repo_root") or "").strip()
+            if repo_root_value:
+                repo_root = Path(repo_root_value).expanduser()
+        if repo_root is None:
+            logger.warning(
+                "integration-supabase-sync: skipping sync for idea_id=%s run_id=%s because local project_id=%s is not canonical and repo_root is unavailable",
+                idea_id,
+                run_id,
+                project_id,
+            )
+            return
+        project_entry = find_project_for_repo_root(repo_root)
+        remote_url = str((project_entry or {}).get("remote_url") or "").strip() or None
+        project_name = str((project_entry or {}).get("name") or "").strip() or None
+        owner, repo = _infer_owner_repo(remote_url, repo_root, project_name)
+        try:
+            resolved_project_id = _lookup_supabase_project_uuid(
+                url=url,
+                key=key,
+                repo_root=repo_root,
+                remote_url=remote_url,
+                owner=owner,
+                repo=repo,
+            ) or ""
+        except Exception as exc:
+            logger.warning(
+                "integration-supabase-sync: skipping sync for idea_id=%s run_id=%s because canonical project UUID lookup failed for local project_id=%s: %s",
+                idea_id,
+                run_id,
+                project_id,
+                exc,
+            )
+            return
+        if not _is_uuid_like(resolved_project_id):
+            logger.warning(
+                "integration-supabase-sync: skipping sync for idea_id=%s run_id=%s because canonical project UUID could not be resolved from local project_id=%s",
+                idea_id,
+                run_id,
+                project_id,
+            )
+            return
+    from datetime import UTC, datetime
+
+    now = datetime.now(UTC).isoformat()
+
+    def _load_artifact(key_name: str) -> dict[str, Any] | None:
+        if result is None:
+            return None
+        path_str = result.artifacts.get(key_name)
+        if not path_str:
+            return None
+        p = Path(path_str)
+        if not p.exists():
+            return None
+        try:
+            return json.loads(p.read_text(encoding="utf-8"))
+        except Exception:
+            return None
+
+    side_effects = _load_artifact("side_effects")
+    implicated_users = _load_artifact("implicated_users")
+    workflow_inventory = _load_artifact("workflow_inventory")
+    validation_report = _load_artifact("validation_gate")
+    red_package = _load_artifact("red_package")
+    red_review = _load_artifact("red_review")
+    green_package = _load_artifact("green_package")
+    green_enrich = _load_artifact("green_enrich")
+    commit_package = _load_artifact("commit_package")
+
+    side_effect_count = len((side_effects or {}).get("side_effects") or []) if side_effects else 0
+    workflow_count = len((workflow_inventory or {}).get("workflow_ids") or []) if workflow_inventory else 0
+
+    effective_status = status
+    if validation_report and validation_report.get("structural_only"):
+        effective_status = "structural_only"
+
+    row = {
+        "idea_id": idea_id,
+        "project_id": resolved_project_id,
+        "run_id": run_id,
+        "pipeline_dir": str(result.pipeline_dir) if result is not None else None,
+        "status": effective_status,
+        "exit_code": result.exit_code if result is not None else None,
+        "iterations_used": result.iterations_used if result is not None else None,
+        "workflow_count": workflow_count,
+        "side_effect_count": side_effect_count,
+        "side_effects": side_effects,
+        "implicated_users": implicated_users,
+        "workflow_inventory": workflow_inventory,
+        "validation_report": validation_report,
+        "red_package": red_package,
+        "red_review": red_review,
+        "green_package": green_package,
+        "green_enrich": green_enrich,
+        "commit_package": commit_package,
+        "failure_message": result.message if (result is not None and result.exit_code != 0) else None,
+        "updated_at": now,
+    }
+    try:
+        _postgrest_request(
+            method="POST",
+            url=f"{url}/rest/v1/devflow_idea_integrations?on_conflict=idea_id",
+            key=key,
+            body=[row],
+            prefer="resolution=merge-duplicates",
+        )
+    except Exception as exc:
+        logger.warning(
+            "integration-supabase-sync: failed for idea_id=%s run_id=%s status=%s project_id=%s row_keys=%s error=%s",
+            idea_id,
+            run_id,
+            effective_status,
+            resolved_project_id,
+            sorted(row.keys()),
+            _describe_postgrest_exception(exc),
+        )