devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/idea/idea_creation_dag.py

@@ -0,0 +1,643 @@
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import os
+import re
+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 ..stores.execution_store import ExecutionStore
+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 .paths import get_idea_paths
+
+DAG_ID = "idea_creation_dag"
+
+_CURRENT_STORE: ExecutionStore | None = None
+_CURRENT_RUN_ID: str | None = None
+
+
+@dataclass(frozen=True)
+class IdeaCreationDagResult:
+    exit_code: int
+    run_id: str
+    pipeline_dir: Path
+    message: str
+    outcome: dict[str, Any]
+
+
+class IdeaCreationDagEvent(BaseModel):
+    repo_root: str
+    idea_id: str
+    project_id: str | None = None
+    text: str | None = None
+    source_path: str | None = None
+    pipeline_key: str
+
+
+REQUIRED_CONTRACT_FIELDS = (
+    "summary",
+    "problem_statement",
+    "target_users",
+    "desired_outcomes",
+    "initial_scope",
+    "constraints",
+    "acceptance_criteria",
+)
+
+
+STOPWORDS = {
+    "the", "and", "for", "with", "that", "this", "from", "into", "your", "their", "them", "then", "when", "have", "will", "would",
+    "should", "could", "build", "app", "tool", "platform", "system", "users", "user", "team", "workflow", "workflows", "core",
+}
+
+
+def _store_run() -> tuple[ExecutionStore, str]:
+    if _CURRENT_STORE is None or _CURRENT_RUN_ID is None:
+        raise RuntimeError("idea creation dag 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 _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 _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 _load_json(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    return payload if isinstance(payload, dict) else {}
+
+
+def _keychain_get(service: str, account: str) -> str | None:
+    try:
+        import subprocess
+        proc = subprocess.run(
+            ["security", "find-generic-password", "-s", service, "-a", account, "-w"],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=10,
+        )
+    except Exception:
+        return None
+    if proc.returncode != 0:
+        return None
+    value = proc.stdout.strip()
+    return value or None
+
+
+def _resolve_supabase_rest_config() -> tuple[str, str] | None:
+    if os.environ.get("PYTEST_CURRENT_TEST"):
+        return None
+    url = (
+        os.environ.get("DEVFLOW_SUPABASE_URL")
+        or os.environ.get("SUPABASE_URL")
+        or _keychain_get("Supabase URL", "Clarity")
+    )
+    key = (
+        os.environ.get("DEVFLOW_SUPABASE_SERVICE_KEY")
+        or os.environ.get("SUPABASE_SERVICE_ROLE_KEY")
+        or os.environ.get("SUPABASE_SERVICE_KEY")
+        or _keychain_get("Supabase Service Key", "Clarity")
+    )
+    if not url or not key:
+        return None
+    return url.rstrip("/"), key
+
+
+def _postgrest_request(*, method: str, url: str, key: str, body: Any | None = None, prefer: str | None = None) -> Any:
+    payload = None if body is None else json.dumps(body).encode("utf-8")
+    req = Request(url, data=payload, method=method)
+    req.add_header("apikey", key)
+    req.add_header("Authorization", f"Bearer {key}")
+    if body is not None:
+        req.add_header("Content-Type", "application/json")
+    if prefer:
+        req.add_header("Prefer", prefer)
+    with urlopen(req, timeout=30) as resp:
+        raw = resp.read().decode("utf-8")
+        return json.loads(raw) if raw else None
+
+
+def _tokenize(text: str) -> set[str]:
+    return {
+        token for token in re.findall(r"[a-z0-9]{3,}", (text or "").lower())
+        if token not in STOPWORDS
+    }
+
+
+def _jaccard(a: set[str], b: set[str]) -> float:
+    if not a or not b:
+        return 0.0
+    return len(a & b) / max(1, len(a | b))
+
+
+def _normalize_contract(*, idea_id: str, project_id: str | None, payload: dict[str, Any], raw_text: str | None) -> dict[str, Any]:
+    readiness = payload.get("readiness_contract") if isinstance(payload.get("readiness_contract"), dict) else payload
+    sufficient = payload.get("sufficient_idea") if isinstance(payload.get("sufficient_idea"), dict) else {}
+    initial_scope = readiness.get("initial_scope") if isinstance(readiness.get("initial_scope"), dict) else {}
+    normalized = {
+        "idea_id": idea_id,
+        "project_id": str(project_id or payload.get("project_id") or readiness.get("project_id") or "").strip() or None,
+        "summary": str(readiness.get("summary") or payload.get("summary") or sufficient.get("summary") or raw_text or idea_id).strip(),
+        "problem_statement": str(readiness.get("problem_statement") or sufficient.get("problem") or payload.get("problem_statement") or "").strip(),
+        "target_users": [str(item).strip() for item in (readiness.get("target_users") or sufficient.get("target_users") or []) if str(item).strip()],
+        "desired_outcomes": [str(item).strip() for item in (readiness.get("desired_outcomes") or sufficient.get("user_outcomes") or []) if str(item).strip()],
+        "initial_scope": {
+            "in_scope": [str(item).strip() for item in (initial_scope.get("in_scope") or sufficient.get("scope") or []) if str(item).strip()],
+            "out_of_scope": [str(item).strip() for item in (initial_scope.get("out_of_scope") or []) if str(item).strip()],
+        },
+        "constraints": [str(item).strip() for item in (readiness.get("constraints") or sufficient.get("constraints") or []) if str(item).strip()],
+        "acceptance_criteria": [str(item).strip() for item in (readiness.get("acceptance_criteria") or sufficient.get("acceptance_criteria") or []) if str(item).strip()],
+        "assumptions": list(readiness.get("assumptions") or payload.get("assumptions") or []),
+        "confidence": float(readiness.get("confidence") or payload.get("confidence") or 0.0),
+        "raw_text": raw_text or payload.get("latest_message") or "",
+        "source_contract": readiness,
+    }
+    return normalized
+
+
+def _missing_fields(contract: dict[str, Any]) -> list[str]:
+    missing: list[str] = []
+    for key in REQUIRED_CONTRACT_FIELDS:
+        value = contract.get(key)
+        if key == "initial_scope":
+            if not isinstance(value, dict) or not list(value.get("in_scope") or []):
+                missing.append(key)
+        elif value in (None, "", [], {}):
+            missing.append(key)
+    return missing
+
+
+def _scope_fragments(contract: dict[str, Any]) -> list[str]:
+    items = [
+        *[str(item).strip() for item in contract.get("desired_outcomes") or []],
+        *[str(item).strip() for item in (contract.get("initial_scope") or {}).get("in_scope") or []],
+    ]
+    deduped: list[str] = []
+    seen: set[str] = set()
+    for item in items:
+        if item and item not in seen:
+            deduped.append(item)
+            seen.add(item)
+    return deduped
+
+
+def evaluate_contract_sufficiency(contract: dict[str, Any]) -> dict[str, Any]:
+    missing = _missing_fields(contract)
+    assumptions = list(contract.get("assumptions") or [])
+    fragments = _scope_fragments(contract)
+    summary_tokens = _tokenize(str(contract.get("summary") or ""))
+    problem_tokens = _tokenize(str(contract.get("problem_statement") or ""))
+    fragment_tokens = [_tokenize(item) for item in fragments if item]
+
+    split_recommended = False
+    split_candidates: list[dict[str, Any]] = []
+    if len(fragment_tokens) >= 2:
+        anchor = fragment_tokens[0]
+        low_overlap = sum(1 for tokens in fragment_tokens[1:] if _jaccard(anchor, tokens) < 0.12)
+        if len(fragments) >= 3 and low_overlap >= 2:
+            split_recommended = True
+            for index, fragment in enumerate(fragments[:3], start=1):
+                split_candidates.append({
+                    "slot": index,
+                    "summary": fragment,
+                    "problem_statement": str(contract.get("problem_statement") or contract.get("summary") or "").strip(),
+                    "target_users": list(contract.get("target_users") or []),
+                    "desired_outcomes": [fragment],
+                    "initial_scope": {"in_scope": [fragment], "out_of_scope": []},
+                    "constraints": list(contract.get("constraints") or []),
+                    "acceptance_criteria": [fragment, *list(contract.get("acceptance_criteria") or [])[:1]],
+                    "assumptions": list(assumptions),
+                })
+
+    thin_signals: list[str] = []
+    if missing:
+        thin_signals.append("missing_required_fields")
+    if len(summary_tokens | problem_tokens) < 8:
+        thin_signals.append("very_low_specificity")
+    if len(fragments) <= 1:
+        thin_signals.append("single_fragment_scope")
+    if float(contract.get("confidence") or 0.0) < 0.55:
+        thin_signals.append("low_contract_confidence")
+    if len(assumptions) >= 5:
+        thin_signals.append("assumption_heavy")
+
+    if split_recommended:
+        decision = "split"
+        passed = True
+        rationale = "The contract bundles multiple low-overlap outcome/scope fragments that read like separate ideas."
+    elif thin_signals:
+        decision = "too_thin"
+        passed = False
+        rationale = "The contract is still too thin to persist as a coherent idea without pretending confidence."
+    else:
+        decision = "sufficient"
+        passed = True
+        rationale = "The contract is specific enough to stand as one coherent idea without splitting."
+
+    return {
+        "kind": "idea_contract_validation.v1",
+        "decision": decision,
+        "passed": passed,
+        "rationale": rationale,
+        "missing_fields": missing,
+        "thin_signals": thin_signals,
+        "split_candidates": split_candidates,
+        "validated_contract": contract,
+    }
+
+
+def build_creation_preview(*, idea_payload: dict[str, Any]) -> dict[str, Any]:
+    contract = _normalize_contract(
+        idea_id=str(idea_payload.get("idea_id") or "idea"),
+        project_id=str(idea_payload.get("project_id") or "") or None,
+        payload=idea_payload,
+        raw_text=str(idea_payload.get("latest_message") or idea_payload.get("summary") or ""),
+    )
+    validation = evaluate_contract_sufficiency(contract)
+    follow_up = None
+    if validation["decision"] == "too_thin":
+        missing = list(validation.get("missing_fields") or [])
+        biggest_gap = missing[0] if missing else "specificity"
+        follow_up = f"This is still too thin to build cleanly. Biggest gap: {biggest_gap}."
+    elif validation["decision"] == "split":
+        follow_up = "This likely wants to split into multiple ideas; don’t treat it as one by default."
+    else:
+        follow_up = "This reads as one coherent idea and can move into idea creation."
+    return {
+        "decision": validation["decision"],
+        "passed": bool(validation["passed"]),
+        "rationale": validation["rationale"],
+        "missing_fields": list(validation.get("missing_fields") or []),
+        "follow_up": follow_up,
+    }
+
+
+def build_creation_queue_items(*, idea_payload: dict[str, Any]) -> list[dict[str, Any]]:
+    base_idea_id = str(idea_payload.get("idea_id") or "idea").strip() or "idea"
+    project_id = str(idea_payload.get("project_id") or "").strip() or None
+    contract = _normalize_contract(
+        idea_id=base_idea_id,
+        project_id=project_id,
+        payload=idea_payload,
+        raw_text=str(idea_payload.get("latest_message") or idea_payload.get("summary") or ""),
+    )
+    validation = evaluate_contract_sufficiency(contract)
+    contracts = list(validation.get("split_candidates") or []) if validation.get("decision") == "split" else [dict(validation.get("validated_contract") or contract)]
+    items: list[dict[str, Any]] = []
+    for index, contract_payload in enumerate(contracts, start=1):
+        slot = int(contract_payload.get("slot") or index)
+        queued_idea_id = base_idea_id if validation.get("decision") != "split" else _stable_id(
+            "idea_",
+            {"parent": base_idea_id, "slot": slot, "summary": contract_payload.get("summary")},
+        )
+        payload = dict(idea_payload)
+        payload["idea_id"] = queued_idea_id
+        payload["project_id"] = project_id
+        payload["title"] = str(contract_payload.get("summary") or queued_idea_id)
+        payload["summary"] = str(contract_payload.get("summary") or queued_idea_id)
+        payload["readiness_contract"] = dict(contract_payload)
+        payload["sufficient_idea"] = {
+            "summary": contract_payload.get("summary"),
+            "problem": contract_payload.get("problem_statement"),
+            "target_users": list(contract_payload.get("target_users") or []),
+            "user_outcomes": list(contract_payload.get("desired_outcomes") or []),
+            "scope": list((contract_payload.get("initial_scope") or {}).get("in_scope") or []),
+            "constraints": list(contract_payload.get("constraints") or []),
+            "acceptance_criteria": list(contract_payload.get("acceptance_criteria") or []),
+        }
+        if validation.get("decision") == "split":
+            payload["parent_idea_id"] = base_idea_id
+        payload["idea_creation_queue"] = {
+            "decision": validation.get("decision"),
+            "rationale": validation.get("rationale"),
+            "slot": slot,
+            "parent_idea_id": base_idea_id if validation.get("decision") == "split" else None,
+        }
+        items.append({
+            "idea_id": queued_idea_id,
+            "title": str(contract_payload.get("summary") or queued_idea_id),
+            "payload": payload,
+            "validation_decision": str(validation.get("decision") or "sufficient"),
+            "slot": slot,
+        })
+    return items
+
+
+def _collect_relevant_paths(*, root: Path, query_tokens: list[str], allowed_suffixes: tuple[str, ...]) -> list[str]:
+    if not root.exists():
+        return []
+    matches: list[tuple[int, str]] = []
+    for path in root.rglob("*"):
+        if not path.is_file() or path.suffix.lower() not in allowed_suffixes:
+            continue
+        rel = str(path)
+        hay = rel.lower()
+        score = sum(3 for token in query_tokens if token and token in hay)
+        if score == 0:
+            try:
+                text = path.read_text(encoding="utf-8", errors="ignore")[:4000].lower()
+            except Exception:
+                text = ""
+            score = sum(1 for token in query_tokens if token and token in text)
+        if score > 0:
+            matches.append((score, rel))
+    matches.sort(key=lambda item: (-item[0], item[1]))
+    return [path for _score, path in matches[:12]]
+
+
+def _persist_local_idea(*, repo_root: Path, idea_id: str, payload: dict[str, Any]) -> str:
+    idea_path = get_idea_paths(repo_root, idea_id=idea_id).idea_dir / "idea.json"
+    idea_path.parent.mkdir(parents=True, exist_ok=True)
+    _write_json(idea_path, payload)
+    return str(idea_path)
+
+
+def _persist_supabase_ideas(*, rows: list[dict[str, Any]]) -> None:
+    config = _resolve_supabase_rest_config()
+    if config is None or not rows:
+        return
+    url, key = config
+    try:
+        _postgrest_request(
+            method="POST",
+            url=f"{url}/rest/v1/devflow_project_ideas?on_conflict=idea_id",
+            key=key,
+            body=rows,
+            prefer="resolution=merge-duplicates",
+        )
+    except Exception:
+        return
+
+
+def _dfs_running(*, project_id: str | None, run_id: str, idea_id: str, summary: str) -> 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=summary,
+        display="project",
+        display_path=f"idea:{idea_id}",
+    )
+
+
+def _dfs_terminal(*, project_id: str | None, run_id: str, idea_id: str, summary: str, current_state: str, current_status: str, error_message: str | None = None) -> 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=summary,
+        error_message=error_message,
+        display="project",
+        display_path=f"idea:{idea_id}",
+    )
+
+
+class ValidateIdeaContractNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        event = task_context.event
+        repo_root = Path(event.repo_root)
+        store, run_id = _store_run()
+        node_exec_id = store.create_node_attempt(run_id=run_id, node_id="validate_contract", node_name="ValidateIdeaContract", attempt=1)
+        payload = _load_json(Path(str(event.source_path))) if event.source_path else _load_json(get_idea_paths(repo_root, idea_id=event.idea_id).idea_dir / "idea.json")
+        contract = _normalize_contract(idea_id=event.idea_id, project_id=event.project_id, payload=payload, raw_text=event.text)
+        validation = evaluate_contract_sufficiency(contract)
+        stage_path = _pipeline_root(repo_root, idea_id=event.idea_id, pipeline_key=event.pipeline_key) / "validate_contract.json"
+        _write_json(stage_path, validation)
+        store.add_artifact(run_id=run_id, node_exec_id=node_exec_id, kind="idea_contract_validation", uri=str(stage_path), metadata=validation)
+        task_context.metadata["contract_validation"] = validation
+        if not validation["passed"]:
+            store.mark_node_finished(node_exec_id=node_exec_id, status="failed", output=validation, error={"message": validation["rationale"]})
+            task_context.metadata["outcome"] = {
+                "status": "contract_insufficient",
+                "idea_id": event.idea_id,
+                "validation": validation,
+            }
+            task_context.metadata["message"] = json.dumps(task_context.metadata["outcome"], 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=validation)
+        return task_context
+
+
+class GatherIdeaContextNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        event = task_context.event
+        repo_root = Path(event.repo_root)
+        store, run_id = _store_run()
+        node_exec_id = store.create_node_attempt(run_id=run_id, node_id="gather_context", node_name="GatherIdeaContext", attempt=1)
+        validation = dict(task_context.metadata.get("contract_validation") or {})
+        contracts = list(validation.get("split_candidates") or []) if validation.get("decision") == "split" else [dict(validation.get("validated_contract") or {})]
+        bundles: list[dict[str, Any]] = []
+        for index, contract in enumerate(contracts, start=1):
+            tokens = sorted({* _tokenize(str(contract.get("summary") or "")), * _tokenize(str(contract.get("problem_statement") or "")), * _tokenize(" ".join(contract.get("target_users") or [])), * _tokenize(" ".join(contract.get("desired_outcomes") or [])), * _tokenize(" ".join((contract.get("initial_scope") or {}).get("in_scope") or []))})
+            bundles.append({
+                "slot": index,
+                "contract": contract,
+                "retrieval_basis": tokens[:16],
+                "code_is_source_of_truth": True,
+                "code_paths": _collect_relevant_paths(root=repo_root / "src", query_tokens=tokens, allowed_suffixes=(".py", ".ts", ".tsx", ".js", ".jsx")),
+                "source_doc_paths": _collect_relevant_paths(root=repo_root / "ai_docs" / "context" / "source_docs", query_tokens=tokens, allowed_suffixes=(".json", ".md")),
+                "project_doc_paths": _collect_relevant_paths(root=repo_root / "ai_docs" / "context" / "v2" / "project_docs", query_tokens=tokens, allowed_suffixes=(".json", ".md")),
+            })
+        payload = {
+            "kind": "idea_context_bundle.v1",
+            "idea_id": event.idea_id,
+            "decision": validation.get("decision"),
+            "bundles": bundles,
+            "retrieval_policy": "contract-driven; code wins when code and docs diverge",
+        }
+        stage_path = _pipeline_root(repo_root, idea_id=event.idea_id, pipeline_key=event.pipeline_key) / "gather_context.json"
+        _write_json(stage_path, payload)
+        store.add_artifact(run_id=run_id, node_exec_id=node_exec_id, kind="idea_context_bundle", uri=str(stage_path), metadata={"bundle_count": len(bundles)})
+        store.mark_node_finished(node_exec_id=node_exec_id, status="succeeded", output=payload)
+        task_context.metadata["context_bundle"] = payload
+        return task_context
+
+
+class PersistIdeaNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        event = task_context.event
+        repo_root = Path(event.repo_root)
+        store, run_id = _store_run()
+        node_exec_id = store.create_node_attempt(run_id=run_id, node_id="persist", node_name="PersistIdea", attempt=1)
+        validation = dict(task_context.metadata.get("contract_validation") or {})
+        context_bundle = dict(task_context.metadata.get("context_bundle") or {})
+        project_id = str(event.project_id or (validation.get("validated_contract") or {}).get("project_id") or "").strip() or None
+        persisted_rows: list[dict[str, Any]] = []
+        persisted_local: list[dict[str, Any]] = []
+        for bundle in list(context_bundle.get("bundles") or []):
+            contract = dict(bundle.get("contract") or {})
+            slot = int(bundle.get("slot") or 1)
+            persisted_idea_id = event.idea_id if validation.get("decision") != "split" else _stable_id("idea_", {"parent": event.idea_id, "slot": slot, "summary": contract.get("summary")})
+            local_payload = {
+                "idea_id": persisted_idea_id,
+                "parent_idea_id": event.idea_id if validation.get("decision") == "split" else None,
+                "project_id": project_id,
+                "origin": "Devin",
+                "status": "ready_for_registration",
+                "shape": "sufficient",
+                "title": str(contract.get("summary") or persisted_idea_id),
+                "summary": str(contract.get("summary") or persisted_idea_id),
+                "sufficient_idea": {
+                    "summary": contract.get("summary"),
+                    "problem": contract.get("problem_statement"),
+                    "target_users": contract.get("target_users") or [],
+                    "user_outcomes": contract.get("desired_outcomes") or [],
+                    "scope": list((contract.get("initial_scope") or {}).get("in_scope") or []),
+                    "constraints": contract.get("constraints") or [],
+                    "acceptance_criteria": contract.get("acceptance_criteria") or [],
+                },
+                "readiness_contract": contract,
+                "idea_creation": {
+                    "validation_decision": validation.get("decision"),
+                    "validation_rationale": validation.get("rationale"),
+                    "context_bundle": bundle,
+                    "pipeline_dir": str(_pipeline_root(repo_root, idea_id=event.idea_id, pipeline_key=event.pipeline_key)),
+                    "run_id": run_id,
+                },
+            }
+            artifact_path = _persist_local_idea(repo_root=repo_root, idea_id=persisted_idea_id, payload=local_payload)
+            persisted_local.append({"idea_id": persisted_idea_id, "artifact_path": artifact_path})
+            persisted_rows.append({
+                "idea_id": persisted_idea_id,
+                "project_id": project_id,
+                "run_id": run_id,
+                "title": local_payload["title"],
+                "summary": local_payload["summary"],
+                "status": local_payload["status"],
+                "shape": local_payload["shape"],
+                "origin": "Devin",
+                "artifact_path": artifact_path,
+                "idea_payload": local_payload,
+                "updated_at": datetime.now(UTC).isoformat(),
+            })
+        _persist_supabase_ideas(rows=persisted_rows)
+        payload = {
+            "kind": "idea_persist_result.v1",
+            "idea_id": event.idea_id,
+            "project_id": project_id,
+            "decision": validation.get("decision"),
+            "persisted_ideas": persisted_local,
+            "supabase_rows_attempted": len(persisted_rows),
+            "local_state_written": True,
+        }
+        stage_path = _pipeline_root(repo_root, idea_id=event.idea_id, pipeline_key=event.pipeline_key) / "persist.json"
+        _write_json(stage_path, payload)
+        store.add_artifact(run_id=run_id, node_exec_id=node_exec_id, kind="idea_persist_result", uri=str(stage_path), metadata=payload)
+        store.mark_node_finished(node_exec_id=node_exec_id, status="succeeded", output=payload)
+        task_context.metadata["outcome"] = {
+            "status": "completed",
+            "idea_id": event.idea_id,
+            "decision": validation.get("decision"),
+            "persisted_ideas": persisted_local,
+            "idea_creation_run_id": run_id,
+            "idea_creation_pipeline_dir": str(_pipeline_root(repo_root, idea_id=event.idea_id, pipeline_key=event.pipeline_key)),
+        }
+        task_context.metadata["message"] = json.dumps(task_context.metadata["outcome"], indent=2, sort_keys=True) + "\n"
+        task_context.metadata["exit_code"] = 0
+        return task_context
+
+
+class IdeaCreationWorkflow(Workflow):
+    workflow_schema = WorkflowSchema(
+        description="Idea creation DAG (validate contract -> gather context -> persist)",
+        event_schema=IdeaCreationDagEvent,
+        start=ValidateIdeaContractNode,
+        nodes=[
+            NodeConfig(node=ValidateIdeaContractNode, connections=[GatherIdeaContextNode]),
+            NodeConfig(node=GatherIdeaContextNode, connections=[PersistIdeaNode]),
+            NodeConfig(node=PersistIdeaNode, connections=[]),
+        ],
+    )
+
+
+def build_pipeline_key(*, repo_root: Path, idea_id: str, text: str | None, source_path: Path | None) -> str:
+    return _stable_id("run_", {"repo_root": str(repo_root), "idea_id": idea_id, "text": text or "", "source_path": str(source_path) if source_path else None})
+
+
+async def run_idea_creation_dag_async(*, repo_root: Path, store: ExecutionStore, idea_id: str, project_id: str | None, text: str | None, source_path: Path | None) -> IdeaCreationDagResult:
+    pipeline_key = build_pipeline_key(repo_root=repo_root, idea_id=idea_id, text=text, source_path=source_path)
+    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, "project_id": project_id},
+    )
+    store.mark_run_started(run_id=run_id)
+    _dfs_running(project_id=project_id, run_id=run_id, idea_id=idea_id, summary="Creating idea from contract")
+    wf = IdeaCreationWorkflow()
+    global _CURRENT_STORE, _CURRENT_RUN_ID
+    _CURRENT_STORE = store
+    _CURRENT_RUN_ID = run_id
+    try:
+        ctx = await asyncio.to_thread(
+            wf.run,
+            {
+                "repo_root": str(repo_root),
+                "idea_id": idea_id,
+                "project_id": project_id,
+                "text": text,
+                "source_path": str(source_path) if source_path else None,
+                "pipeline_key": pipeline_key,
+            },
+        )
+    except Exception as exc:
+        store.mark_run_finished(run_id=run_id, status="failed")
+        _dfs_terminal(project_id=project_id, run_id=run_id, idea_id=idea_id, summary="Idea creation failed", current_state="failed", current_status="failed", error_message=str(exc))
+        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:
+        _dfs_terminal(project_id=project_id, run_id=run_id, idea_id=idea_id, summary="Idea creation complete", current_state="completed", current_status="succeeded")
+    else:
+        _dfs_terminal(project_id=project_id, run_id=run_id, idea_id=idea_id, summary="Idea creation blocked", current_state="failed", current_status="failed", error_message=str(ctx.metadata.get("message") or "contract insufficient"))
+    return IdeaCreationDagResult(
+        exit_code=exit_code,
+        run_id=run_id,
+        pipeline_dir=pipeline_dir,
+        message=str(ctx.metadata.get("message") or ""),
+        outcome=dict(ctx.metadata.get("outcome") or {}),
+    )
+
+
+def run_idea_creation_dag(*, repo_root: Path, store: ExecutionStore, idea_id: str, project_id: str | None, text: str | None, source_path: Path | None) -> IdeaCreationDagResult:
+    return asyncio.run(run_idea_creation_dag_async(repo_root=repo_root, store=store, idea_id=idea_id, project_id=project_id, text=text, source_path=source_path))