devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/story/validate_tests_story.py

@@ -0,0 +1,512 @@
+#!/usr/bin/env python3
+"""Story-scoped deterministic validation for contract tests.
+
+This is intentionally a *scoped* variant of scripts/validate_tests.py.
+
+Constraints:
+- Offline + deterministic
+- Static analysis only (no pytest execution required)
+- Does NOT modify or depend on the behavior of validate_tests.py
+
+Exit codes:
+  0 = OK
+  2 = Validation failed (issues found)
+
+What it validates (scoped to one story_id):
+- Tests for this story must include coherent marker triple:
+  - @pytest.mark.story_id("...")
+  - @pytest.mark.story_uuid("...")
+  - @pytest.mark.plane("...")
+- The story_id must exist in canonical story docs.
+- story_uuid markers must match the canonical story uuid.
+- Plane coverage must include each required plane declared in the story contract.
+- Anti-patterns (best-effort heuristics) within tests for this story.
+
+Note: It does NOT attempt repo-wide coverage; that remains the job of validate_tests.py.
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import json
+import re
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Iterable
+
+from devflow_engine.story.markdown_contracts import parse_story_contracts_from_markdown
+
+
+MARK_STORY_ID_RE = re.compile(r"(?:@)?pytest\.mark\.story_id\(([^\)]+)\)")
+MARK_STORY_UUID_RE = re.compile(r"(?:@)?pytest\.mark\.story_uuid\(([^\)]+)\)")
+MARK_PLANE_RE = re.compile(r"(?:@)?pytest\.mark\.plane\(([^\)]+)\)")
+COMMENT_STORY_ID_RE = re.compile(r"@story_id:\s*([^\s]+)")
+COMMENT_STORY_UUID_RE = re.compile(r"@story_uuid:\s*([^\s]+)")
+COMMENT_PLANE_RE = re.compile(r"@plane:\s*([^\s]+)")
+PY_CONST_RE = re.compile(r'^([A-Z_][A-Z0-9_]*)\s*=\s*["\']([^"\']+)["\']\s*$')
+DEF_TEST_RE = re.compile(r"^def\s+(test_[a-zA-Z0-9_]+)\s*\(")
+JS_TEST_RE = re.compile(r"\b(it|test)\s*\(")
+
+MOCK_ASSERT_RE = re.compile(
+    r"assert\s+.*\.(called|call_count|assert_called|assert_called_once|assert_called_with|mock_calls)\b"
+)
+MOCK_IMPORT_RE = re.compile(r"from\s+unittest\.mock\s+import\s+|import\s+unittest\.mock")
+PATCH_RE = re.compile(r"\bpatch\(")
+TEST_FILE_SUFFIXES = {".py", ".js", ".ts", ".jsx", ".tsx", ".mjs", ".cjs"}
+FORBIDDEN_COMPLETE_DROP_RESET_PATTERNS: tuple[tuple[str, re.Pattern[str]], ...] = (
+    ("DROP SCHEMA", re.compile(r"\bDROP\s+SCHEMA\b", re.IGNORECASE)),
+    ("DROP DATABASE", re.compile(r"\bDROP\s+DATABASE\b", re.IGNORECASE)),
+    ("DROP OWNED BY", re.compile(r"\bDROP\s+OWNED\s+BY\b", re.IGNORECASE)),
+    ("DROP ALL TABLES", re.compile(r"\bDROP\s+TABLES?\b", re.IGNORECASE)),
+    (
+        "metadata.drop_all",
+        re.compile(r"\b(?:[A-Za-z_][A-Za-z0-9_]*\.)?metadata\.drop_all\s*\(", re.IGNORECASE),
+    ),
+    ("db.drop_all", re.compile(r"\bdb\.drop_all\s*\(", re.IGNORECASE)),
+)
+REWRITE_REQUIRED_CODES = {
+    "forbidden_complete_drop_reset_pattern",
+    "invalid_python_test_file",
+}
+
+
+@dataclass(frozen=True)
+class Issue:
+    code: str
+    message: str
+    path: str
+    line: int | None = None
+    context: str | None = None
+
+
+def _iter_story_files(user_stories_dir: Path) -> Iterable[Path]:
+    for p in sorted(user_stories_dir.rglob("*.md")):
+        if p.name.startswith("."):
+            continue
+        yield p
+
+
+def _iter_story_json_files(repo_root: Path) -> Iterable[Path]:
+    ideas_root = repo_root / ".devflow" / "ideas"
+    if not ideas_root.exists():
+        return []
+    return sorted(ideas_root.glob("*/devflow_story_sets/*/story_*.json"))
+
+
+def _load_story_from_json(repo_root: Path, story_id: str) -> dict[str, object] | None:
+    for p in _iter_story_json_files(repo_root):
+        try:
+            payload = json.loads(p.read_text("utf-8"))
+        except Exception:
+            continue
+        if str(payload.get("story_id") or "") != story_id:
+            continue
+        return {
+            "story_id": str(payload.get("story_id") or ""),
+            "story_uuid": str(payload.get("story_uuid") or ""),
+            "required_planes": [str(x) for x in (payload.get("required_planes") or [])],
+            "path": str(p),
+            "source_kind": "compiled_story_json",
+        }
+    return None
+
+
+def _load_story_from_markdown(user_stories_dir: Path, story_id: str) -> dict[str, object] | None:
+    for p in _iter_story_files(user_stories_dir):
+        md = p.read_text("utf-8")
+        blocks = parse_story_contracts_from_markdown(md, source_path=str(p))
+        for b in blocks:
+            c = b.contract
+            if c.story_id == story_id:
+                return {
+                    "story_id": c.story_id,
+                    "story_uuid": c.story_uuid,
+                    "required_planes": list(c.required_planes or []),
+                    "path": str(p),
+                    "source_kind": "canonical_markdown",
+                }
+    return None
+
+
+def _load_story(repo_root: Path, user_stories_dir: Path, story_id: str) -> dict[str, object] | None:
+    story = _load_story_from_json(repo_root, story_id)
+    if story is not None:
+        return story
+    return _load_story_from_markdown(user_stories_dir, story_id)
+
+
+def _resolve_marker_value(raw: str, constants: dict[str, str]) -> str | None:
+    token = raw.strip()
+    if token.startswith(('"', "'")) and token.endswith(('"', "'")) and len(token) >= 2:
+        return token[1:-1]
+    return constants.get(token)
+
+
+def _iter_candidate_test_files(root: Path) -> Iterable[Path]:
+    if root.is_file():
+        if root.name.startswith(".") or root.suffix not in TEST_FILE_SUFFIXES:
+            return []
+        return [root]
+    if not root.exists() or not root.is_dir():
+        return []
+    files: list[Path] = []
+    for p in sorted(root.rglob("*")):
+        if p.name.startswith(".") or not p.is_file() or p.suffix not in TEST_FILE_SUFFIXES:
+            continue
+        files.append(p)
+    return files
+
+
+def _resolve_test_files(*, repo_root: Path, tests_dir: Path, test_paths: list[str] | None) -> list[Path]:
+    if not test_paths:
+        return list(_iter_candidate_test_files(tests_dir))
+
+    seen: set[Path] = set()
+    resolved: list[Path] = []
+    for raw_path in test_paths:
+        candidate_root = Path(raw_path)
+        if not candidate_root.is_absolute():
+            candidate_root = repo_root / candidate_root
+        for candidate in _iter_candidate_test_files(candidate_root.resolve()):
+            normalized = candidate.resolve()
+            if normalized in seen:
+                continue
+            seen.add(normalized)
+            resolved.append(normalized)
+    return resolved
+
+
+def _find_forbidden_complete_drop_reset_issue(*, path: str, text: str) -> Issue | None:
+    for line_number, line in enumerate(text.splitlines(), start=1):
+        stripped = line.strip()
+        if stripped.startswith(("#", "//")):
+            continue
+        for label, pattern in FORBIDDEN_COMPLETE_DROP_RESET_PATTERNS:
+            if not pattern.search(line):
+                continue
+            return Issue(
+                code="forbidden_complete_drop_reset_pattern",
+                message=(
+                    "Forbidden complete-drop reset pattern detected in story-scoped Red tests "
+                    f"({label}). Rewrite required: replace destructive reset logic with story-scoped setup/cleanup."
+                ),
+                path=path,
+                line=line_number,
+                context=line.strip()[:200],
+            )
+    return None
+
+
+def _validate_python_test_file(*, path: str, text: str) -> Issue | None:
+    try:
+        module = ast.parse(text, filename=path)
+        compile(module, path, "exec")
+    except SyntaxError as exc:
+        return Issue(
+            code="invalid_python_test_file",
+            message=(
+                "Python story-scoped test file is not parseable/compilable. "
+                f"Rewrite required before Red can proceed: {exc.msg}."
+            ),
+            path=path,
+            line=exc.lineno,
+            context=(exc.text or "").strip()[:200] or None,
+        )
+    except ValueError as exc:
+        return Issue(
+            code="invalid_python_test_file",
+            message=(
+                "Python story-scoped test file failed deterministic compile validation. "
+                f"Rewrite required before Red can proceed: {exc}."
+            ),
+            path=path,
+            context=str(exc)[:200] or None,
+        )
+    return None
+
+
+def _scan_tests_for_story(
+    test_files: Iterable[Path],
+    story_id: str,
+    *,
+    explicitly_scoped_paths: bool = False,
+) -> tuple[list[Issue], set[str], set[str]]:
+    issues: list[Issue] = []
+    planes_seen: set[str] = set()
+    uuids_seen: set[str] = set()
+
+    for p in sorted(test_files):
+        rel = str(p)
+        text = p.read_text("utf-8")
+        lines = text.splitlines()
+        constants: dict[str, str] = {}
+        story_scoped_candidate = explicitly_scoped_paths or story_id in text
+        if p.suffix == ".py" and story_scoped_candidate:
+            invalid_python_issue = _validate_python_test_file(path=rel, text=text)
+            if invalid_python_issue is not None:
+                issues.append(invalid_python_issue)
+                continue
+        if story_id in text:
+            forbidden_reset_issue = _find_forbidden_complete_drop_reset_issue(path=rel, text=text)
+            if forbidden_reset_issue is not None:
+                issues.append(forbidden_reset_issue)
+        for line in lines:
+            m_const = PY_CONST_RE.match(line.strip())
+            if m_const:
+                constants[m_const.group(1)] = m_const.group(2)
+
+        current_story_id: str | None = None
+        current_story_uuid: str | None = None
+        current_planes: set[str] = set()
+        current_has_target_story = False
+
+        def flush(boundary_line: int) -> None:
+            nonlocal current_story_id, current_story_uuid, current_planes, current_has_target_story
+            if not current_has_target_story:
+                current_story_id = None
+                current_story_uuid = None
+                current_planes = set()
+                current_has_target_story = False
+                return
+
+            if current_story_id is None:
+                issues.append(
+                    Issue(
+                        code="missing_story_id_marker",
+                        message=f'Test for story {story_id!r} is missing @pytest.mark.story_id("...") marker.',
+                        path=rel,
+                        line=boundary_line,
+                    )
+                )
+            if current_story_uuid is None:
+                issues.append(
+                    Issue(
+                        code="missing_story_uuid_marker",
+                        message=f'Test for story {story_id!r} is missing @pytest.mark.story_uuid("...") marker.',
+                        path=rel,
+                        line=boundary_line,
+                    )
+                )
+            if not current_planes:
+                issues.append(
+                    Issue(
+                        code="missing_plane_marker",
+                        message=f'Test for story {story_id!r} is missing @pytest.mark.plane("...") marker.',
+                        path=rel,
+                        line=boundary_line,
+                    )
+                )
+
+            if current_story_uuid is not None:
+                uuids_seen.add(current_story_uuid)
+            planes_seen.update(current_planes)
+
+            current_story_id = None
+            current_story_uuid = None
+            current_planes = set()
+            current_has_target_story = False
+
+        if story_id in text and (MOCK_IMPORT_RE.search(text) or PATCH_RE.search(text)):
+            for i, line in enumerate(lines, start=1):
+                if MOCK_ASSERT_RE.search(line):
+                    issues.append(
+                        Issue(
+                            code="testing_anti_pattern_mock_assertion",
+                            message=(
+                                "Possible anti-pattern: asserting on mock call behavior "
+                                "(tests should verify real behavior, not that mocks were called)."
+                            ),
+                            path=rel,
+                            line=i,
+                            context=line.strip()[:200],
+                        )
+                    )
+
+        for i, line in enumerate(lines, start=1):
+            m_id = MARK_STORY_ID_RE.search(line)
+            if m_id:
+                resolved = _resolve_marker_value(m_id.group(1), constants)
+                if resolved is not None:
+                    current_story_id = resolved
+                    current_has_target_story = current_story_id == story_id
+            else:
+                c_id = COMMENT_STORY_ID_RE.search(line)
+                if c_id:
+                    current_story_id = c_id.group(1)
+                    current_has_target_story = current_story_id == story_id
+
+            m_uuid = MARK_STORY_UUID_RE.search(line)
+            if m_uuid:
+                resolved = _resolve_marker_value(m_uuid.group(1), constants)
+                if resolved is not None:
+                    current_story_uuid = resolved
+            else:
+                c_uuid = COMMENT_STORY_UUID_RE.search(line)
+                if c_uuid:
+                    current_story_uuid = c_uuid.group(1)
+
+            for m_plane in MARK_PLANE_RE.finditer(line):
+                resolved = _resolve_marker_value(m_plane.group(1), constants)
+                if resolved is not None:
+                    current_planes.add(resolved)
+            if not MARK_PLANE_RE.search(line):
+                c_plane = COMMENT_PLANE_RE.search(line)
+                if c_plane:
+                    current_planes.add(c_plane.group(1))
+
+            stripped = line.strip()
+            if DEF_TEST_RE.match(stripped) or JS_TEST_RE.search(stripped):
+                flush(i)
+
+        flush(len(lines) if lines else 1)
+
+    return issues, planes_seen, uuids_seen
+
+
+def validate(
+    *,
+    repo_root: Path,
+    story_id: str,
+    test_paths: list[str] | None = None,
+    plane_scope: list[str] | None = None,
+) -> tuple[int, list[Issue]]:
+    """Validate contract tests scoped to a single story_id.
+
+    Args:
+        plane_scope: When provided, restricts the orphan_plane_coverage check to
+            only these planes instead of the full story.required_planes list.
+            Use this when validating a single bundle in a multi-plane story so that
+            sibling bundles' planes do not cause spurious repair triggers.
+    """
+    user_stories_dir = repo_root / "ai_docs" / "context" / "v2" / "project_docs" / "user_stories"
+    tests_dir = repo_root / "tests"
+
+    issues: list[Issue] = []
+
+    story = _load_story(repo_root, user_stories_dir, story_id)
+    if story is None:
+        issues.append(
+            Issue(
+                code="unknown_story_id",
+                message=f"story_id {story_id!r} does not exist in canonical story docs.",
+                path=str(user_stories_dir),
+            )
+        )
+        return 2, issues
+
+    resolved_test_files = _resolve_test_files(repo_root=repo_root, tests_dir=tests_dir, test_paths=test_paths)
+    scan_issues, planes_seen, uuids_seen = _scan_tests_for_story(
+        resolved_test_files,
+        story_id,
+        explicitly_scoped_paths=bool(test_paths),
+    )
+    issues.extend(scan_issues)
+
+    expected_uuid = str(story.get("story_uuid") or "")
+    if expected_uuid and uuids_seen and expected_uuid not in uuids_seen:
+        issues.append(
+            Issue(
+                code="story_uuid_mismatch",
+                message=(
+                    f"Tests for story_id {story_id!r} declare story_uuid(s) {sorted(uuids_seen)!r} "
+                    f"but story doc uuid is {expected_uuid!r}."
+                ),
+                path=str(tests_dir if not test_paths else repo_root),
+            )
+        )
+
+    # When plane_scope is provided (per-bundle validation), only check the planes
+    # owned by this bundle. This prevents spurious orphan_plane_coverage failures
+    # when sibling bundles are still running in parallel and haven't written their
+    # tests yet. Full cross-plane coverage is verified at the story-level
+    # reconciliation step after all bundles complete.
+    story_required = [str(p) for p in (story.get("required_planes") or [])]
+    if plane_scope is not None:
+        required = [p for p in story_required if p in plane_scope]
+    else:
+        required = story_required
+    missing_planes = [p for p in required if p not in planes_seen]
+    if missing_planes:
+        issues.append(
+            Issue(
+                code="orphan_plane_coverage",
+                message=(
+                    f"Orphan plane coverage: story_id {story_id!r} requires plane(s) {missing_planes!r} "
+                    f"but tests only cover {sorted(planes_seen)!r}."
+                ),
+                path=str(story.get("path") or user_stories_dir),
+            )
+        )
+
+    exit_code = 0 if not issues else 2
+    return exit_code, issues
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Validate contract tests scoped to a single story_id")
+    ap.add_argument("story_id", help="Story id (e.g. DF2-IMPL-620)")
+    ap.add_argument(
+        "--repo-root",
+        default=".",
+        help="Path to devflow_engine repo root (default: inferred)",
+    )
+    ap.add_argument(
+        "--json",
+        dest="json_path",
+        default=None,
+        help="Write JSON report to path",
+    )
+    ap.add_argument(
+        "--test-path",
+        dest="test_paths",
+        action="append",
+        default=None,
+        help="Explicit test file/directory to scan (repeatable). Defaults to repo_root/tests when omitted.",
+    )
+    ap.add_argument(
+        "--plane",
+        dest="plane_scope",
+        action="append",
+        default=None,
+        help=(
+            "Restrict orphan_plane_coverage check to these planes only (repeatable). "
+            "Use when validating a single bundle in a multi-plane story to avoid "
+            "spurious failures while sibling bundles are still running."
+        ),
+    )
+    args = ap.parse_args()
+
+    repo_root = Path(args.repo_root).resolve()
+    code, issues = validate(
+        repo_root=repo_root,
+        story_id=str(args.story_id),
+        test_paths=args.test_paths,
+        plane_scope=args.plane_scope,
+    )
+
+    if args.json_path:
+        rewrite_required = any(i.code in REWRITE_REQUIRED_CODES for i in issues)
+        out = {
+            "story_id": str(args.story_id),
+            "issue_count": len(issues),
+            "issues": [asdict(i) for i in issues],
+            "errors": [asdict(i) for i in issues],
+            "outcome": "failed" if issues else "ok",
+            "rewrite_required": rewrite_required,
+        }
+        Path(args.json_path).write_text(json.dumps(out, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+    if issues:
+        print(f"STORY TEST VALIDATION FAILED: {len(issues)} issue(s)")
+        for i in issues:
+            loc = f"{i.path}:{i.line}" if i.line else i.path
+            print(f"- {i.code}: {loc}: {i.message}")
+        return 2
+
+    print("ok")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

devflow_engine/story/validation.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .discovery import get_story_source_paths
+from .markdown_contracts import MANDATORY_CONTRACT_FORMATION_MODE_LINE, parse_story_contracts_from_markdown
+from .markdown_contracts import is_uuid4
+
+
+@dataclass(frozen=True)
+class StoryValidationDiagnostic:
+    level: str  # "error" | "warning"
+    code: str
+    message: str
+    path: str
+
+
+@dataclass(frozen=True)
+class StoryValidationResult:
+    ok: bool
+    diagnostics: list[StoryValidationDiagnostic]
+
+
+_REQUIRED_HEADER_KEYS: list[str] = ["story_uuid", "story_id", "title", "required_planes"]
+_REQUIRED_SECTIONS: list[str] = ["Intent", "Scope", "Acceptance criteria", "Contract test specs"]
+
+
+def _has_header_key(raw_text: str, key: str) -> bool:
+    # Search line-start key with optional whitespace.
+    prefix = f"{key}:"
+    for ln in raw_text.splitlines():
+        if ln.strip().startswith(prefix):
+            return True
+    return False
+
+
+def _has_section(raw_text: str, section_name: str) -> bool:
+    needle = f"## {section_name}"
+    return any(ln.strip() == needle for ln in raw_text.splitlines())
+
+
+def validate_story_sources(repo_root: Path) -> StoryValidationResult:
+    """Validate all story sources in repo.
+
+    Area 4 contract differences vs low-level contract validator:
+    - missing plane_oracles is a WARNING (recommended), not a hard error
+    - required markdown sections must exist (Intent/Scope/Acceptance criteria/Contract test specs)
+
+    Returns a result object with stable diagnostic codes.
+    """
+
+    repo_root = Path(repo_root)
+    diags: list[StoryValidationDiagnostic] = []
+
+    for p in get_story_source_paths(repo_root):
+        text = p.read_text(encoding="utf-8")
+        blocks = parse_story_contracts_from_markdown(text, source_path=str(p))
+        if not blocks:
+            diags.append(
+                StoryValidationDiagnostic(
+                    level="error",
+                    code="NO_STORY_BLOCKS",
+                    message="No story_uuid blocks found in markdown",
+                    path=str(p),
+                )
+            )
+            continue
+
+        for b in blocks:
+            c = b.contract
+            raw = c.raw_text
+            base_path = f"{c.source_path}:{b.start_line}"
+
+            # Header keys must be present in source text (not just parse output).
+            for k in _REQUIRED_HEADER_KEYS:
+                if not _has_header_key(raw, k):
+                    diags.append(
+                        StoryValidationDiagnostic(
+                            level="error",
+                            code=f"MISSING_HEADER_KEY:{k}",
+                            message=f"Missing required header key: {k}",
+                            path=base_path,
+                        )
+                    )
+
+            # UUID validity
+            if c.story_uuid and not is_uuid4(c.story_uuid):
+                diags.append(
+                    StoryValidationDiagnostic(
+                        level="error",
+                        code="INVALID_UUID",
+                        message="story_uuid must be a uuid-v4 string",
+                        path=f"{base_path}:story_uuid",
+                    )
+                )
+
+            # Contract formation mode line must be present.
+            if MANDATORY_CONTRACT_FORMATION_MODE_LINE not in raw:
+                diags.append(
+                    StoryValidationDiagnostic(
+                        level="error",
+                        code="MISSING_CONTRACT_FORMATION_MODE_LINE",
+                        message="Missing mandatory contract formation mode line",
+                        path=base_path,
+                    )
+                )
+
+            # Required sections
+            for sec in _REQUIRED_SECTIONS:
+                if not _has_section(raw, sec):
+                    diags.append(
+                        StoryValidationDiagnostic(
+                            level="error",
+                            code=f"MISSING_SECTION:{sec}",
+                            message=f"Missing required section: {sec}",
+                            path=base_path,
+                        )
+                    )
+
+            # plane_oracles recommended (warning)
+            if "plane_oracles:" not in raw:
+                diags.append(
+                    StoryValidationDiagnostic(
+                        level="warning",
+                        code="MISSING_RECOMMENDED_FIELD:plane_oracles",
+                        message="Recommended field plane_oracles is missing",
+                        path=f"{base_path}:plane_oracles",
+                    )
+                )
+
+    ok = not any(d.level == "error" for d in diags)
+    return StoryValidationResult(ok=ok, diagnostics=diags)

devflow_engine/ui_grounding/__init__.py

@@ -0,0 +1,11 @@
+from .dag import DAG_ID, UIGroundingDagResult, run_ui_grounding_dag
+from .pencil_bridge import PencilPreflightArtifact, PencilPreflightResult, run_pencil_preflight
+
+__all__ = [
+    "DAG_ID",
+    "UIGroundingDagResult",
+    "PencilPreflightArtifact",
+    "PencilPreflightResult",
+    "run_pencil_preflight",
+    "run_ui_grounding_dag",
+]

devflow_engine/ui_grounding/agentic.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel
+
+from ..agentic_prompts import load_agentic_prompt_lines
+from ..agentic_runtime import AgentRunEnvelope, run_agent_step
+
+
+UI_GROUNDING_DOCTRINE = load_agentic_prompt_lines("ui_grounding_doctrine")
+
+
+def run_ui_grounding_agent_step(*, repo_root: Path, stage_name: str, output_model: type[BaseModel], context_payload: dict[str, Any], guidance: list[str], timeout_seconds: int | None = None) -> tuple[BaseModel, AgentRunEnvelope]:
+    return run_agent_step(
+        repo_root=repo_root,
+        stage_name=f"ui_grounding_{stage_name}",
+        output_model=output_model,
+        context_payload=context_payload,
+        guidance=UI_GROUNDING_DOCTRINE + guidance,
+        timeout_seconds=timeout_seconds,
+    )
+
+
+def persist_agent_run(*, pipeline_root: Path, node_id: str, envelope: AgentRunEnvelope) -> Path:
+    path = pipeline_root / "agent_runs" / f"{node_id}.json"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(envelope.model_dump(), indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return path