devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/idea/story_pipeline.py

@@ -0,0 +1,1585 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import subprocess
+import sys
+import uuid
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+from urllib.parse import quote
+from urllib.request import Request, urlopen
+
+from pydantic import BaseModel
+
+from ..devflow_state import publish_devflow_state
+from ..project_registry import find_project_for_repo_root
+from ..planning.render_drafts import render_draft_story_markdown
+from ..stores.execution_store import ExecutionStore
+from ..story.contracts import validate_story_contract
+from ..story.markdown_contracts import MANDATORY_CONTRACT_FORMATION_MODE_LINE, PlaneOracle, StoryContract
+from ..ui_grounding.models import GroundedStoryReferencePatchArtifact
+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 .actors import load_actor_registry, normalize_idea_actors, resolve_actor_entry, write_actor_registry
+from .paths import get_idea_paths
+from .sufficiency import evaluate_idea_sufficiency, extract_sufficient_idea, load_idea_source, render_sufficiency_json
+from .traditional_stories import (
+    TraditionalStoryInsufficiencyError,
+    _extract_json,
+    _load_llm_cli_config,
+    generate_story_coverage_requirements,
+    generate_traditional_user_story_set,
+    validate_sufficient_idea,
+)
+from ..llm.cli_one_shot import run_one_shot
+
+
+DAG_ID = "idea_to_devflow_stories_dag"
+
+
+@dataclass(frozen=True)
+class IdeaStoryDagResult:
+    exit_code: int
+    run_id: str
+    pipeline_dir: Path
+    message: str
+    story_set_id: str | None
+    devflow_story_set_id: str | None
+    failed_stage: str | None = None
+    resume_cursor: dict[str, Any] | None = None
+
+
+class IdeaStoryDagEvent(BaseModel):
+    repo_root: str
+    idea_id: str
+    raw_text: str | None = None
+    source_path: str | None = None
+    max_stories: int = 0
+    planes: list[str]
+    pipeline_key: str
+
+
+_CURRENT_STORE: ExecutionStore | None = None
+_CURRENT_RUN_ID: str | None = None
+
+
+def _store_run() -> tuple[ExecutionStore, str]:
+    if _CURRENT_STORE is None or _CURRENT_RUN_ID is None:
+        raise RuntimeError("idea story pipeline missing runtime store/run_id")
+    return _CURRENT_STORE, _CURRENT_RUN_ID
+
+
+def _stable_hash(payload: Any) -> str:
+    return hashlib.sha256(json.dumps(payload, sort_keys=True).encode("utf-8")).hexdigest()
+
+
+def _stable_id(prefix: str, payload: Any, *, size: int = 12) -> str:
+    return f"{prefix}{_stable_hash(payload)[:size]}"
+
+
+def _deterministic_uuid4(seed: str) -> str:
+    raw = bytearray(hashlib.sha256(seed.encode("utf-8")).digest()[:16])
+    raw[6] = (raw[6] & 0x0F) | 0x40
+    raw[8] = (raw[8] & 0x3F) | 0x80
+    return str(uuid.UUID(bytes=bytes(raw)))
+
+
+def _parse_list_option(planes: list[str]) -> list[str]:
+    return sorted({str(item).strip() for item in planes if str(item).strip()})
+
+
+CANONICAL_PLANES = ["auth", "api", "ui", "integrations", "ops"]
+
+
+def _validate_candidate_planes(planes: list[str]) -> list[str]:
+    allowed = set(CANONICAL_PLANES)
+    invalid = [plane for plane in planes if plane not in allowed]
+    if invalid:
+        raise ValueError(f"Invalid planes: {invalid}. Allowed planes are auth, api, ui, integrations, ops.")
+    return planes
+
+
+def _resolve_story_plane_candidates(planes: list[str]) -> list[str]:
+    normalized = _validate_candidate_planes(_parse_list_option(planes))
+    return normalized or list(CANONICAL_PLANES)
+
+
+def _pipeline_root(repo_root: Path, *, idea_id: str, pipeline_key: str) -> Path:
+    return get_idea_paths(repo_root, idea_id=idea_id).idea_dir / "pipelines" / DAG_ID / pipeline_key
+
+
+def _read_idea_payload(repo_root: Path, *, idea_id: str) -> dict[str, Any]:
+    idea_json = get_idea_paths(repo_root, idea_id=idea_id).idea_dir / "idea.json"
+    if not idea_json.exists():
+        return {"idea_id": idea_id}
+    return json.loads(idea_json.read_text(encoding="utf-8"))
+
+
+def _write_json(path: Path, payload: dict[str, 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 _clean_dfs_summary(text: str) -> str:
+    cleaned = re.sub(r"\[<more repeated useless text>\]", "", str(text or ""), flags=re.IGNORECASE)
+    cleaned = re.sub(r"\s+", " ", cleaned).strip()
+    return cleaned[:240] if cleaned else "Processing story generation"
+
+
+def _dfs_running(*, repo_root: Path, idea_id: str, run_id: str, summary: str) -> None:
+    project = find_project_for_repo_root(repo_root)
+    project_id = None if project is None else str(project.get("project_id") or "").strip()
+    if not project_id:
+        idea_json = get_idea_paths(repo_root, idea_id=idea_id).idea_dir / "idea.json"
+        if idea_json.exists():
+            try:
+                project_id = str(json.loads(idea_json.read_text(encoding="utf-8")).get("project_id") or "").strip()
+            except Exception:
+                project_id = None
+    if not project_id:
+        return
+    publish_devflow_state(
+        project_id=project_id,
+        run_id=run_id,
+        current_state="running",
+        current_status="processing",
+        run_summary=_clean_dfs_summary(summary),
+        display="project",
+        display_path=f"idea:{idea_id}",
+    )
+
+
+def _dfs_node_running(*, repo_root: Path, idea_id: str, run_id: str, node_id: str, summary: str) -> None:
+    _dfs_running(repo_root=repo_root, idea_id=idea_id, run_id=run_id, summary=summary)
+
+
+def _dfs_terminal(*, repo_root: Path, idea_id: str, run_id: str, summary: str, current_state: str, current_status: str, error_message: str | None = None) -> None:
+    project = find_project_for_repo_root(repo_root)
+    project_id = None if project is None else str(project.get("project_id") or "").strip()
+    if not project_id:
+        idea_json = get_idea_paths(repo_root, idea_id=idea_id).idea_dir / "idea.json"
+        if idea_json.exists():
+            try:
+                project_id = str(json.loads(idea_json.read_text(encoding="utf-8")).get("project_id") or "").strip()
+            except Exception:
+                project_id = None
+    if not project_id:
+        return
+    publish_devflow_state(
+        project_id=project_id,
+        run_id=run_id,
+        current_state=current_state,
+        current_status=current_status,
+        run_summary=_clean_dfs_summary(summary),
+        error_message=_clean_dfs_summary(error_message or "") if error_message else None,
+        display="project",
+        display_path=f"idea:{idea_id}",
+    )
+
+
+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 os.environ.get("SUPABASE_URL")
+    )
+    key = (
+        os.environ.get("DEVFLOW_SUPABASE_SERVICE_KEY")
+        or os.environ.get("SUPABASE_SERVICE_ROLE_KEY")
+        or os.environ.get("SUPABASE_SERVICE_KEY")
+    )
+    if not url or not key:
+        from ..devflow_state import _keychain_get  # type: ignore
+        url = url or _keychain_get("Supabase URL", "Clarity")
+        key = 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
+
+
+def _update_idea_pipeline_status(*, repo_root: Path, idea_id: str, status: str) -> None:
+    """Update devflow_project_ideas.status for the given idea."""
+    config = _resolve_supabase_rest_config()
+    if config is None:
+        return
+    url, key = config
+    try:
+        _postgrest_request(
+            method="PATCH",
+            url=f"{url}/rest/v1/devflow_project_ideas?idea_id=eq.{quote(idea_id)}",
+            key=key,
+            body={"status": status, "updated_at": datetime.now(UTC).isoformat()},
+        )
+    except Exception:
+        return  # non-fatal
+
+
+def _is_uuid_like(value: str | None) -> bool:
+    candidate = str(value or "").strip()
+    if not candidate:
+        return False
+    try:
+        uuid.UUID(candidate)
+    except ValueError:
+        return False
+    return True
+
+
+def _lookup_project_id_for_idea(*, url: str, key: str, idea_id: str) -> str | None:
+    try:
+        rows = _postgrest_request(
+            method="GET",
+            url=f"{url}/rest/v1/devflow_project_ideas?select=project_id&idea_id=eq.{quote(idea_id)}&limit=1",
+            key=key,
+        )
+    except Exception:
+        return None
+    if not isinstance(rows, list) or not rows:
+        return None
+    project_id = str((rows[0] or {}).get("project_id") or "").strip()
+    return project_id or None
+
+
+def _resolve_story_sync_project_id(*, url: str, key: str, idea_id: str, idea_payload: dict[str, Any]) -> str | None:
+    project_id = str(idea_payload.get("project_id") or "").strip()
+    if _is_uuid_like(project_id):
+        return project_id
+    resolved_project_id = _lookup_project_id_for_idea(url=url, key=key, idea_id=idea_id)
+    if _is_uuid_like(resolved_project_id):
+        return resolved_project_id
+    return project_id or resolved_project_id or None
+
+
+def _sync_devflow_stories_to_supabase(*, repo_root: Path, idea_id: str, run_id: str, devflow_story_set_id: str) -> None:
+    config = _resolve_supabase_rest_config()
+    if config is None:
+        return
+    url, key = config
+    idea_json = get_idea_paths(repo_root, idea_id=idea_id).idea_dir / "idea.json"
+    if not idea_json.exists():
+        return
+    idea_payload = json.loads(idea_json.read_text(encoding="utf-8"))
+    project_id = _resolve_story_sync_project_id(url=url, key=key, idea_id=idea_id, idea_payload=idea_payload)
+    if not project_id:
+        return
+
+    compiled_manifest_path = get_idea_paths(repo_root, idea_id=idea_id).idea_dir / "devflow_story_sets" / devflow_story_set_id / "manifest.json"
+    if not compiled_manifest_path.exists():
+        return
+    compiled_manifest = json.loads(compiled_manifest_path.read_text(encoding="utf-8"))
+    source_story_set_id = str(compiled_manifest.get("source_story_set_id") or "").strip()
+    if not source_story_set_id:
+        return
+    trad_manifest_path = get_idea_paths(repo_root, idea_id=idea_id).idea_dir / "traditional_user_stories" / source_story_set_id / "manifest.json"
+    if not trad_manifest_path.exists():
+        return
+    trad_manifest = json.loads(trad_manifest_path.read_text(encoding="utf-8"))
+    trad_story_paths = [repo_root / rel for rel in (trad_manifest.get("story_paths") or [])]
+    compiled_story_paths = [repo_root / rel for rel in (compiled_manifest.get("story_paths") or [])]
+    compiled_by_index = {idx: path for idx, path in enumerate(sorted(compiled_story_paths), start=1)}
+
+    rows: list[dict[str, Any]] = []
+    for index, trad_path in enumerate(sorted(trad_story_paths), start=1):
+        if not trad_path.exists():
+            continue
+        trad_text = trad_path.read_text(encoding="utf-8")
+        title, _actor, acceptance, statement = _story_statement_from_traditional(trad_text)
+        compiled_path = compiled_by_index.get(index)
+        compiled_payload: dict[str, Any] = {}
+        if compiled_path and compiled_path.exists():
+            compiled_payload = json.loads(compiled_path.read_text(encoding="utf-8"))
+        rows.append({
+            "idea_id": idea_id,
+            "story_id": str(compiled_payload.get("story_id") or f"TRAD:{idea_id}:{index:03d}"),
+            "story_uuid": str(compiled_payload.get("story_uuid") or "") or None,
+            "project_id": project_id,
+            "run_id": run_id,
+            "title": title,
+            "summary": statement or None,
+            "acceptance_criteria": acceptance,
+            "status": "ready_for_implementation",
+            "plane": str(compiled_payload.get("plane") or "") or None,
+            "required_planes": compiled_payload.get("required_planes") or [],
+            "devflow_story_set_id": devflow_story_set_id,
+            "source_story_set_id": source_story_set_id,
+            "artifact_path": str(trad_path),
+            "compiled_story_id": str(compiled_payload.get("story_id") or "") or None,
+            "compiled_story_path": str(compiled_path) if compiled_path else None,
+            "updated_at": datetime.now(UTC).isoformat(),
+        })
+    delete_url = f"{url}/rest/v1/devflow_idea_stories?idea_id=eq.{quote(idea_id)}"
+    try:
+        _postgrest_request(method="DELETE", url=delete_url, key=key)
+        if rows:
+            _postgrest_request(method="POST", url=f"{url}/rest/v1/devflow_idea_stories?on_conflict=story_id", key=key, body=rows, prefer="resolution=merge-duplicates")
+    except Exception:
+        return
+
+
+def _load_json_report(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def _story_statement_from_traditional(text: str) -> tuple[str, str, list[str], str]:
+    lines = [line.rstrip() for line in text.splitlines()]
+    title = ""
+    statement_lines: list[str] = []
+    actor = ""
+    acceptance: list[str] = []
+    in_acceptance = False
+
+    for line in lines:
+        stripped = line.strip()
+        if stripped.startswith("**Title:**"):
+            title = stripped.split(":", 1)[1].strip()
+            continue
+
+        if stripped in {"## User Value", "## Acceptance Criteria"}:
+            in_acceptance = stripped == "## Acceptance Criteria"
+            continue
+
+        if stripped.startswith("As a "):
+            actor = stripped[len("As a "):].rstrip(",").strip()
+            statement_lines.append(stripped)
+            continue
+
+        if stripped.startswith("I want ") or stripped.startswith("so that "):
+            statement_lines.append(stripped)
+            continue
+
+        if in_acceptance and stripped:
+            acceptance.append(stripped)
+
+    return title or "Compiled DevFlow story", actor, acceptance, "\n".join(statement_lines).strip()
+
+
+_HTTP_ANCHOR_RE = re.compile(r"^(GET|POST|PUT|PATCH|DELETE)\s+/\S+")
+_SCHEME_ANCHOR_RE = re.compile(r"^[a-z][a-z0-9_-]{1,32}:")
+
+
+def _anchor_is_allowed(anchor: str) -> bool:
+    value = (anchor or "").strip()
+    if not value:
+        return False
+    return bool(_SCHEME_ANCHOR_RE.match(value) or _HTTP_ANCHOR_RE.match(value))
+
+
+def _adjudicate_story_planes(*, repo_root: Path, idea_id: str, story: dict[str, Any], candidate_planes: list[str]) -> dict[str, Any]:
+    prompt = {
+        "task": "adjudicate_story_planes",
+        "idea_id": idea_id,
+        "story": story,
+        "candidate_planes": candidate_planes,
+        "instructions": [
+            "Return JSON only. No markdown. No prose outside JSON.",
+            "Select only the planes that are truly required for this specific story.",
+            "Do not include a plane unless the story's user-visible outcome requires coverage/oracles in that plane.",
+            "Do not default to all planes.",
+            "For every included and excluded plane, provide a concise rationale.",
+        ],
+        "output_schema": {
+            "required_planes": ["api"],
+            "included_planes": [{"plane": "api", "rationale": "string"}],
+            "excluded_planes": [{"plane": "ui", "rationale": "string"}],
+        },
+    }
+    base_cmd, delivery = _load_llm_cli_config()
+    result = run_one_shot(base_cmd=base_cmd, delivery=delivery, prompt=json.dumps(prompt, indent=2, sort_keys=True), cwd=repo_root)
+    if not result.ok:
+        raise RuntimeError(result.stderr or result.stdout or "story plane adjudication LLM command failed")
+    raw_json = _extract_json(result.stdout)
+    if raw_json is None:
+        raise RuntimeError("Failed to locate JSON in story plane adjudication output.")
+    parsed = json.loads(raw_json)
+    if not isinstance(parsed, dict):
+        raise RuntimeError("Story plane adjudication output must be a JSON object.")
+    required_planes = sorted({str(item).strip() for item in (parsed.get("required_planes") or []) if str(item).strip()})
+    invalid = [plane for plane in required_planes if plane not in {"auth", "api", "ui", "integrations", "ops"}]
+    if invalid:
+        raise RuntimeError(f"Story plane adjudication returned invalid planes: {invalid}")
+    if not required_planes:
+        raise RuntimeError("Story plane adjudication returned no required planes.")
+    parsed["required_planes"] = required_planes
+    return parsed
+
+
+def _validate_generated_story_payload(*, payload: dict[str, Any], source_path: Path) -> list[dict[str, str]]:
+    plane_oracles = [
+        PlaneOracle(
+            plane=str(item.get("plane") or "").strip(),
+            oracle=str(item.get("oracle") or "").strip(),
+            anchor=str(item.get("anchor") or "").strip(),
+        )
+        for item in (payload.get("plane_oracles") or [])
+        if isinstance(item, dict)
+    ]
+    contract = StoryContract(
+        story_uuid=str(payload.get("story_uuid") or "").strip(),
+        story_id=str(payload.get("story_id") or "").strip(),
+        title=str(payload.get("title") or "").strip(),
+        required_planes=[str(item).strip() for item in (payload.get("required_planes") or []) if str(item).strip()],
+        contract_formation_mode_line_present=str(payload.get("contract_formation_mode") or "").strip()
+        == MANDATORY_CONTRACT_FORMATION_MODE_LINE,
+        plane_oracles=plane_oracles,
+        raw_text=json.dumps(payload, sort_keys=True),
+        source_path=str(source_path),
+    )
+
+    issues = [
+        {"code": issue.code, "message": issue.message, "path": issue.path}
+        for issue in validate_story_contract(contract, start_line=1)
+    ]
+    for index, oracle in enumerate(plane_oracles):
+        if oracle.anchor and not _anchor_is_allowed(oracle.anchor):
+            issues.append(
+                {
+                    "code": "invalid_plane_oracle_anchor_format",
+                    "message": "plane_oracles anchor must be a stable address",
+                    "path": f"{source_path}:plane_oracles[{index}].anchor",
+                }
+            )
+    return issues
+
+
+def _load_grounded_story_reference_patch(
+    repo_root: Path,
+    *,
+    idea_id: str,
+    story_paths: list[Path],
+) -> GroundedStoryReferencePatchArtifact | None:
+    idea_dir = get_idea_paths(repo_root, idea_id=idea_id).idea_dir
+    pipeline_root = idea_dir / "pipelines" / "ui_grounding_dag"
+    if not pipeline_root.exists():
+        return None
+
+    source_refs = {str(path.relative_to(repo_root)) for path in story_paths}
+    source_refs.add(f"idea:{idea_id}")
+    idea_json = idea_dir / "idea.json"
+    if idea_json.exists():
+        source_refs.add(str(idea_json.relative_to(repo_root)))
+
+    candidates = sorted(pipeline_root.glob("*/grounded_story_reference_patch.json"), key=lambda path: path.stat().st_mtime, reverse=True)
+    for patch_path in candidates:
+        try:
+            patch = GroundedStoryReferencePatchArtifact.model_validate_json(patch_path.read_text(encoding="utf-8"))
+        except Exception:
+            continue
+        if patch.idea_id != idea_id:
+            continue
+        target_refs = {str(item).strip() for item in patch.target_refs if str(item).strip()}
+        if target_refs and target_refs.isdisjoint(source_refs):
+            continue
+        return patch
+    return None
+
+
+def _merge_grounded_ui_anchors(
+    *,
+    payload: dict[str, Any],
+    ui_patch: GroundedStoryReferencePatchArtifact | None,
+) -> dict[str, Any]:
+    if ui_patch is None or not ui_patch.attached_ui_anchors:
+        return payload
+
+    merged = dict(payload)
+    ui_anchor_values = [
+        str(item.get("anchor") or "").strip()
+        for item in ui_patch.attached_ui_anchors
+        if isinstance(item, dict) and str(item.get("anchor") or "").strip()
+    ]
+    if not ui_anchor_values:
+        return merged
+
+    seen_evidence: set[str] = set()
+    evidence: list[str] = []
+    for anchor in [*(merged.get("evidence_anchors") or []), *ui_anchor_values]:
+        value = str(anchor or "").strip()
+        if value and value not in seen_evidence:
+            seen_evidence.add(value)
+            evidence.append(value)
+    merged["evidence_anchors"] = evidence
+
+    plane_oracles = []
+    preferred_ui_anchor = ui_anchor_values[0]
+    for item in (merged.get("plane_oracles") or []):
+        if not isinstance(item, dict):
+            continue
+        oracle = dict(item)
+        if str(oracle.get("plane") or "").strip() == "ui":
+            oracle["anchor"] = preferred_ui_anchor
+        plane_oracles.append(oracle)
+    merged["plane_oracles"] = plane_oracles
+    merged["ui_grounding"] = {
+        "origin": ui_patch.origin,
+        "supporting_evidence_refs": list(ui_patch.supporting_evidence_refs),
+        "attached_ui_anchors": list(ui_patch.attached_ui_anchors),
+    }
+    return merged
+
+
+def _grounded_ui_patch_cache_key(ui_patch: GroundedStoryReferencePatchArtifact | None) -> dict[str, Any] | None:
+    if ui_patch is None:
+        return None
+    return {
+        "origin": ui_patch.origin,
+        "target_refs": list(ui_patch.target_refs),
+        "attached_ui_anchors": list(ui_patch.attached_ui_anchors),
+        "supporting_evidence_refs": list(ui_patch.supporting_evidence_refs),
+    }
+
+
+def _compile_devflow_story_set(
+    *,
+    repo_root: Path,
+    idea_id: str,
+    story_set_id: str,
+    story_paths: list[Path],
+    planes: list[str],
+    story_plane_adjudication: dict[str, Any] | None = None,
+    pass_index: int = 1,
+    prior_validation_issues: list[dict[str, str]] | None = None,
+    force_rebuild: bool = False,
+) -> tuple[str, Path, list[Path]]:
+    paths = get_idea_paths(repo_root, idea_id=idea_id)
+    grounded_ui_patch = _load_grounded_story_reference_patch(repo_root, idea_id=idea_id, story_paths=story_paths)
+    compile_id = _stable_id(
+        "dfs_",
+        {
+            "idea_id": idea_id,
+            "story_set_id": story_set_id,
+            "planes": planes,
+            "story_paths": [str(p.relative_to(repo_root)) for p in story_paths],
+            "grounded_ui_patch": _grounded_ui_patch_cache_key(grounded_ui_patch),
+        },
+    )
+    root = paths.idea_dir / "devflow_story_sets" / compile_id
+    manifest_path = root / "manifest.json"
+    if manifest_path.exists() and not force_rebuild:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+        compiled_paths = [repo_root / rel_path for rel_path in manifest.get("story_paths", [])]
+        return compile_id, root, compiled_paths
+
+    root.mkdir(parents=True, exist_ok=True)
+    for stale_path in root.glob("story_*.json"):
+        stale_path.unlink()
+    compiled_paths: list[Path] = []
+    adjudication_map = {
+        str(item.get("story_path")): item
+        for item in ((story_plane_adjudication or {}).get("stories") or [])
+        if isinstance(item, dict) and str(item.get("story_path") or "").strip()
+    }
+    for index, source_path in enumerate(sorted(story_paths), start=1):
+        source_text = source_path.read_text(encoding="utf-8")
+        title, actor_label, acceptance, statement = _story_statement_from_traditional(source_text)
+        rel_source = str(source_path.relative_to(repo_root))
+        story_id = f"STORY:idea:{idea_id}:compiled:{index:03d}"
+        story_planes = [str(item).strip() for item in ((adjudication_map.get(str(source_path)) or {}).get("required_planes") or planes) if str(item).strip()]
+        story_uuid = _deterministic_uuid4(f"{idea_id}:{story_set_id}:{rel_source}:{','.join(story_planes)}")
+        payload = {
+            "story_uuid": story_uuid,
+            "story_id": story_id,
+            "title": title,
+            "contract_formation_mode": MANDATORY_CONTRACT_FORMATION_MODE_LINE,
+            "required_planes": story_planes,
+            "plane_oracles": [
+                {
+                    "plane": plane,
+                    "oracle": f"{title}: the user-observable outcome remains satisfied for the {plane} plane.",
+                    "anchor": f"artifact:{rel_source}",
+                }
+                for plane in story_planes
+            ],
+            "evidence_anchors": [f"artifact:{rel_source}"],
+            "draft_story_id": f"compiled_{story_set_id}_{index:03d}",
+            "plane": story_planes[0],
+            "source_analysis_id": story_set_id,
+        }
+        actor_registry = load_actor_registry(repo_root)
+        primary_actor = resolve_actor_entry(actor=actor_label, actor_registry=actor_registry) if actor_label else None
+        if primary_actor is None and actor_label:
+            raise RuntimeError(f"Traditional story actor {actor_label!r} is not present in canonical actor registry during handoff.")
+        if primary_actor is not None:
+            payload["primary_actor"] = {
+                "id": str(primary_actor.get("id") or "").strip(),
+                "label": str(primary_actor.get("label") or "").strip(),
+                "kind": str(primary_actor.get("kind") or "human").strip() or "human",
+                "inherits_from": str(primary_actor.get("inherits_from") or "").strip() or None,
+            }
+        if statement:
+            payload["user_value_statement"] = statement
+        if acceptance:
+            payload["acceptance_criteria"] = acceptance
+        payload = _merge_grounded_ui_anchors(payload=payload, ui_patch=grounded_ui_patch)
+        out_path = root / f"story_{index:03d}.json"
+        out_path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+        compiled_paths.append(out_path)
+
+    manifest = {
+        "devflow_story_set_id": compile_id,
+        "idea_id": idea_id,
+        "kind": "devflow_story_set",
+        "planes": planes,
+        "source_story_set_id": story_set_id,
+        "source_story_paths": [str(path.relative_to(repo_root)) for path in sorted(story_paths)],
+        "story_paths": [str(path.relative_to(repo_root)) for path in compiled_paths],
+    }
+    manifest_path.write_text(json.dumps(manifest, indent=2, sort_keys=True), encoding="utf-8")
+    return compile_id, root, compiled_paths
+
+
+def _build_devflow_story_validation_workspace(*, root: Path, compiled_paths: list[Path], pass_index: int) -> Path:
+    validation_root = root / "_validation" / f"pass_{pass_index:03d}"
+    story_dir = validation_root / "ai_docs" / "context" / "v2" / "project_docs" / "user_stories" / "generated"
+    story_dir.mkdir(parents=True, exist_ok=True)
+
+    for index, compiled_path in enumerate(sorted(compiled_paths), start=1):
+        payload = json.loads(compiled_path.read_text(encoding="utf-8"))
+        markdown = render_draft_story_markdown(payload)
+        out_path = story_dir / f"story_{index:03d}.md"
+        out_path.write_text(markdown, encoding="utf-8")
+
+    return validation_root
+
+
+def _run_devflow_story_validator(*, engine_root: Path, validation_repo_root: Path, report_path: Path) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "devflow_engine.story.validate_stories",
+            "--repo-root",
+            str(validation_repo_root),
+            "--json",
+            str(report_path),
+        ],
+        cwd=str(validation_repo_root),
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+
+
+def _resolve_existing_sufficient_idea(repo_root: Path, *, idea_id: str) -> tuple[dict[str, Any], dict[str, Any]] | None:
+    payload = _read_idea_payload(repo_root, idea_id=idea_id)
+    candidate = payload.get("sufficient_idea")
+    if not isinstance(candidate, dict):
+        return None
+    missing = validate_sufficient_idea(candidate)
+    if missing:
+        return None
+    return payload, candidate
+
+
+class SufficiencyGateNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        event = task_context.event
+        repo_root = Path(event.repo_root)
+        store, run_id = _store_run()
+        _dfs_node_running(repo_root=repo_root, idea_id=event.idea_id, run_id=run_id, node_id="sufficiency_gate", summary="Reviewing idea readiness")
+        node_exec_id = store.create_node_attempt(run_id=run_id, node_id="sufficiency_gate", node_name="SufficiencyGate", attempt=1)
+
+        stage_path = _pipeline_root(repo_root, idea_id=event.idea_id, pipeline_key=event.pipeline_key) / "sufficiency.json"
+        existing = _resolve_existing_sufficient_idea(repo_root, idea_id=event.idea_id)
+        if existing is not None:
+            payload, sufficient_idea = existing
+            result_payload = {
+                "input": {"mode": "existing_idea_json", "source": str((get_idea_paths(repo_root, idea_id=event.idea_id).idea_dir / "idea.json").relative_to(repo_root))},
+                "sufficient_idea": sufficient_idea,
+                "story_generation_pass": True,
+                "reused_existing": True,
+                "identified_gaps": [],
+                "blockers": [],
+                "discussion_points": [],
+                "sufficiency_quotient": 100,
+            }
+            _write_json(stage_path, result_payload)
+            store.add_artifact(run_id=run_id, node_exec_id=node_exec_id, kind="idea_sufficiency", uri=str(stage_path), metadata=result_payload)
+            store.mark_node_finished(node_exec_id=node_exec_id, status="succeeded", output={"artifact_path": str(stage_path), "reused_existing": True})
+            task_context.metadata["sufficient_idea"] = sufficient_idea
+            task_context.metadata["sufficiency_payload"] = result_payload
+            return task_context
+
+        try:
+            raw_text, input_meta = load_idea_source(
+                text=event.raw_text,
+                source_path=Path(event.source_path) if event.source_path else None,
+            )
+        except ValueError as exc:
+            payload = {"story_generation_pass": False, "error": str(exc), "blockers": ["input_source"]}
+            _write_json(stage_path, payload)
+            store.add_artifact(run_id=run_id, node_exec_id=node_exec_id, kind="idea_sufficiency", uri=str(stage_path), metadata=payload)
+            store.mark_node_finished(node_exec_id=node_exec_id, status="failed", output=payload, error={"message": str(exc)})
+            task_context.metadata["message"] = json.dumps(payload, indent=2, sort_keys=True) + "\npipeline blocked: insufficient ideation\n"
+            task_context.metadata["exit_code"] = 2
+            task_context.stop_workflow()
+            return task_context
+
+        result = evaluate_idea_sufficiency(raw_text, input_meta=input_meta)
+        payload = dict(result.payload)
+        payload["sufficient_idea"] = extract_sufficient_idea(raw_text)
+        _write_json(stage_path, payload)
+        store.add_artifact(run_id=run_id, node_exec_id=node_exec_id, kind="idea_sufficiency", uri=str(stage_path), metadata=payload)
+
+        if not result.passed:
+            store.mark_node_finished(node_exec_id=node_exec_id, status="failed", output=payload, error={"message": "insufficient ideation"})
+            task_context.metadata["message"] = render_sufficiency_json(result) + "pipeline blocked: insufficient ideation\n"
+            task_context.metadata["exit_code"] = 2
+            task_context.stop_workflow()
+            return task_context
+
+        idea_dir = get_idea_paths(repo_root, idea_id=event.idea_id).idea_dir
+        idea_dir.mkdir(parents=True, exist_ok=True)
+        idea_json = idea_dir / "idea.json"
+        current = _read_idea_payload(repo_root, idea_id=event.idea_id)
+        current["idea_id"] = event.idea_id
+        current.setdefault("title", str(payload["sufficient_idea"].get("summary") or event.idea_id))
+        current["sufficient_idea"] = payload["sufficient_idea"]
+        current["ideation_output"] = payload
+        idea_json.write_text(json.dumps(current, indent=2, sort_keys=True), encoding="utf-8")
+
+        store.mark_node_finished(node_exec_id=node_exec_id, status="succeeded", output={"artifact_path": str(stage_path), "reused_existing": False})
+        task_context.metadata["sufficient_idea"] = payload["sufficient_idea"]
+        task_context.metadata["sufficiency_payload"] = payload
+        return task_context
+
+
+class ActorRegistryNormalizationNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        event = task_context.event
+        repo_root = Path(event.repo_root)
+        store, run_id = _store_run()
+        _dfs_node_running(repo_root=repo_root, idea_id=event.idea_id, run_id=run_id, node_id="actor_registry_normalization", summary="Normalizing canonical actors")
+        node_exec_id = store.create_node_attempt(run_id=run_id, node_id="actor_registry_normalization", node_name="ActorRegistryNormalization", attempt=1)
+        stage_path = _pipeline_root(repo_root, idea_id=event.idea_id, pipeline_key=event.pipeline_key) / "actor_registry_normalization.json"
+
+        sufficient_idea = dict(task_context.metadata.get("sufficient_idea") or {})
+        existing_registry = load_actor_registry(repo_root)
+        normalized = normalize_idea_actors(
+            repo_root=repo_root,
+            idea_id=event.idea_id,
+            sufficient_idea=sufficient_idea,
+            existing_registry=existing_registry,
+        )
+        merged_registry = {
+            "actors": list(normalized.get("resolved_actors") or normalized.get("actors") or []),
+            "canonical_actors": list(normalized.get("canonical_actors") or []),
+            "notes": normalized.get("notes") or existing_registry.get("notes") or [],
+            "path": normalized.get("path") or str(existing_registry.get("path") or ""),
+        }
+        registry_path = write_actor_registry(
+            repo_root,
+            actors=merged_registry["actors"],
+            notes=merged_registry["notes"],
+        )
+
+        sufficient_idea["target_users"] = list(merged_registry["canonical_actors"])
+        idea_payload = _read_idea_payload(repo_root, idea_id=event.idea_id)
+        if isinstance(idea_payload.get("sufficient_idea"), dict):
+            idea_payload["sufficient_idea"] = {**dict(idea_payload["sufficient_idea"]), "target_users": list(merged_registry["canonical_actors"])}
+        idea_payload["actor_registry"] = {
+            "path": str(registry_path.relative_to(repo_root)),
+            "canonical_actors": list(merged_registry["canonical_actors"]),
+            "actors": list(merged_registry["actors"]),
+            "notes": list(merged_registry["notes"]),
+        }
+        _write_json(get_idea_paths(repo_root, idea_id=event.idea_id).idea_dir / "idea.json", idea_payload)
+
+        payload = {
+            "actor_registry_path": str(registry_path.relative_to(repo_root)),
+            "existing_actor_count": len(existing_registry.get("actors") or []),
+            "canonical_actors": list(merged_registry["canonical_actors"]),
+            "resolved_actors": list(merged_registry["actors"]),
+            "additions": list(normalized.get("additions") or []),
+            "repairs": list(normalized.get("repairs") or []),
+            "notes": list(merged_registry["notes"]),
+        }
+        _write_json(stage_path, payload)
+        store.add_artifact(run_id=run_id, node_exec_id=node_exec_id, kind="idea_actor_registry", uri=str(stage_path), metadata=payload)
+        store.mark_node_finished(node_exec_id=node_exec_id, status="succeeded", output=payload)
+        task_context.metadata["sufficient_idea"] = sufficient_idea
+        task_context.metadata["actor_registry"] = merged_registry
+        return task_context
+
+
+class PlaneRequirementGateNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        event = task_context.event
+        repo_root = Path(event.repo_root)
+        store, run_id = _store_run()
+        _dfs_node_running(repo_root=repo_root, idea_id=event.idea_id, run_id=run_id, node_id="plane_requirement_gate", summary="Resolving candidate story planes")
+        node_exec_id = store.create_node_attempt(run_id=run_id, node_id="plane_requirement_gate", node_name="PlaneRequirementGate", attempt=1)
+        stage_path = _pipeline_root(repo_root, idea_id=event.idea_id, pipeline_key=event.pipeline_key) / "plane_requirement.json"
+        candidate_planes = _resolve_story_plane_candidates(event.planes)
+        payload = {
+            "candidate_planes": candidate_planes,
+            "source": "upstream_candidate_planes" if _parse_list_option(event.planes) else "canonical_story_plane_universe",
+        }
+        _write_json(stage_path, payload)
+        store.add_artifact(run_id=run_id, node_exec_id=node_exec_id, kind="idea_plane_requirement", uri=str(stage_path), metadata=payload)
+        store.mark_node_finished(node_exec_id=node_exec_id, status="succeeded", output=payload)
+        task_context.metadata["candidate_planes"] = candidate_planes
+        return task_context
+
+
+class StoryCoverageRequirementsNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        event = task_context.event
+        repo_root = Path(event.repo_root)
+        store, run_id = _store_run()
+        _dfs_node_running(repo_root=repo_root, idea_id=event.idea_id, run_id=run_id, node_id="story_coverage_requirements", summary="Generating story coverage requirements")
+        node_exec_id = store.create_node_attempt(
+            run_id=run_id,
+            node_id="story_coverage_requirements",
+            node_name="StoryCoverageRequirements",
+            attempt=1,
+        )
+        sufficient_idea = dict(task_context.metadata.get("sufficient_idea") or {})
+        payload = _read_idea_payload(repo_root, idea_id=event.idea_id)
+        requirements = generate_story_coverage_requirements(
+            repo_root=repo_root,
+            idea_id=event.idea_id,
+            payload=payload,
+            sufficient_idea=sufficient_idea,
+        )
+        stage_path = _pipeline_root(repo_root, idea_id=event.idea_id, pipeline_key=event.pipeline_key) / "coverage_requirements.json"
+        _write_json(stage_path, requirements)
+        stage_payload = {"coverage_requirements": requirements, "artifact_path": str(stage_path)}
+        store.add_artifact(run_id=run_id, node_exec_id=node_exec_id, kind="traditional_story_coverage_requirements", uri=str(stage_path), metadata=requirements)
+        store.mark_node_finished(node_exec_id=node_exec_id, status="succeeded", output=stage_payload)
+        task_context.metadata["coverage_requirements"] = requirements
+        if isinstance(requirements.get("actor_registry"), dict):
+            task_context.metadata["actor_registry"] = dict(requirements.get("actor_registry") or {})
+        return task_context
+
+
+class TraditionalStoryGenerationNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        event = task_context.event
+        repo_root = Path(event.repo_root)
+        store, run_id = _store_run()
+        _dfs_node_running(repo_root=repo_root, idea_id=event.idea_id, run_id=run_id, node_id="traditional_story_generation", summary="Generating user stories")
+        node_exec_id = store.create_node_attempt(
+            run_id=run_id,
+            node_id="traditional_story_generation",
+            node_name="TraditionalStoryGeneration",
+            attempt=1,
+        )
+
+        try:
+            story_set = generate_traditional_user_story_set(
+                repo_root=repo_root,
+                idea_id=event.idea_id,
+                max_stories=event.max_stories,
+                coverage_requirements=dict(task_context.metadata.get("coverage_requirements") or {}),
+                actor_registry=dict(task_context.metadata.get("actor_registry") or {}),
+            )
+        except TraditionalStoryInsufficiencyError as exc:
+            stage_payload = {
+                "story_set_id": exc.story_set_id,
+                "stories_dir": str(exc.root),
+                "report_path": str(exc.report_path),
+                "sufficiency": exc.report,
+            }
+            stage_path = _pipeline_root(repo_root, idea_id=event.idea_id, pipeline_key=event.pipeline_key) / "traditional_story_generation.json"
+            _write_json(stage_path, stage_payload)
+            store.add_artifact(
+                run_id=run_id,
+                node_exec_id=node_exec_id,
+                kind="traditional_user_story_report",
+                uri=str(stage_path),
+                metadata=stage_payload,
+            )
+            store.mark_node_finished(node_exec_id=node_exec_id, status="succeeded", output=stage_payload)
+            task_context.metadata["story_set_id"] = exc.story_set_id
+            task_context.metadata["stories_dir"] = str(exc.root)
+            task_context.metadata["story_paths"] = []
+            task_context.metadata["traditional_story_sufficiency"] = exc.report
+            return task_context
+        manifest_path = story_set.root / "manifest.json"
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+        stage_payload = {
+            "story_set_id": story_set.story_set_id,
+            "stories_dir": str(story_set.root),
+            "story_paths": manifest.get("story_paths", []),
+            "sufficiency": story_set.sufficiency_report,
+        }
+        stage_path = _pipeline_root(repo_root, idea_id=event.idea_id, pipeline_key=event.pipeline_key) / "traditional_story_generation.json"
+        _write_json(stage_path, stage_payload)
+        store.add_artifact(run_id=run_id, node_exec_id=node_exec_id, kind="traditional_user_stories", uri=str(stage_path), metadata=stage_payload)
+        store.mark_node_finished(node_exec_id=node_exec_id, status="succeeded", output=stage_payload)
+        task_context.metadata["story_set_id"] = story_set.story_set_id
+        task_context.metadata["stories_dir"] = str(story_set.root)
+        task_context.metadata["story_paths"] = [str(path) for path in story_set.story_paths]
+        task_context.metadata["traditional_story_sufficiency"] = story_set.sufficiency_report
+        return task_context
+
+
+class TraditionalStoryCoverageGateNode(AgentNode):
+    def get_agent_config(self) -> AgentConfig:
+        return AgentConfig(
+            instructions=(
+                "Evaluate whether the generated traditional user stories sufficiently represent the validated idea, "
+                "using structured semantic judgment."
+            )
+        )
+
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        event = task_context.event
+        repo_root = Path(event.repo_root)
+        store, run_id = _store_run()
+        _dfs_node_running(repo_root=repo_root, idea_id=event.idea_id, run_id=run_id, node_id="traditional_story_coverage_gate", summary="Reviewing story coverage")
+        node_exec_id = store.create_node_attempt(
+            run_id=run_id,
+            node_id="traditional_story_coverage_gate",
+            node_name="TraditionalStoryCoverageGate",
+            attempt=1,
+        )
+
+        report = dict(task_context.metadata.get("traditional_story_sufficiency") or {})
+        stage_payload = {
+            "story_set_id": str(task_context.metadata.get("story_set_id") or ""),
+            "stories_dir": str(task_context.metadata.get("stories_dir") or ""),
+            "sufficiency": report,
+            "evaluation_mode": report.get("evaluation_mode") or "agentic",
+        }
+        stage_path = _pipeline_root(repo_root, idea_id=event.idea_id, pipeline_key=event.pipeline_key) / "traditional_story_coverage_gate.json"
+        _write_json(stage_path, stage_payload)
+        store.add_artifact(
+            run_id=run_id,
+            node_exec_id=node_exec_id,
+            kind="traditional_story_coverage_gate",
+            uri=str(stage_path),
+            metadata=stage_payload,
+        )
+
+        if not report.get("passed"):
+            store.mark_node_finished(
+                node_exec_id=node_exec_id,
+                status="failed",
+                output=stage_payload,
+                error={"message": "traditional story coverage gate failed after refinement"},
+            )
+            task_context.metadata["message"] = (
+                f"dag_id: {DAG_ID}\n"
+                f"pipeline_dir: {_pipeline_root(repo_root, idea_id=event.idea_id, pipeline_key=event.pipeline_key)}\n"
+                f"traditional story coverage insufficient after {report.get('pass_count')} pass(es)\n"
+                f"{json.dumps({'final_findings': report.get('final_findings'), 'report_path': str(stage_path)}, indent=2, sort_keys=True)}\n"
+            )
+            task_context.metadata["exit_code"] = 2
+            task_context.stop_workflow()
+            return task_context
+
+        store.mark_node_finished(node_exec_id=node_exec_id, status="succeeded", output=stage_payload)
+        return task_context
+
+
+class TraditionalStoryDecompositionNode(AgentNode):
+    def get_agent_config(self) -> AgentConfig:
+        return AgentConfig(
+            instructions=(
+                "Evaluate whether the covered traditional user stories are cleanly decomposed into atomic, non-overlapping stories."
+            )
+        )
+
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        event = task_context.event
+        repo_root = Path(event.repo_root)
+        store, run_id = _store_run()
+        _dfs_node_running(repo_root=repo_root, idea_id=event.idea_id, run_id=run_id, node_id="traditional_story_decomposition", summary="Reviewing story decomposition")
+        node_exec_id = store.create_node_attempt(
+            run_id=run_id,
+            node_id="traditional_story_decomposition",
+            node_name="TraditionalStoryDecomposition",
+            attempt=1,
+        )
+
+        report = dict((task_context.metadata.get("traditional_story_sufficiency") or {}).get("decomposition") or {})
+        stage_payload = {
+            "story_set_id": str(task_context.metadata.get("story_set_id") or ""),
+            "stories_dir": str(task_context.metadata.get("stories_dir") or ""),
+            "decomposition": report,
+            "evaluation_mode": report.get("evaluation_mode") or "agentic",
+        }
+        stage_path = _pipeline_root(repo_root, idea_id=event.idea_id, pipeline_key=event.pipeline_key) / "traditional_story_decomposition.json"
+        _write_json(stage_path, stage_payload)
+        store.add_artifact(
+            run_id=run_id,
+            node_exec_id=node_exec_id,
+            kind="traditional_story_decomposition",
+            uri=str(stage_path),
+            metadata=stage_payload,
+        )
+        if not report.get("passed"):
+            store.mark_node_finished(node_exec_id=node_exec_id, status="failed", output=stage_payload, error={"message": "traditional story decomposition failed"})
+            task_context.metadata["message"] = (
+                f"dag_id: {DAG_ID}\n"
+                f"pipeline_dir: {_pipeline_root(repo_root, idea_id=event.idea_id, pipeline_key=event.pipeline_key)}\n"
+                f"traditional story decomposition failed\n"
+                f"{json.dumps({'findings': report.get('findings'), 'report_path': str(stage_path)}, indent=2, sort_keys=True)}\n"
+            )
+            task_context.metadata["exit_code"] = 2
+            task_context.stop_workflow()
+            return task_context
+        store.mark_node_finished(node_exec_id=node_exec_id, status="succeeded", output=stage_payload)
+        return task_context
+
+
+class StoryPlaneAdjudicationNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        event = task_context.event
+        repo_root = Path(event.repo_root)
+        store, run_id = _store_run()
+        _dfs_node_running(repo_root=repo_root, idea_id=event.idea_id, run_id=run_id, node_id="story_plane_adjudication", summary="Confirming story planes")
+        node_exec_id = store.create_node_attempt(run_id=run_id, node_id="story_plane_adjudication", node_name="StoryPlaneAdjudication", attempt=1)
+
+        story_paths = [Path(path_str) for path_str in task_context.metadata.get("story_paths", [])]
+        if not story_paths:
+            payload = {"error": "No traditional stories available for plane adjudication."}
+            pipeline_dir = _pipeline_root(repo_root, idea_id=event.idea_id, pipeline_key=event.pipeline_key)
+            failure_payload = _handoff_failure_payload(
+                stage="story_plane_adjudication",
+                idea_id=event.idea_id,
+                pipeline_dir=pipeline_dir,
+                story_set_id=str(task_context.metadata.get("story_set_id") or "") or None,
+                details=payload,
+                resume_cursor=_resume_cursor_for_story_pipeline(pipeline_dir=pipeline_dir, story_set_id=str(task_context.metadata.get("story_set_id") or "") or None),
+            )
+            _write_handoff_failure(pipeline_dir=pipeline_dir, payload=failure_payload)
+            stage_path = pipeline_dir / "story_plane_adjudication.json"
+            _write_json(stage_path, payload)
+            store.add_artifact(run_id=run_id, node_exec_id=node_exec_id, kind="story_plane_adjudication", uri=str(stage_path), metadata=payload)
+            store.mark_node_finished(node_exec_id=node_exec_id, status="failed", output=payload, error={"message": payload["error"]})
+            task_context.metadata["message"] = json.dumps(payload, indent=2, sort_keys=True) + "\n"
+            task_context.metadata["exit_code"] = 2
+            task_context.stop_workflow()
+            return task_context
+
+        candidate_planes = list(task_context.metadata.get("candidate_planes") or _resolve_story_plane_candidates(event.planes))
+
+        adjudications = []
+        for source_path in story_paths:
+            text = source_path.read_text(encoding="utf-8")
+            title, _actor, acceptance, statement = _story_statement_from_traditional(text)
+            story_payload = {
+                "title": title,
+                "acceptance_criteria": acceptance,
+                "statement": statement,
+                "source_path": str(source_path),
+            }
+            adjudication = _adjudicate_story_planes(repo_root=repo_root, idea_id=event.idea_id, story=story_payload, candidate_planes=candidate_planes)
+            adjudications.append({
+                "story_path": str(source_path),
+                **adjudication,
+            })
+        stage_payload = {"candidate_planes": candidate_planes, "stories": adjudications}
+        stage_path = _pipeline_root(repo_root, idea_id=event.idea_id, pipeline_key=event.pipeline_key) / "story_plane_adjudication.json"
+        _write_json(stage_path, stage_payload)
+        store.add_artifact(run_id=run_id, node_exec_id=node_exec_id, kind="story_plane_adjudication", uri=str(stage_path), metadata=stage_payload)
+        store.mark_node_finished(node_exec_id=node_exec_id, status="succeeded", output=stage_payload)
+        task_context.metadata["story_plane_adjudication"] = stage_payload
+        return task_context
+
+
+class DevflowStoryCompilationNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        event = task_context.event
+        repo_root = Path(event.repo_root)
+        store, run_id = _store_run()
+        _dfs_node_running(repo_root=repo_root, idea_id=event.idea_id, run_id=run_id, node_id="devflow_story_compilation", summary="Compiling DevFlow stories")
+        engine_root = Path(__file__).resolve().parents[3]
+        node_exec_id = store.create_node_attempt(
+            run_id=run_id,
+            node_id="devflow_story_compilation",
+            node_name="DevflowStoryCompilation",
+            attempt=1,
+        )
+
+        story_paths = [Path(path_str) for path_str in task_context.metadata.get("story_paths", [])]
+        story_set_id = str(task_context.metadata.get("story_set_id") or "")
+        compile_id = ""
+        root: Path | None = None
+        compiled_paths: list[Path] = []
+        validation_history: list[dict[str, Any]] = []
+        validation_issues: list[dict[str, str]] = []
+        validation_report: dict[str, Any] = {"ok": False, "issue_count": 0, "issues": []}
+
+        for pass_index in range(1, 4):
+            compile_id, root, compiled_paths = _compile_devflow_story_set(
+                repo_root=repo_root,
+                idea_id=event.idea_id,
+                story_set_id=story_set_id,
+                story_paths=story_paths,
+                planes=event.planes,
+                story_plane_adjudication=task_context.metadata.get("story_plane_adjudication"),
+                pass_index=pass_index,
+                prior_validation_issues=validation_issues,
+                force_rebuild=pass_index > 1,
+            )
+            validation_workspace = _build_devflow_story_validation_workspace(
+                root=root,
+                compiled_paths=compiled_paths,
+                pass_index=pass_index,
+            )
+            pass_report_path = root / f"validation_pass_{pass_index:03d}.json"
+            validator = _run_devflow_story_validator(
+                engine_root=engine_root,
+                validation_repo_root=validation_workspace,
+                report_path=pass_report_path,
+            )
+            validation_report = _load_json_report(pass_report_path)
+            validation_report.setdefault("ok", validator.returncode == 0)
+            validation_report.setdefault("issue_count", len(validation_report.get("issues") or []))
+            validation_report.setdefault("issues", [])
+            validation_issues = list(validation_report.get("issues") or [])
+            validation_history.append(
+                {
+                    "pass_index": pass_index,
+                    "ok": bool(validation_report.get("ok")),
+                    "issue_count": int(validation_report.get("issue_count") or 0),
+                    "issues": validation_issues,
+                    "validator_returncode": validator.returncode,
+                    "validator_stdout": validator.stdout,
+                    "validator_stderr": validator.stderr,
+                    "validator_report_path": str(pass_report_path),
+                }
+            )
+            if validation_report.get("ok"):
+                break
+
+        assert root is not None
+        manifest = json.loads((root / "manifest.json").read_text(encoding="utf-8"))
+        consolidated_report = {
+            "devflow_story_set_id": compile_id,
+            "idea_id": event.idea_id,
+            "ok": bool(validation_report.get("ok")),
+            "pass_count": len(validation_history),
+            "history": validation_history,
+            "final_issues": validation_issues,
+            "final_issue_count": len(validation_issues),
+        }
+        consolidated_report_path = root / "validation_report.json"
+        _write_json(consolidated_report_path, consolidated_report)
+        store.add_artifact(
+            run_id=run_id,
+            node_exec_id=node_exec_id,
+            kind="devflow_story_validation_report",
+            uri=str(consolidated_report_path),
+            metadata=consolidated_report,
+            content_type="application/json",
+            byte_size=len(json.dumps(consolidated_report, sort_keys=True)),
+        )
+
+        if not validation_report.get("ok"):
+            stage_payload = {
+                "devflow_story_set_id": compile_id,
+                "devflow_stories_dir": str(root),
+                "story_paths": manifest.get("story_paths", []),
+                "source_story_set_id": story_set_id,
+                "planes": event.planes,
+                "validation": {
+                    "ok": False,
+                    "issue_count": len(validation_issues),
+                    "issues": validation_issues,
+                    "pass_count": len(validation_history),
+                    "history": validation_history,
+                    "report_path": str(consolidated_report_path),
+                },
+            }
+            pipeline_dir = _pipeline_root(repo_root, idea_id=event.idea_id, pipeline_key=event.pipeline_key)
+            stage_path = pipeline_dir / "devflow_story_compilation.json"
+            _write_json(stage_path, stage_payload)
+            failure_payload = _handoff_failure_payload(
+                stage="devflow_story_compilation",
+                idea_id=event.idea_id,
+                pipeline_dir=pipeline_dir,
+                story_set_id=story_set_id or None,
+                devflow_story_set_id=compile_id or None,
+                details=stage_payload.get("validation") or {},
+                resume_cursor=_resume_cursor_for_story_pipeline(pipeline_dir=pipeline_dir, story_set_id=story_set_id or None),
+            )
+            _write_handoff_failure(pipeline_dir=pipeline_dir, payload=failure_payload)
+            store.mark_node_finished(
+                node_exec_id=node_exec_id,
+                status="failed",
+                output=stage_payload,
+                error={"message": "story contract validation failed"},
+            )
+            task_context.metadata["message"] = (
+                f"dag_id: {DAG_ID}\n"
+                f"pipeline_dir: {_pipeline_root(repo_root, idea_id=event.idea_id, pipeline_key=event.pipeline_key)}\n"
+                f"story contract validation failed after {len(validation_history)} pass(es)\n"
+                f"{json.dumps(stage_payload['validation'], indent=2, sort_keys=True)}\n"
+            )
+            task_context.metadata["exit_code"] = 1
+            task_context.stop_workflow()
+            return task_context
+
+        project_entry = find_project_for_repo_root(repo_root)
+        project_id = None if project_entry is None else str(project_entry.get("project_id") or "") or None
+        story_artifact_ids: list[str] = []
+        for compiled_path in compiled_paths:
+            story_payload = json.loads(compiled_path.read_text(encoding="utf-8"))
+            artifact_id = store.add_artifact(
+                run_id=run_id,
+                node_exec_id=node_exec_id,
+                kind="generated_devflow_story_json",
+                uri=str(compiled_path),
+                metadata=story_payload,
+                content_type="application/json",
+                byte_size=len(json.dumps(story_payload, sort_keys=True)),
+            )
+            story_artifact_ids.append(artifact_id)
+            store.enqueue_story_task(
+                project_id=project_id,
+                enqueue_run_id=run_id,
+                story_artifact_id=artifact_id,
+                story_id=str(story_payload.get("story_id") or ""),
+                title=str(story_payload.get("title") or ""),
+            )
+
+        manifest["story_artifact_ids"] = story_artifact_ids
+        (root / "manifest.json").write_text(json.dumps(manifest, indent=2, sort_keys=True), encoding="utf-8")
+        stage_payload = {
+            "devflow_story_set_id": compile_id,
+            "devflow_stories_dir": str(root),
+            "story_paths": manifest.get("story_paths", []),
+            "story_artifact_ids": story_artifact_ids,
+            "source_story_set_id": story_set_id,
+            "planes": event.planes,
+            "project_id": project_id,
+            "validation": {
+                "ok": True,
+                "issue_count": 0,
+                "issues": [],
+                "pass_count": len(validation_history),
+                "history": validation_history,
+                "report_path": str(consolidated_report_path),
+            },
+        }
+        stage_path = _pipeline_root(repo_root, idea_id=event.idea_id, pipeline_key=event.pipeline_key) / "devflow_story_compilation.json"
+        _write_json(stage_path, stage_payload)
+        store.add_artifact(run_id=run_id, node_exec_id=node_exec_id, kind="devflow_story_set", uri=str(stage_path), metadata=stage_payload)
+        store.mark_node_finished(node_exec_id=node_exec_id, status="succeeded", output=stage_payload)
+        task_context.metadata["devflow_story_set_id"] = compile_id
+        task_context.metadata["pipeline_dir"] = str(_pipeline_root(repo_root, idea_id=event.idea_id, pipeline_key=event.pipeline_key))
+        pass_count = int((task_context.metadata.get("traditional_story_sufficiency") or {}).get("pass_count") or 1)
+        task_context.metadata["message"] = (
+            f"dag_id: {DAG_ID}\n"
+            f"pipeline_dir: {_pipeline_root(repo_root, idea_id=event.idea_id, pipeline_key=event.pipeline_key)}\n"
+            f"traditional_story_sufficiency_pass: {pass_count}/3\n"
+            f"story_set_id: {story_set_id}\n"
+            f"stories_dir: {get_idea_paths(repo_root, idea_id=event.idea_id).idea_dir / 'traditional_user_stories' / story_set_id}\n"
+            f"devflow_story_set_id: {compile_id}\n"
+            f"devflow_stories_dir: {root}\n"
+        )
+        return task_context
+
+
+class IdeaToDevflowStoriesWorkflow(Workflow):
+    workflow_schema = WorkflowSchema(
+        description="Idea to DevFlow stories DAG (GenAI workflow framework)",
+        event_schema=IdeaStoryDagEvent,
+        start=SufficiencyGateNode,
+        nodes=[
+            NodeConfig(node=SufficiencyGateNode, connections=[ActorRegistryNormalizationNode]),
+            NodeConfig(node=ActorRegistryNormalizationNode, connections=[PlaneRequirementGateNode]),
+            NodeConfig(node=PlaneRequirementGateNode, connections=[StoryCoverageRequirementsNode]),
+            NodeConfig(node=StoryCoverageRequirementsNode, connections=[TraditionalStoryGenerationNode]),
+            NodeConfig(node=TraditionalStoryGenerationNode, connections=[TraditionalStoryCoverageGateNode]),
+            NodeConfig(node=TraditionalStoryCoverageGateNode, connections=[TraditionalStoryDecompositionNode]),
+            NodeConfig(node=TraditionalStoryDecompositionNode, connections=[StoryPlaneAdjudicationNode]),
+            NodeConfig(node=StoryPlaneAdjudicationNode, connections=[DevflowStoryCompilationNode]),
+            NodeConfig(node=DevflowStoryCompilationNode, connections=[]),
+        ],
+    )
+
+
+def _handoff_failure_payload(*, stage: str, idea_id: str, pipeline_dir: Path, story_set_id: str | None = None, devflow_story_set_id: str | None = None, details: dict[str, Any] | None = None, resume_cursor: dict[str, Any] | None = None) -> dict[str, Any]:
+    return {
+        "idea_id": idea_id,
+        "failed_stage": stage,
+        "story_set_id": story_set_id,
+        "devflow_story_set_id": devflow_story_set_id,
+        "pipeline_dir": str(pipeline_dir),
+        "resume_cursor": resume_cursor,
+        "details": details or {},
+    }
+
+
+def _write_handoff_failure(*, pipeline_dir: Path, payload: dict[str, Any]) -> Path:
+    path = pipeline_dir / "handoff_failure.json"
+    _write_json(path, payload)
+    return path
+
+
+def _resume_cursor_for_story_pipeline(*, pipeline_dir: Path, story_set_id: str | None) -> dict[str, Any]:
+    if not (pipeline_dir / "story_plane_adjudication.json").exists():
+        return {"kind": "idea_to_devflow_stories", "stage": "story_plane_adjudication", "pipeline_dir": str(pipeline_dir), "story_set_id": story_set_id}
+    if not (pipeline_dir / "devflow_story_compilation.json").exists():
+        return {"kind": "idea_to_devflow_stories", "stage": "devflow_story_compilation", "pipeline_dir": str(pipeline_dir), "story_set_id": story_set_id}
+    return {"kind": "idea_to_devflow_stories", "stage": "retry_pipeline", "pipeline_dir": str(pipeline_dir), "story_set_id": story_set_id}
+
+
+def _load_pipeline_stage(pipeline_dir: Path, stage_name: str) -> dict[str, Any]:
+    path = pipeline_dir / f"{stage_name}.json"
+    if not path.exists():
+        return {}
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    return payload if isinstance(payload, dict) else {}
+
+
+def _resume_story_pipeline_context(*, repo_root: Path, event: IdeaStoryDagEvent, pipeline_dir: Path) -> tuple[TaskContext, type[Node]] | None:
+    handoff_failure_path = pipeline_dir / "handoff_failure.json"
+    handoff_failure: dict[str, Any] = {}
+    stage = ""
+    if handoff_failure_path.exists():
+        loaded = json.loads(handoff_failure_path.read_text(encoding="utf-8"))
+        if isinstance(loaded, dict):
+            handoff_failure = loaded
+            resume_cursor = handoff_failure.get("resume_cursor") if isinstance(handoff_failure.get("resume_cursor"), dict) else {}
+            if str(resume_cursor.get("kind") or "") == "idea_to_devflow_stories":
+                stage = str(resume_cursor.get("stage") or handoff_failure.get("failed_stage") or "").strip()
+
+    generation_payload = _load_pipeline_stage(pipeline_dir, "traditional_story_generation")
+    coverage_payload = _load_pipeline_stage(pipeline_dir, "traditional_story_coverage_gate")
+    decomposition_payload = _load_pipeline_stage(pipeline_dir, "traditional_story_decomposition")
+    plane_payload = _load_pipeline_stage(pipeline_dir, "story_plane_adjudication")
+    compilation_payload = _load_pipeline_stage(pipeline_dir, "devflow_story_compilation")
+    story_paths = [repo_root / Path(path_str) for path_str in (generation_payload.get("story_paths") or []) if str(path_str).strip()]
+    if not story_paths or not all(path.exists() for path in story_paths):
+        return None
+
+    if not stage:
+        if plane_payload.get("stories") and not compilation_payload:
+            stage = "devflow_story_compilation"
+        elif decomposition_payload.get("decomposition") and not plane_payload:
+            stage = "story_plane_adjudication"
+        elif coverage_payload.get("sufficiency") and not decomposition_payload:
+            stage = "traditional_story_decomposition"
+        elif coverage_payload.get("sufficiency") and decomposition_payload and not plane_payload:
+            stage = "story_plane_adjudication"
+        else:
+            return None
+
+    start_node: type[Node]
+    if stage == "devflow_story_compilation" and (plane_payload.get("stories") or plane_payload.get("candidate_planes")):
+        start_node = DevflowStoryCompilationNode
+    elif stage == "story_plane_adjudication" and decomposition_payload.get("decomposition"):
+        start_node = StoryPlaneAdjudicationNode
+    elif stage == "traditional_story_decomposition" and coverage_payload.get("sufficiency"):
+        start_node = TraditionalStoryDecompositionNode
+    else:
+        return None
+
+    ctx = TaskContext(event=event)
+    ctx.metadata["story_set_id"] = str(generation_payload.get("story_set_id") or handoff_failure.get("story_set_id") or "") or None
+    ctx.metadata["stories_dir"] = str(generation_payload.get("stories_dir") or "")
+    ctx.metadata["story_paths"] = [str(path) for path in story_paths]
+    ctx.metadata["traditional_story_sufficiency"] = dict(coverage_payload.get("sufficiency") or generation_payload.get("sufficiency") or {})
+    if decomposition_payload.get("decomposition"):
+        ctx.metadata["traditional_story_decomposition"] = dict(decomposition_payload.get("decomposition") or {})
+    if plane_payload.get("stories") or plane_payload.get("candidate_planes"):
+        ctx.metadata["story_plane_adjudication"] = dict(plane_payload)
+    return ctx, start_node
+
+
+def build_pipeline_key(
+    *,
+    repo_root: Path,
+    idea_id: str,
+    text: str | None,
+    source_path: Path | None,
+    max_stories: int,
+    planes: list[str],
+) -> str:
+    payload = _read_idea_payload(repo_root, idea_id=idea_id)
+    if source_path is not None or text:
+        raw_text, _ = load_idea_source(text=text, source_path=source_path)
+        source_payload: dict[str, Any] = {"raw_text": raw_text}
+    else:
+        source_payload = {"sufficient_idea": payload.get("sufficient_idea"), "idea_id": idea_id}
+    return _stable_id(
+        "run_",
+        {
+            "idea_id": idea_id,
+            "max_stories": max_stories,
+            "planes": _parse_list_option(planes),
+            "source": source_payload,
+        },
+    )
+
+
+async def run_idea_to_devflow_stories_dag_async(
+    *,
+    repo_root: Path,
+    store: ExecutionStore,
+    idea_id: str,
+    text: str | None,
+    source_path: Path | None,
+    max_stories: int,
+    planes: list[str],
+) -> IdeaStoryDagResult:
+    normalized_planes = _validate_candidate_planes(_parse_list_option(planes))
+    pipeline_key = build_pipeline_key(
+        repo_root=repo_root,
+        idea_id=idea_id,
+        text=text,
+        source_path=source_path,
+        max_stories=max_stories,
+        planes=normalized_planes,
+    )
+    pipeline_dir = _pipeline_root(repo_root, idea_id=idea_id, pipeline_key=pipeline_key)
+    pipeline_dir.mkdir(parents=True, exist_ok=True)
+
+    run_id = store.create_run(
+        dag_id=DAG_ID,
+        dag_version="v1",
+        root_correlation_id=f"corr_{pipeline_key}",
+        config={
+            "idea_id": idea_id,
+            "pipeline_key": pipeline_key,
+            "max_stories": max_stories,
+            "planes": normalized_planes,
+        },
+    )
+    store.mark_run_started(run_id=run_id)
+
+    wf = IdeaToDevflowStoriesWorkflow()
+    event_payload = {
+        "repo_root": str(repo_root),
+        "idea_id": idea_id,
+        "raw_text": text,
+        "source_path": str(source_path) if source_path else None,
+        "max_stories": max_stories,
+        "planes": normalized_planes,
+        "pipeline_key": pipeline_key,
+    }
+    resume_plan = _resume_story_pipeline_context(
+        repo_root=repo_root,
+        event=IdeaStoryDagEvent(**event_payload),
+        pipeline_dir=pipeline_dir,
+    )
+    # Publish initial state so DFS shows the pipeline started
+    _dfs_running(repo_root=repo_root, idea_id=idea_id, run_id=run_id, summary="Starting story generation pipeline")
+    _update_idea_pipeline_status(repo_root=repo_root, idea_id=idea_id, status="generating_stories")
+
+    global _CURRENT_STORE, _CURRENT_RUN_ID
+    _CURRENT_STORE = store
+    _CURRENT_RUN_ID = run_id
+    try:
+        if resume_plan is None:
+            ctx = await wf._run(event_payload)
+        else:
+            ctx, start_node = resume_plan
+            current_node_class: type[Node] | None = start_node
+            while current_node_class:
+                if ctx.should_stop:
+                    break
+                current_node = wf.nodes[current_node_class].node
+                ctx = await current_node(task_context=ctx).process(ctx)
+                current_node_class = await wf._get_next_node_class(current_node_class, ctx)
+    except Exception as exc:
+        store.mark_run_finished(run_id=run_id, status="failed")
+        _dfs_terminal(repo_root=repo_root, idea_id=idea_id, run_id=run_id, summary="Story generation failed", current_state="failed", current_status="failed", error_message=str(exc))
+        _update_idea_pipeline_status(repo_root=repo_root, idea_id=idea_id, status="generation_failed")
+        raise
+    finally:
+        _CURRENT_STORE = None
+        _CURRENT_RUN_ID = None
+
+    exit_code = int(ctx.metadata.get("exit_code") or 0)
+    store.mark_run_finished(run_id=run_id, status="succeeded" if exit_code == 0 else "failed")
+    if exit_code == 0 and ctx.metadata.get("devflow_story_set_id"):
+        _sync_devflow_stories_to_supabase(
+            repo_root=repo_root,
+            idea_id=idea_id,
+            run_id=run_id,
+            devflow_story_set_id=str(ctx.metadata.get("devflow_story_set_id")),
+        )
+
+    if exit_code == 0:
+        _dfs_terminal(
+            repo_root=repo_root,
+            idea_id=idea_id,
+            run_id=run_id,
+            summary="Story generation complete",
+            current_state="completed",
+            current_status="succeeded",
+        )
+        _update_idea_pipeline_status(repo_root=repo_root, idea_id=idea_id, status="stories_generated")
+    else:
+        _dfs_terminal(
+            repo_root=repo_root,
+            idea_id=idea_id,
+            run_id=run_id,
+            summary="Story generation failed",
+            current_state="failed",
+            current_status="failed",
+        )
+        _update_idea_pipeline_status(repo_root=repo_root, idea_id=idea_id, status="generation_failed")
+
+    handoff_failure_path = pipeline_dir / "handoff_failure.json"
+    handoff_failure = json.loads(handoff_failure_path.read_text(encoding="utf-8")) if handoff_failure_path.exists() else {}
+    return IdeaStoryDagResult(
+        exit_code=exit_code,
+        run_id=run_id,
+        pipeline_dir=pipeline_dir,
+        message=str(ctx.metadata.get("message") or ""),
+        story_set_id=ctx.metadata.get("story_set_id"),
+        devflow_story_set_id=ctx.metadata.get("devflow_story_set_id"),
+        failed_stage=str(handoff_failure.get("failed_stage") or "") or None,
+        resume_cursor=handoff_failure.get("resume_cursor") if isinstance(handoff_failure.get("resume_cursor"), dict) else None,
+    )
+
+
+def run_idea_to_devflow_stories_dag(
+    *,
+    repo_root: Path,
+    store: ExecutionStore,
+    idea_id: str,
+    text: str | None,
+    source_path: Path | None,
+    max_stories: int,
+    planes: list[str],
+) -> IdeaStoryDagResult:
+    wf = IdeaToDevflowStoriesWorkflow()
+    _ = wf
+    import asyncio
+
+    return asyncio.run(
+        run_idea_to_devflow_stories_dag_async(
+            repo_root=repo_root,
+            store=store,
+            idea_id=idea_id,
+            text=text,
+            source_path=source_path,
+            max_stories=max_stories,
+            planes=planes,
+        )
+    )