devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/project_registration/dag.py

@@ -0,0 +1,1581 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+import sqlite3
+import subprocess
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from hashlib import sha256
+from pathlib import Path
+from typing import Any, Callable
+from urllib.parse import quote
+from urllib.request import Request, urlopen
+
+from pydantic import BaseModel
+
+from ..stores.execution_store import ExecutionStore
+from ..source_docs_updater import ensure_source_doc_scaffold
+from ..devflow_state import publish_devflow_state
+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
+
+
+DAG_ID = "project_registration_dag"
+
+RegistrationCallback = Callable[[Path], None]
+
+_CURRENT_STORE: ExecutionStore | None = None
+_CURRENT_RUN_ID: str | None = None
+_CURRENT_REGISTER_REPO: RegistrationCallback | None = None
+
+
+@dataclass(frozen=True)
+class ProjectRegistrationDagResult:
+    exit_code: int
+    run_id: str
+    project_id: str
+    registration_state: str
+    pipeline_dir: Path
+    repo_root: Path
+    workspace_path: Path
+    registry_entry: dict[str, object]
+    state_history: list[dict[str, str]]
+    message: str
+
+
+class StateHistoryRecord(BaseModel):
+    state: str
+    timestamp: str
+
+
+class ProjectRegistrationDagEvent(BaseModel):
+    repo_root: str
+    workspace_path: str
+    remote_url: str | None = None
+    project_name: str | None = None
+    command_name: str
+    project_id: str
+    pipeline_key: str
+    occurred_at: str
+
+
+class ProjectShellArtifact(BaseModel):
+    dag_id: str
+    project_id: str
+    owner: str
+    repo: str
+    repo_root: str
+    workspace_path: str
+    remote_url: str | None = None
+    registration_command: str
+    registration_state: str
+    state_history: list[StateHistoryRecord]
+    created_at: str
+    updated_at: str
+
+
+class BindingRequestArtifact(BaseModel):
+    dag_id: str
+    project_id: str
+    registration_state: str
+    state_history: list[StateHistoryRecord]
+    project_shell_ref: str
+    state_history_ref: str
+    registry_entry_ref: str
+    created_at: str
+    updated_at: str
+
+
+class EngineRegistrationArtifact(BaseModel):
+    dag_id: str
+    project_id: str
+    registration_state: str
+    command_name: str
+    repo_root: str
+    workspace_path: str
+    remote_url: str | None = None
+    state_history: list[StateHistoryRecord]
+    ok: bool
+    error_message: str | None = None
+    created_at: str
+    updated_at: str
+
+
+class ProjectRegistrationSummary(BaseModel):
+    exit_code: int
+    run_id: str
+    pipeline_dir: str
+    message: str
+    outcome: dict[str, Any]
+
+
+class ProjectRegistrationArtifact(BaseModel):
+    dag_id: str
+    run_id: str
+    project_id: str
+    command_name: str
+    repo_root: str
+    workspace_path: str
+    remote_url: str | None = None
+    registration_state: str
+    state_history: list[StateHistoryRecord]
+    project_shell_ref: str
+    state_history_ref: str
+    engine_registration_ref: str
+    summary_ref: str
+    created_at: str
+    updated_at: str
+
+
+def _store_run() -> tuple[ExecutionStore, str]:
+    if _CURRENT_STORE is None or _CURRENT_RUN_ID is None:
+        raise RuntimeError("project registration dag missing runtime store/run_id")
+    return _CURRENT_STORE, _CURRENT_RUN_ID
+
+
+def _registration_callback() -> RegistrationCallback:
+    if _CURRENT_REGISTER_REPO is None:
+        raise RuntimeError("project registration dag missing repo registration callback")
+    return _CURRENT_REGISTER_REPO
+
+
+def _devflow_home() -> Path:
+    import os
+
+    base = os.environ.get("DEVFLOW_HOME") or os.environ.get("HOME")
+    if base:
+        return Path(base).expanduser().resolve()
+    return Path.home().resolve()
+
+
+def _projects_registry_path() -> Path:
+    return _devflow_home() / ".devflow" / "registry" / "projects.json"
+
+
+def _read_projects_registry() -> dict[str, object]:
+    path = _projects_registry_path()
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return {"schema_version": 1, "projects": []}
+    if not isinstance(raw, dict):
+        return {"schema_version": 1, "projects": []}
+    projects = raw.get("projects")
+    if not isinstance(projects, list):
+        projects = []
+    return {"schema_version": 1, "projects": projects}
+
+
+def _write_projects_registry(registry: dict[str, object]) -> None:
+    path = _projects_registry_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(registry, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def _workspace_hash(remote_url: str | None, repo_root: Path) -> str:
+    ident = (remote_url or f"local:{repo_root.resolve()}").strip().lower()
+    return sha256(ident.encode("utf-8")).hexdigest()[:8]
+
+
+def _infer_owner_repo(remote_url: str | None, repo_root: Path, project_name: str | None) -> tuple[str, str]:
+    if remote_url:
+        match = re.search(r"[:/](?P<owner>[^/]+)/(?P<repo>[^/]+?)(?:\.git)?$", remote_url)
+        if match:
+            return match.group("owner").lower(), match.group("repo").lower()
+    repo = (project_name or repo_root.name).strip().lower() or "project"
+    repo = re.sub(r"[^a-z0-9._-]+", "-", repo).strip("-") or "project"
+    return "local", repo
+
+
+def _stable_project_identity(*, repo_root: Path, remote_url: str | None, project_name: str | None) -> tuple[str, str, str]:
+    owner, repo = _infer_owner_repo(remote_url, repo_root, project_name)
+    workspace_hash = _workspace_hash(remote_url, repo_root)
+    return owner, repo, f"proj_{workspace_hash}"
+
+
+def _pipeline_root(repo_root: Path, project_id: str) -> Path:
+    return repo_root / ".devflow" / "projects" / project_id / "pipelines" / DAG_ID / "current"
+
+
+# ---------------------------------------------------------------------------
+# Supabase project UUID helpers
+# ---------------------------------------------------------------------------
+
+_UUID_RE = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+)
+
+
+def _is_uuid_like(value: str) -> bool:
+    """Return True if value looks like a UUID (8-4-4-4-12 hex)."""
+    return bool(_UUID_RE.match(value.lower()))
+
+
+def _resolve_supabase_config_for_registration() -> tuple[str, str] | None:
+    """Return (url, key) if Supabase is configured, else None.
+
+    Skipped during pytest runs to preserve test isolation.
+    """
+    if os.environ.get("PYTEST_CURRENT_TEST"):
+        return None
+    url = (
+        os.environ.get("DEVFLOW_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:
+        try:
+            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")
+        except Exception:
+            pass
+    if not url or not key:
+        return None
+    return url.rstrip("/"), key
+
+
+def _supabase_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 _lookup_supabase_project_uuid(
+    *,
+    url: str,
+    key: str,
+    repo_root: Path,
+    remote_url: str | None,
+    owner: str | None = None,
+    repo: str | None = None,
+) -> str | None:
+    """Return Supabase devflow_projects.id UUID for this project, or None.
+
+    Lookup order (most → least specific):
+    1. repo_url (case-insensitive ilike match)
+    2. devflow_repo_root (exact match — set when the project was first registered
+       from a local engine run; may be blank on UI-created rows)
+    3. repo_name (ilike match on the GitHub repo slug — reliable fallback for
+       rows created through the Supabase UI or API that never ran local import)
+    """
+    # 1. Try by remote_url first (most specific)
+    if remote_url:
+        stripped = remote_url.strip()
+        candidates: list[str] = []
+        for value in (stripped, stripped.lower()):
+            if value and value not in candidates:
+                candidates.append(value)
+            without_git = re.sub(r"\.git$", "", value, flags=re.IGNORECASE).rstrip("/")
+            if without_git and without_git not in candidates:
+                candidates.append(without_git)
+        for candidate in candidates:
+            rows = _supabase_request(
+                method="GET",
+                url=f"{url}/rest/v1/devflow_projects?select=id&repo_url=ilike.{quote(candidate)}&limit=1",
+                key=key,
+            )
+            if isinstance(rows, list) and rows:
+                val = str((rows[0] or {}).get("id") or "").strip()
+                if _is_uuid_like(val):
+                    return val
+
+    # 2. Try by devflow_repo_root (exact match)
+    resolved_root = str(repo_root.expanduser().resolve())
+    rows = _supabase_request(
+        method="GET",
+        url=f"{url}/rest/v1/devflow_projects?select=id&devflow_repo_root=eq.{quote(resolved_root)}&limit=1",
+        key=key,
+    )
+    if isinstance(rows, list) and rows:
+        val = str((rows[0] or {}).get("id") or "").strip()
+        if _is_uuid_like(val):
+            return val
+
+    # 3. Fallback: try by repo_name slug (ilike).
+    # This catches rows that were created via the UI / API before any local
+    # import ran, where devflow_repo_root is blank and repo_url may differ in
+    # format (e.g. missing .git suffix or different casing).
+    if repo:
+        rows = _supabase_request(
+            method="GET",
+            url=f"{url}/rest/v1/devflow_projects?select=id&repo_name=ilike.{quote(repo)}&limit=1",
+            key=key,
+        )
+        if isinstance(rows, list) and rows:
+            val = str((rows[0] or {}).get("id") or "").strip()
+            if _is_uuid_like(val):
+                return val
+
+    return None
+
+
+def _create_supabase_project_row(
+    *,
+    url: str,
+    key: str,
+    repo_root: Path,
+    remote_url: str | None,
+    project_name: str | None,
+    owner: str,
+    repo: str,
+) -> str:
+    """Create a new devflow_projects row and return its UUID.
+
+    Only sets columns that are available during local registration.
+    Raises RuntimeError if the insert fails.
+    """
+    resolved_root = str(repo_root.expanduser().resolve())
+    payload: dict[str, Any] = {
+        "name": project_name or repo or resolved_root.split("/")[-1],
+        "devflow_repo_root": resolved_root,
+        "status": "draft_unbound",
+        "metadata": {
+            "created_from": "devflow-engine",
+            "registration_mode": "local",
+        },
+    }
+    if remote_url:
+        payload["repo_url"] = remote_url
+    if owner and owner != "local":
+        payload["repo_owner"] = owner
+    if repo:
+        payload["repo_name"] = repo
+
+    rows = _supabase_request(
+        method="POST",
+        url=f"{url}/rest/v1/devflow_projects",
+        key=key,
+        body=payload,
+        prefer="return=representation",
+    )
+    if not isinstance(rows, list) or not rows:
+        raise RuntimeError("Failed to create devflow_projects row in Supabase")
+    val = str((rows[0] or {}).get("id") or "").strip()
+    if not _is_uuid_like(val):
+        raise RuntimeError(f"Supabase devflow_projects insert returned unexpected id: {val!r}")
+    return val
+
+
+def _update_supabase_devflow_project_id(
+    *,
+    url: str,
+    key: str,
+    supabase_uuid: str,
+) -> None:
+    """Update devflow_projects.devflow_project_id = supabase_uuid for the row."""
+    try:
+        _supabase_request(
+            method="PATCH",
+            url=f"{url}/rest/v1/devflow_projects?id=eq.{quote(supabase_uuid)}",
+            key=key,
+            body={"devflow_project_id": supabase_uuid},
+        )
+    except Exception:
+        pass  # Non-fatal: local state is correct, Supabase annotation is best-effort
+
+
+def _detect_repo_default_branch(repo_root: Path) -> str | None:
+    commands = [
+        ["git", "-C", str(repo_root), "symbolic-ref", "--short", "refs/remotes/origin/HEAD"],
+        ["git", "-C", str(repo_root), "symbolic-ref", "--short", "HEAD"],
+    ]
+    for command in commands:
+        try:
+            proc = subprocess.run(
+                command,
+                capture_output=True,
+                text=True,
+                check=False,
+                timeout=10,
+            )
+        except Exception:
+            continue
+        if proc.returncode != 0:
+            continue
+        value = proc.stdout.strip()
+        if not value:
+            continue
+        branch = value.rsplit("/", 1)[-1].strip()
+        if branch:
+            return branch
+    return None
+
+
+def _repair_supabase_project_row(
+    *,
+    url: str,
+    key: str,
+    supabase_uuid: str,
+    repo_root: Path,
+    remote_url: str | None,
+    project_name: str | None,
+    owner: str,
+    repo: str,
+    registration_status: str,
+) -> None:
+    resolved_root = str(repo_root.expanduser().resolve())
+    payload: dict[str, Any] = {
+        "devflow_repo_root": resolved_root,
+        "status": registration_status,
+    }
+    if remote_url:
+        payload["repo_url"] = remote_url
+    if project_name:
+        payload["name"] = project_name
+    if owner and owner != "local":
+        payload["repo_owner"] = owner
+    if repo:
+        payload["repo_name"] = repo
+    default_branch = _detect_repo_default_branch(repo_root)
+    if default_branch:
+        payload["repo_default_branch"] = default_branch
+    _supabase_request(
+        method="PATCH",
+        url=f"{url}/rest/v1/devflow_projects?id=eq.{quote(supabase_uuid)}",
+        key=key,
+        body=payload,
+    )
+
+
+def _publish_devflow_state_for_registration(
+    *,
+    project_id: str,
+    run_id: str,
+) -> None:
+    config = _resolve_supabase_config_for_registration()
+    if config is None:
+        return
+    publish_devflow_state(
+        project_id=project_id,
+        run_id=run_id,
+        current_state="project_registered",
+        current_status="idle",
+        run_summary="project registration complete",
+        display="project",
+        display_path=f"project:{project_id}",
+    )
+
+
+def _resolve_or_create_supabase_project_uuid(
+    *,
+    repo_root: Path,
+    remote_url: str | None,
+    project_name: str | None,
+    owner: str,
+    repo: str,
+) -> str | None:
+    """Return Supabase UUID for this project (look up or create).
+
+    Returns None when Supabase is not configured (e.g. during tests or
+    offline use). In that case the caller should fall back to the hash-based id.
+
+    Raises RuntimeError if Supabase IS configured but the operation fails.
+    """
+    config = _resolve_supabase_config_for_registration()
+    if config is None:
+        return None
+    url, key = config
+
+    try:
+        uuid = _lookup_supabase_project_uuid(
+            url=url,
+            key=key,
+            repo_root=repo_root,
+            remote_url=remote_url,
+            owner=owner,
+            repo=repo,
+        )
+        if uuid:
+            return uuid
+
+        # Not found → create a new row
+        return _create_supabase_project_row(
+            url=url,
+            key=key,
+            repo_root=repo_root,
+            remote_url=remote_url,
+            project_name=project_name,
+            owner=owner,
+            repo=repo,
+        )
+    except Exception as exc:
+        raise RuntimeError(
+            f"Supabase project UUID resolution failed for {repo_root}: {exc}"
+        ) from exc
+
+
+def _read_existing_local_project_uuid(
+    *,
+    repo_root: Path,
+    workspace_path: Path,
+    remote_url: str | None,
+) -> str | None:
+    """Return a UUID-like project_id already stored in the local projects registry
+    for this repo, if one exists.
+
+    This prevents `run_project_registration_dag` from asking Supabase to create a
+    second devflow_projects row (and therefore a second/drifted project identity)
+    when the same repo is imported or re-initialised after it was already
+    successfully registered.
+
+    The local registry is the in-process cache of the last Supabase UUID that was
+    resolved for this repo.  If the stored project_id is already UUID-shaped, it
+    IS the authoritative Supabase UUID and must be reused without a new lookup.
+    """
+    registry = _read_projects_registry()
+    projects = list(registry.get("projects", []))
+    resolved_root = str(repo_root.expanduser().resolve())
+    resolved_ws = str(workspace_path.expanduser().resolve())
+    for item in projects:
+        if not isinstance(item, dict):
+            continue
+        # Match by remote_url (most reliable)
+        if remote_url and item.get("remote_url") == remote_url:
+            pid = str(item.get("project_id") or "").strip()
+            if _is_uuid_like(pid):
+                return pid
+        # Match by workspace_path
+        ws = str(item.get("workspace_path") or "").strip()
+        if ws:
+            try:
+                if Path(ws).expanduser().resolve() == Path(resolved_ws):
+                    pid = str(item.get("project_id") or "").strip()
+                    if _is_uuid_like(pid):
+                        return pid
+            except Exception:
+                pass
+        # Match by repo_root
+        rr = str(item.get("repo_root") or "").strip()
+        if rr:
+            try:
+                if Path(rr).expanduser().resolve() == Path(resolved_root):
+                    pid = str(item.get("project_id") or "").strip()
+                    if _is_uuid_like(pid):
+                        return pid
+            except Exception:
+                pass
+    return None
+
+
+# ---------------------------------------------------------------------------
+
+
+def _write_json(path: Path, payload: dict[str, object]) -> 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 _jsonable_history(records: list[StateHistoryRecord]) -> list[dict[str, str]]:
+    return [item.model_dump() for item in records]
+
+
+def _find_existing_project_entry(
+    *,
+    projects: list[object],
+    repo_root: Path,
+    workspace_path: Path,
+    remote_url: str | None,
+) -> tuple[int | None, dict[str, object] | None]:
+    for idx, item in enumerate(projects):
+        if not isinstance(item, dict):
+            continue
+        if remote_url and item.get("remote_url") == remote_url:
+            return idx, item
+        if Path(str(item.get("workspace_path", ""))).expanduser() == workspace_path:
+            return idx, item
+        if Path(str(item.get("repo_root", ""))).expanduser() == repo_root:
+            return idx, item
+    return None, None
+
+
+def _upsert_registry_state(
+    *,
+    entry: dict[str, object],
+    found_index: int | None,
+    registry: dict[str, object],
+    projects: list[object],
+    state_history: list[StateHistoryRecord],
+    state: str,
+    timestamp: str,
+) -> tuple[int, dict[str, object]]:
+    seen_states = {item.state for item in state_history}
+    if state not in seen_states:
+        state_history.append(StateHistoryRecord(state=state, timestamp=timestamp))
+    entry["registration_state"] = state
+    entry["state_history"] = _jsonable_history(state_history)
+    entry["updated_at"] = timestamp
+    if state == "engine_registered":
+        entry["registered_at"] = timestamp
+    if state == "ready_for_source_scope":
+        entry["ready_for_source_scope_at"] = timestamp
+    if found_index is None:
+        projects.append(entry)
+        found_index = len(projects) - 1
+    else:
+        projects[found_index] = entry
+    registry["projects"] = projects
+    _write_projects_registry(registry)
+    return found_index, entry
+
+
+def _write_summary(
+    *,
+    pipeline_dir: Path,
+    exit_code: int,
+    run_id: str,
+    outcome: dict[str, Any],
+    message: str,
+) -> Path:
+    summary = ProjectRegistrationSummary(
+        exit_code=exit_code,
+        run_id=run_id,
+        pipeline_dir=str(pipeline_dir),
+        message=message,
+        outcome=outcome,
+    )
+    summary_path = pipeline_dir / "summary.json"
+    _write_json(summary_path, summary.model_dump())
+    return summary_path
+
+
+def _reconcile_execution_store_project_row(*, repo_root: Path, authoritative_project_id: str) -> None:
+    db_path = repo_root / ".devflow" / "execution.sqlite"
+    if not authoritative_project_id:
+        return
+
+    now = int(datetime.now(UTC).timestamp())
+    with sqlite3.connect(db_path) as conn:
+        conn.row_factory = sqlite3.Row
+        rows = conn.execute(
+            "SELECT rowid, project_id FROM projects WHERE repo_root=? ORDER BY created_at ASC, rowid ASC",
+            (str(repo_root),),
+        ).fetchall()
+        authoritative_rows = [row for row in rows if str(row["project_id"] or "") == authoritative_project_id]
+
+        if authoritative_rows:
+            keep_rowid = int(authoritative_rows[0]["rowid"])
+            conn.execute(
+                "DELETE FROM projects WHERE repo_root=? AND rowid<>?",
+                (str(repo_root), keep_rowid),
+            )
+            conn.execute(
+                "UPDATE projects SET project_id=?, name=?, repo_root=?, metadata_json=COALESCE(metadata_json, ?)"
+                " WHERE rowid=?",
+                (authoritative_project_id, authoritative_project_id, str(repo_root), json.dumps({}, sort_keys=True), keep_rowid),
+            )
+            conn.commit()
+            return
+
+        if rows:
+            keep_rowid = int(rows[0]["rowid"])
+            conn.execute(
+                "UPDATE projects SET project_id=?, name=?, repo_root=? WHERE rowid=?",
+                (authoritative_project_id, authoritative_project_id, str(repo_root), keep_rowid),
+            )
+            conn.execute(
+                "DELETE FROM projects WHERE repo_root=? AND rowid<>?",
+                (str(repo_root), keep_rowid),
+            )
+            conn.commit()
+            return
+
+        conn.execute(
+            "INSERT INTO projects(project_id, created_at, name, repo_root, metadata_json) VALUES(?,?,?,?,?)",
+            (authoritative_project_id, now, authoritative_project_id, str(repo_root), json.dumps({}, sort_keys=True)),
+        )
+        conn.commit()
+
+
+def _project_existing_local_artifacts_to_supabase(*, repo_root: Path, authoritative_project_id: str, run_id: str) -> None:
+    if not authoritative_project_id:
+        return
+
+    now = datetime.now(UTC).isoformat()
+
+    try:
+        from ..source_scope import dag as source_scope_dag
+
+        source_scope_cfg = source_scope_dag._resolve_supabase_rest_config()
+        if source_scope_cfg is not None:
+            source_scope_url, source_scope_key = source_scope_cfg
+            scope_rows: list[dict[str, Any]] = []
+            for scope_path in sorted((repo_root / ".devflow" / "scopes").glob("*/scope.json")):
+                try:
+                    payload = json.loads(scope_path.read_text(encoding="utf-8"))
+                except Exception:
+                    continue
+                scope_rows.append(
+                    {
+                        "scope_id": str(payload.get("scope_id") or scope_path.parent.name),
+                        "project_id": authoritative_project_id,
+                        "scope_set_id": payload.get("scope_set_id"),
+                        "run_id": run_id,
+                        "title": str(payload.get("title") or payload.get("scope_id") or scope_path.parent.name),
+                        "summary": payload.get("summary") or payload.get("description"),
+                        "status": payload.get("status"),
+                        "coverage_status": payload.get("coverage_status"),
+                        "review_status": payload.get("review_status"),
+                        "scope_set_title": payload.get("scope_set_title"),
+                        "source_traceability_refs": payload.get("source_traceability_refs") or [],
+                        "assumptions": payload.get("assumptions") or [],
+                        "depends_on": payload.get("depends_on") or [],
+                        "origin": "project_import",
+                        "artifact_path": str(scope_path),
+                        "updated_at": now,
+                    }
+                )
+            if scope_rows:
+                source_scope_dag._postgrest_request(
+                    method="POST",
+                    url=f"{source_scope_url}/rest/v1/devflow_project_scopes?on_conflict=scope_id",
+                    key=source_scope_key,
+                    body=scope_rows,
+                    prefer="resolution=merge-duplicates",
+                )
+    except Exception:
+        pass
+
+    try:
+        from ..scope_idea import dag as scope_idea_dag
+
+        scope_idea_cfg = scope_idea_dag._resolve_supabase_rest_config()
+        if scope_idea_cfg is not None:
+            scope_idea_url, scope_idea_key = scope_idea_cfg
+            idea_rows: list[dict[str, Any]] = []
+            for idea_path in sorted((repo_root / ".devflow" / "ideas").glob("*/idea.json")):
+                try:
+                    payload = json.loads(idea_path.read_text(encoding="utf-8"))
+                except Exception:
+                    continue
+                idea_rows.append(
+                    {
+                        "idea_id": str(payload.get("idea_id") or idea_path.parent.name),
+                        "project_id": authoritative_project_id,
+                        "scope_set_id": payload.get("scope_set_id"),
+                        "scope_id": payload.get("scope_id"),
+                        "run_id": run_id,
+                        "title": str(payload.get("title") or payload.get("idea_id") or idea_path.parent.name),
+                        "summary": payload.get("summary") or payload.get("description"),
+                        "status": payload.get("status"),
+                        "shape": payload.get("shape"),
+                        "resolution_status": payload.get("resolution_status"),
+                        "origin": "project_import",
+                        "artifact_path": str(idea_path),
+                        "updated_at": now,
+                    }
+                )
+            if idea_rows:
+                scope_idea_dag._postgrest_request(
+                    method="POST",
+                    url=f"{scope_idea_url}/rest/v1/devflow_project_ideas?on_conflict=idea_id",
+                    key=scope_idea_key,
+                    body=idea_rows,
+                    prefer="resolution=merge-duplicates",
+                )
+    except Exception:
+        pass
+
+    try:
+        from ..idea import story_pipeline
+
+        story_cfg = story_pipeline._resolve_supabase_rest_config()
+        if story_cfg is not None:
+            story_url, story_key = story_cfg
+            story_rows: list[dict[str, Any]] = []
+            ideas_root = repo_root / ".devflow" / "ideas"
+            for idea_dir in sorted([path for path in ideas_root.iterdir() if path.is_dir()] if ideas_root.exists() else []):
+                idea_id = idea_dir.name
+                for manifest_path in sorted((idea_dir / "devflow_story_sets").glob("*/manifest.json")):
+                    try:
+                        compiled_manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+                    except Exception:
+                        continue
+                    source_story_set_id = str(compiled_manifest.get("source_story_set_id") or "").strip()
+                    if not source_story_set_id:
+                        continue
+                    trad_manifest_path = idea_dir / "traditional_user_stories" / source_story_set_id / "manifest.json"
+                    if not trad_manifest_path.exists():
+                        continue
+                    try:
+                        trad_manifest = json.loads(trad_manifest_path.read_text(encoding="utf-8"))
+                    except Exception:
+                        continue
+                    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)}
+                    for index, trad_path in enumerate(sorted(trad_story_paths), start=1):
+                        if not trad_path.exists():
+                            continue
+                        title, _actor, acceptance, statement = story_pipeline._story_statement_from_traditional(
+                            trad_path.read_text(encoding="utf-8")
+                        )
+                        compiled_path = compiled_by_index.get(index)
+                        compiled_payload: dict[str, Any] = {}
+                        if compiled_path and compiled_path.exists():
+                            try:
+                                compiled_payload = json.loads(compiled_path.read_text(encoding="utf-8"))
+                            except Exception:
+                                compiled_payload = {}
+                        story_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": authoritative_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": manifest_path.parent.name,
+                                "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": now,
+                            }
+                        )
+            if story_rows:
+                story_pipeline._postgrest_request(
+                    method="POST",
+                    url=f"{story_url}/rest/v1/devflow_idea_stories?on_conflict=story_id",
+                    key=story_key,
+                    body=story_rows,
+                    prefer="resolution=merge-duplicates",
+                )
+    except Exception:
+        pass
+
+    try:
+        from ..integration import dag as integration_dag
+
+        integration_cfg = integration_dag._resolve_supabase_rest_config()
+        if integration_cfg is not None:
+            integration_url, integration_key = integration_cfg
+            integration_rows: list[dict[str, Any]] = []
+            ideas_root = repo_root / ".devflow" / "ideas"
+            for idea_dir in sorted([path for path in ideas_root.iterdir() if path.is_dir()] if ideas_root.exists() else []):
+                idea_id = idea_dir.name
+                for run_dir in sorted((idea_dir / "integration" / "runs").glob("*")) if (idea_dir / "integration" / "runs").exists() else []:
+                    if not run_dir.is_dir():
+                        continue
+
+                    def _load_json(name: str) -> dict[str, Any] | None:
+                        path = run_dir / name
+                        if not path.exists():
+                            return None
+                        try:
+                            return json.loads(path.read_text(encoding="utf-8"))
+                        except Exception:
+                            return None
+
+                    side_effects = _load_json("side_effects.json")
+                    implicated_users = _load_json("implicated_users.json")
+                    workflow_inventory = _load_json("workflow_inventory.json")
+                    validation_report = _load_json("validation_gate.json")
+                    red_package = _load_json("red_package.json")
+                    red_review = _load_json("red_review.json")
+                    green_package = _load_json("green_package.json")
+                    green_enrich = _load_json("green_enrich.json")
+                    commit_package = _load_json("commit_package.json")
+                    integration_rows.append(
+                        {
+                            "idea_id": idea_id,
+                            "project_id": authoritative_project_id,
+                            "run_id": run_dir.name,
+                            "pipeline_dir": str(run_dir),
+                            "status": "completed",
+                            "exit_code": None,
+                            "iterations_used": None,
+                            "workflow_count": len((workflow_inventory or {}).get("workflow_ids") or []),
+                            "side_effect_count": len((side_effects or {}).get("side_effects") or []),
+                            "side_effects": side_effects,
+                            "implicated_users": implicated_users,
+                            "workflow_inventory": workflow_inventory,
+                            "validation_report": validation_report,
+                            "red_package": red_package,
+                            "red_review": red_review,
+                            "green_package": green_package,
+                            "green_enrich": green_enrich,
+                            "commit_package": commit_package,
+                            "failure_message": None,
+                            "repair_cycles": (validation_report or {}).get("repair_cycles", 0) if validation_report else 0,
+                            "repair_patches_count": (validation_report or {}).get("repair_patches_count", 0) if validation_report else 0,
+                            "repair_summary": (validation_report or {}).get("repair_summary") if validation_report else None,
+                            "updated_at": now,
+                        }
+                    )
+            if integration_rows:
+                integration_dag._postgrest_request(
+                    method="POST",
+                    url=f"{integration_url}/rest/v1/devflow_idea_integrations?on_conflict=idea_id",
+                    key=integration_key,
+                    body=integration_rows,
+                    prefer="resolution=merge-duplicates",
+                )
+    except Exception:
+        pass
+
+
+class DeriveProjectShellNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        event = task_context.event
+        repo_root = Path(event.repo_root).expanduser().resolve()
+        workspace_path = Path(event.workspace_path).expanduser().resolve()
+        pipeline_dir = _pipeline_root(repo_root, event.project_id)
+        pipeline_dir.mkdir(parents=True, exist_ok=True)
+
+        store, run_id = _store_run()
+        node_exec_id = store.create_node_attempt(
+            run_id=run_id,
+            node_id="derive_project_shell",
+            node_name="DeriveProjectShell",
+            attempt=1,
+            input={
+                "repo_root": str(repo_root),
+                "workspace_path": str(workspace_path),
+                "remote_url": event.remote_url,
+                "project_name": event.project_name,
+            },
+        )
+
+        registry = _read_projects_registry()
+        projects = list(registry.get("projects", []))  # type: ignore[arg-type]
+        found_index, found_entry = _find_existing_project_entry(
+            projects=projects,
+            repo_root=repo_root,
+            workspace_path=workspace_path,
+            remote_url=event.remote_url,
+        )
+        existing_history = found_entry.get("state_history", []) if isinstance(found_entry, dict) else []
+        state_history = [StateHistoryRecord.model_validate(item) for item in existing_history if isinstance(item, dict)]
+        current_state = str(found_entry.get("registration_state") or "draft_unbound") if isinstance(found_entry, dict) else "draft_unbound"
+        owner, repo = _infer_owner_repo(event.remote_url, repo_root, event.project_name)
+
+        entry: dict[str, object] = dict(found_entry or {})
+        entry.update(
+            {
+                "project_id": str(event.project_id),
+                "owner": owner,
+                "repo": repo,
+                "workspace_path": str(workspace_path),
+                "repo_root": str(repo_root),
+                "remote_url": event.remote_url,
+                "registration_command": event.command_name,
+                "registration_artifact": str(pipeline_dir / "project_registration.json"),
+            }
+        )
+
+        artifact = ProjectShellArtifact(
+            dag_id=DAG_ID,
+            project_id=str(entry["project_id"]),
+            owner=owner,
+            repo=repo,
+            repo_root=str(repo_root),
+            workspace_path=str(workspace_path),
+            remote_url=event.remote_url,
+            registration_command=event.command_name,
+            registration_state=current_state,
+            state_history=state_history,
+            created_at=event.occurred_at,
+            updated_at=event.occurred_at,
+        )
+        shell_path = pipeline_dir / "project_shell.json"
+        _write_json(shell_path, artifact.model_dump())
+        store.add_artifact(
+            run_id=run_id,
+            node_exec_id=node_exec_id,
+            kind="project_registration.project_shell",
+            uri=str(shell_path),
+            metadata=artifact.model_dump(),
+        )
+
+        task_context.metadata["repo_root"] = str(repo_root)
+        task_context.metadata["workspace_path"] = str(workspace_path)
+        task_context.metadata["pipeline_dir"] = str(pipeline_dir)
+        task_context.metadata["registry"] = registry
+        task_context.metadata["projects"] = projects
+        task_context.metadata["registry_index"] = found_index
+        task_context.metadata["registry_entry"] = entry
+        task_context.metadata["state_history"] = _jsonable_history(state_history)
+        task_context.metadata["artifacts"] = {
+            "project_shell_ref": str(shell_path),
+        }
+
+        store.mark_node_finished(
+            node_exec_id=node_exec_id,
+            status="succeeded",
+            output={
+                "project_id": str(entry["project_id"]),
+                "project_shell_ref": str(shell_path),
+                "existing_state_count": len(state_history),
+            },
+        )
+        self.save_output(artifact)
+        return task_context
+
+
+class PersistBindingRequestedNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        event = task_context.event
+        store, run_id = _store_run()
+        node_exec_id = store.create_node_attempt(
+            run_id=run_id,
+            node_id="persist_binding_requested",
+            node_name="PersistBindingRequested",
+            attempt=1,
+        )
+
+        pipeline_dir = Path(str(task_context.metadata["pipeline_dir"]))
+        registry = dict(task_context.metadata["registry"])
+        projects = list(task_context.metadata["projects"])
+        found_index = task_context.metadata.get("registry_index")
+        entry = dict(task_context.metadata["registry_entry"])
+        state_history = [StateHistoryRecord.model_validate(item) for item in task_context.metadata.get("state_history", [])]
+
+        found_index, entry = _upsert_registry_state(
+            entry=entry,
+            found_index=found_index if isinstance(found_index, int) else None,
+            registry=registry,
+            projects=projects,
+            state_history=state_history,
+            state="draft_unbound",
+            timestamp=event.occurred_at,
+        )
+        found_index, entry = _upsert_registry_state(
+            entry=entry,
+            found_index=found_index,
+            registry=registry,
+            projects=projects,
+            state_history=state_history,
+            state="binding_requested",
+            timestamp=event.occurred_at,
+        )
+
+        state_history_path = pipeline_dir / "state_history.json"
+        state_history_payload = {
+            "project_id": str(entry["project_id"]),
+            "state_history": _jsonable_history(state_history),
+        }
+        _write_json(state_history_path, state_history_payload)
+
+        binding_artifact = BindingRequestArtifact(
+            dag_id=DAG_ID,
+            project_id=str(entry["project_id"]),
+            registration_state="binding_requested",
+            state_history=state_history,
+            project_shell_ref=str(task_context.metadata["artifacts"]["project_shell_ref"]),
+            state_history_ref=str(state_history_path),
+            registry_entry_ref=str(pipeline_dir / "project_registration.json"),
+            created_at=event.occurred_at,
+            updated_at=event.occurred_at,
+        )
+        binding_path = pipeline_dir / "binding_request.json"
+        _write_json(binding_path, binding_artifact.model_dump())
+        store.add_artifact(
+            run_id=run_id,
+            node_exec_id=node_exec_id,
+            kind="project_registration.binding_request",
+            uri=str(binding_path),
+            metadata=binding_artifact.model_dump(),
+        )
+        store.add_artifact(
+            run_id=run_id,
+            node_exec_id=node_exec_id,
+            kind="project_registration.state_history",
+            uri=str(state_history_path),
+            metadata=state_history_payload,
+        )
+
+        task_context.metadata["registry"] = registry
+        task_context.metadata["projects"] = projects
+        task_context.metadata["registry_index"] = found_index
+        task_context.metadata["registry_entry"] = entry
+        task_context.metadata["state_history"] = _jsonable_history(state_history)
+        task_context.metadata["artifacts"]["state_history_ref"] = str(state_history_path)
+        task_context.metadata["artifacts"]["binding_request_ref"] = str(binding_path)
+
+        store.mark_node_finished(
+            node_exec_id=node_exec_id,
+            status="succeeded",
+            output={
+                "registration_state": "binding_requested",
+                "binding_request_ref": str(binding_path),
+                "state_history_ref": str(state_history_path),
+            },
+        )
+        self.save_output(binding_artifact)
+        return task_context
+
+
+class RegisterEngineNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        event = task_context.event
+        repo_root = Path(str(task_context.metadata["repo_root"]))
+        pipeline_dir = Path(str(task_context.metadata["pipeline_dir"]))
+        store, run_id = _store_run()
+        node_exec_id = store.create_node_attempt(
+            run_id=run_id,
+            node_id="register_engine",
+            node_name="RegisterEngine",
+            attempt=1,
+            input={
+                "repo_root": str(repo_root),
+                "command_name": event.command_name,
+            },
+        )
+
+        registry = dict(task_context.metadata["registry"])
+        projects = list(task_context.metadata["projects"])
+        found_index = task_context.metadata.get("registry_index")
+        entry = dict(task_context.metadata["registry_entry"])
+        state_history = [StateHistoryRecord.model_validate(item) for item in task_context.metadata.get("state_history", [])]
+
+        try:
+            _registration_callback()(repo_root)
+        except Exception as exc:
+            failure_artifact = EngineRegistrationArtifact(
+                dag_id=DAG_ID,
+                project_id=str(entry["project_id"]),
+                registration_state=str(entry.get("registration_state") or "binding_requested"),
+                command_name=event.command_name,
+                repo_root=str(repo_root),
+                workspace_path=str(task_context.metadata["workspace_path"]),
+                remote_url=event.remote_url,
+                state_history=state_history,
+                ok=False,
+                error_message=str(exc),
+                created_at=event.occurred_at,
+                updated_at=event.occurred_at,
+            )
+            failure_path = pipeline_dir / "engine_registration.json"
+            _write_json(failure_path, failure_artifact.model_dump())
+            store.add_artifact(
+                run_id=run_id,
+                node_exec_id=node_exec_id,
+                kind="project_registration.engine_registration",
+                uri=str(failure_path),
+                metadata=failure_artifact.model_dump(),
+            )
+            outcome = {
+                "project_id": str(entry["project_id"]),
+                "registration_state": str(entry.get("registration_state") or "binding_requested"),
+                "pipeline_dir": str(pipeline_dir),
+                "repo_root": str(repo_root),
+                "error": str(exc),
+            }
+            summary_path = _write_summary(
+                pipeline_dir=pipeline_dir,
+                exit_code=2,
+                run_id=run_id,
+                outcome=outcome,
+                message="project registration failed during engine bootstrap",
+            )
+            task_context.metadata["artifacts"]["engine_registration_ref"] = str(failure_path)
+            task_context.metadata["artifacts"]["summary_ref"] = str(summary_path)
+            task_context.metadata["outcome"] = outcome
+            task_context.metadata["message"] = json.dumps(outcome, sort_keys=True) + "\n"
+            task_context.metadata["exit_code"] = 2
+            store.mark_node_finished(
+                node_exec_id=node_exec_id,
+                status="failed",
+                output={
+                    "engine_registration_ref": str(failure_path),
+                    "summary_ref": str(summary_path),
+                },
+                error={"message": str(exc)},
+            )
+            task_context.stop_workflow()
+            return task_context
+
+        found_index, entry = _upsert_registry_state(
+            entry=entry,
+            found_index=found_index if isinstance(found_index, int) else None,
+            registry=registry,
+            projects=projects,
+            state_history=state_history,
+            state="engine_registered",
+            timestamp=event.occurred_at,
+        )
+        artifact = EngineRegistrationArtifact(
+            dag_id=DAG_ID,
+            project_id=str(entry["project_id"]),
+            registration_state="engine_registered",
+            command_name=event.command_name,
+            repo_root=str(repo_root),
+            workspace_path=str(task_context.metadata["workspace_path"]),
+            remote_url=event.remote_url,
+            state_history=state_history,
+            ok=True,
+            error_message=None,
+            created_at=event.occurred_at,
+            updated_at=event.occurred_at,
+        )
+        engine_path = pipeline_dir / "engine_registration.json"
+        _write_json(engine_path, artifact.model_dump())
+        store.add_artifact(
+            run_id=run_id,
+            node_exec_id=node_exec_id,
+            kind="project_registration.engine_registration",
+            uri=str(engine_path),
+            metadata=artifact.model_dump(),
+        )
+
+        task_context.metadata["registry"] = registry
+        task_context.metadata["projects"] = projects
+        task_context.metadata["registry_index"] = found_index
+        task_context.metadata["registry_entry"] = entry
+        task_context.metadata["state_history"] = _jsonable_history(state_history)
+        task_context.metadata["artifacts"]["engine_registration_ref"] = str(engine_path)
+
+        store.mark_node_finished(
+            node_exec_id=node_exec_id,
+            status="succeeded",
+            output={
+                "registration_state": "engine_registered",
+                "engine_registration_ref": str(engine_path),
+            },
+        )
+        self.save_output(artifact)
+        return task_context
+
+
+class FinalizeProjectRegistrationNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        event = task_context.event
+        pipeline_dir = Path(str(task_context.metadata["pipeline_dir"]))
+        repo_root = Path(str(task_context.metadata["repo_root"]))
+        store, run_id = _store_run()
+        node_exec_id = store.create_node_attempt(
+            run_id=run_id,
+            node_id="finalize_registration",
+            node_name="FinalizeProjectRegistration",
+            attempt=1,
+        )
+
+        registry = dict(task_context.metadata["registry"])
+        projects = list(task_context.metadata["projects"])
+        found_index = task_context.metadata.get("registry_index")
+        entry = dict(task_context.metadata["registry_entry"])
+        state_history = [StateHistoryRecord.model_validate(item) for item in task_context.metadata.get("state_history", [])]
+
+        found_index, entry = _upsert_registry_state(
+            entry=entry,
+            found_index=found_index if isinstance(found_index, int) else None,
+            registry=registry,
+            projects=projects,
+            state_history=state_history,
+            state="ready_for_source_scope",
+            timestamp=event.occurred_at,
+        )
+
+        scaffold_paths = ensure_source_doc_scaffold(repo_root)
+
+        registration_artifact = ProjectRegistrationArtifact(
+            dag_id=DAG_ID,
+            run_id=run_id,
+            project_id=str(entry["project_id"]),
+            command_name=event.command_name,
+            repo_root=str(repo_root),
+            workspace_path=str(task_context.metadata["workspace_path"]),
+            remote_url=event.remote_url,
+            registration_state="ready_for_source_scope",
+            state_history=state_history,
+            project_shell_ref=str(task_context.metadata["artifacts"]["project_shell_ref"]),
+            state_history_ref=str(task_context.metadata["artifacts"]["state_history_ref"]),
+            engine_registration_ref=str(task_context.metadata["artifacts"]["engine_registration_ref"]),
+            summary_ref=str(pipeline_dir / "summary.json"),
+            created_at=event.occurred_at,
+            updated_at=event.occurred_at,
+        )
+        registration_path = pipeline_dir / "project_registration.json"
+        _write_json(registration_path, registration_artifact.model_dump())
+        store.add_artifact(
+            run_id=run_id,
+            node_exec_id=node_exec_id,
+            kind="project_registration.registration_record",
+            uri=str(registration_path),
+            metadata=registration_artifact.model_dump(),
+        )
+
+        outcome = {
+            "project_id": str(entry["project_id"]),
+            "registration_state": "ready_for_source_scope",
+            "pipeline_dir": str(pipeline_dir),
+            "workspace": str(repo_root),
+            "next_step": "source docs -> scopes",
+        }
+        summary_path = _write_summary(
+            pipeline_dir=pipeline_dir,
+            exit_code=0,
+            run_id=run_id,
+            outcome=outcome,
+            message="project registration complete",
+        )
+
+        task_context.metadata["registry"] = registry
+        task_context.metadata["projects"] = projects
+        task_context.metadata["registry_index"] = found_index
+        task_context.metadata["registry_entry"] = entry
+        task_context.metadata["state_history"] = _jsonable_history(state_history)
+        task_context.metadata["artifacts"]["registration_artifact_ref"] = str(registration_path)
+        task_context.metadata["artifacts"]["summary_ref"] = str(summary_path)
+        task_context.metadata["outcome"] = outcome
+        task_context.metadata["message"] = json.dumps(outcome, sort_keys=True) + "\n"
+        task_context.metadata["exit_code"] = 0
+
+        # Create / update the devflow_state record for this project.
+        # This is a required part of successful registration when Supabase is
+        # configured, so failures should stop the registration flow.
+        _publish_devflow_state_for_registration(
+            project_id=str(entry["project_id"]),
+            run_id=run_id,
+        )
+
+        try:
+            _project_existing_local_artifacts_to_supabase(
+                repo_root=repo_root,
+                authoritative_project_id=str(entry["project_id"]),
+                run_id=run_id,
+            )
+        except Exception:
+            pass
+
+        store.mark_node_finished(
+            node_exec_id=node_exec_id,
+            status="succeeded",
+            output={
+                "registration_state": "ready_for_source_scope",
+                "registration_artifact_ref": str(registration_path),
+                "summary_ref": str(summary_path),
+                "source_docs_dir": str(scaffold_paths.source_docs_dir),
+                "project_docs_dir": str(scaffold_paths.project_docs_dir),
+            },
+        )
+        self.save_output(registration_artifact)
+        return task_context
+
+
+class ProjectRegistrationWorkflow(Workflow):
+    workflow_schema = WorkflowSchema(
+        description="Project registration DAG (derive shell -> bind state -> engine registration -> ready handoff)",
+        event_schema=ProjectRegistrationDagEvent,
+        start=DeriveProjectShellNode,
+        nodes=[
+            NodeConfig(node=DeriveProjectShellNode, connections=[PersistBindingRequestedNode]),
+            NodeConfig(node=PersistBindingRequestedNode, connections=[RegisterEngineNode]),
+            NodeConfig(node=RegisterEngineNode, connections=[FinalizeProjectRegistrationNode]),
+            NodeConfig(node=FinalizeProjectRegistrationNode, connections=[]),
+        ],
+    )
+
+
+def run_project_registration_dag(
+    *,
+    repo_root: Path,
+    workspace_path: Path,
+    remote_url: str | None,
+    project_name: str | None,
+    command_name: str,
+    register_repo: RegistrationCallback,
+    supabase_project_id: str | None = None,
+) -> ProjectRegistrationDagResult:
+    repo_root = repo_root.expanduser().resolve()
+    workspace_path = workspace_path.expanduser().resolve()
+    repo_root.joinpath(".devflow").mkdir(parents=True, exist_ok=True)
+
+    _owner, _repo, _hash_project_id = _stable_project_identity(
+        repo_root=repo_root,
+        remote_url=remote_url,
+        project_name=project_name,
+    )
+
+    # Prefer the Supabase UUID as the canonical local project_id.
+    # Resolution order (first match wins):
+    #   1. Explicit supabase_project_id kwarg — highest priority override.
+    #   2. Existing UUID already stored in the local registry for this repo —
+    #      avoids re-querying Supabase and, critically, avoids creating a SECOND
+    #      devflow_projects row (and thus a drifted project identity) on re-import.
+    #   3. Supabase lookup-or-create — used only when the project has never been
+    #      registered locally before.
+    #   4. Hash-based fallback — used only when Supabase is not configured at all.
+    _supabase_uuid_resolved: str | None = None
+
+    if supabase_project_id and _is_uuid_like(supabase_project_id):
+        # Explicit override takes highest priority
+        project_id = supabase_project_id
+        _supabase_uuid_resolved = supabase_project_id
+    else:
+        # Check local registry before hitting Supabase — prevents duplicate row creation
+        _local_uuid = _read_existing_local_project_uuid(
+            repo_root=repo_root,
+            workspace_path=workspace_path,
+            remote_url=remote_url,
+        )
+        if _local_uuid:
+            # Already registered — reuse without a Supabase round-trip
+            project_id = _local_uuid
+            _supabase_uuid_resolved = _local_uuid
+        else:
+            # First time this repo is being registered — look up or create in Supabase
+            _supabase_uuid_resolved = _resolve_or_create_supabase_project_uuid(
+                repo_root=repo_root,
+                remote_url=remote_url,
+                project_name=project_name,
+                owner=_owner,
+                repo=_repo,
+            )
+            project_id = _supabase_uuid_resolved if _supabase_uuid_resolved else _hash_project_id
+    pipeline_key = "current"
+    pipeline_dir = _pipeline_root(repo_root, project_id)
+    pipeline_dir.mkdir(parents=True, exist_ok=True)
+    occurred_at = datetime.now(UTC).replace(microsecond=0).isoformat()
+
+    store = ExecutionStore(repo_root / ".devflow" / "execution.sqlite")
+    run_id = store.create_run(
+        dag_id=DAG_ID,
+        dag_version="v2_workflow",
+        root_correlation_id=f"corr_{project_id}",
+        config={
+            "project_id": project_id,
+            "pipeline_key": pipeline_key,
+            "command_name": command_name,
+            "workspace_path": str(workspace_path),
+            "remote_url": remote_url,
+        },
+    )
+    store.mark_run_started(run_id=run_id)
+
+    wf = ProjectRegistrationWorkflow()
+    global _CURRENT_STORE, _CURRENT_RUN_ID, _CURRENT_REGISTER_REPO
+    _CURRENT_STORE = store
+    _CURRENT_RUN_ID = run_id
+    _CURRENT_REGISTER_REPO = register_repo
+    ctx: TaskContext | None = None
+    try:
+        ctx = wf.run(
+            {
+                "repo_root": str(repo_root),
+                "workspace_path": str(workspace_path),
+                "remote_url": remote_url,
+                "project_name": project_name,
+                "command_name": command_name,
+                "project_id": project_id,
+                "pipeline_key": pipeline_key,
+                "occurred_at": occurred_at,
+            }
+        )
+    except Exception as exc:
+        outcome = {
+            "project_id": project_id,
+            "registration_state": "binding_requested",
+            "pipeline_dir": str(pipeline_dir),
+            "repo_root": str(repo_root),
+            "error": str(exc),
+        }
+        _write_summary(
+            pipeline_dir=pipeline_dir,
+            exit_code=2,
+            run_id=run_id,
+            outcome=outcome,
+            message="project registration failed",
+        )
+        store.mark_run_finished(run_id=run_id, status="failed")
+        raise
+    finally:
+        _CURRENT_STORE = None
+        _CURRENT_RUN_ID = None
+        _CURRENT_REGISTER_REPO = None
+
+    assert ctx is not None
+    exit_code = int(ctx.metadata.get("exit_code") or 0)
+    if exit_code == 0:
+        try:
+            _reconcile_execution_store_project_row(
+                repo_root=repo_root,
+                authoritative_project_id=project_id,
+            )
+            if _supabase_uuid_resolved:
+                _supabase_cfg = _resolve_supabase_config_for_registration()
+                if _supabase_cfg:
+                    _repair_supabase_project_row(
+                        url=_supabase_cfg[0],
+                        key=_supabase_cfg[1],
+                        supabase_uuid=_supabase_uuid_resolved,
+                        repo_root=repo_root,
+                        remote_url=remote_url,
+                        project_name=project_name,
+                        owner=_owner,
+                        repo=_repo,
+                        registration_status="ready_for_source_scope",
+                    )
+                    _update_supabase_devflow_project_id(
+                        url=_supabase_cfg[0],
+                        key=_supabase_cfg[1],
+                        supabase_uuid=_supabase_uuid_resolved,
+                    )
+        except Exception as exc:
+            outcome = {
+                "project_id": project_id,
+                "registration_state": "ready_for_source_scope",
+                "pipeline_dir": str(pipeline_dir),
+                "repo_root": str(repo_root),
+                "error": str(exc),
+            }
+            _write_summary(
+                pipeline_dir=pipeline_dir,
+                exit_code=2,
+                run_id=run_id,
+                outcome=outcome,
+                message="project registration failed during finalize sync",
+            )
+            store.mark_run_finished(run_id=run_id, status="failed")
+            raise RuntimeError(
+                f"Project registration finalize sync failed for {repo_root}: {exc}"
+            ) from exc
+
+    store.mark_run_finished(run_id=run_id, status="succeeded" if exit_code == 0 else "failed")
+
+    registry_entry = dict(ctx.metadata.get("registry_entry") or {})
+    state_history = [item for item in ctx.metadata.get("state_history", []) if isinstance(item, dict)]
+    registration_state = str(registry_entry.get("registration_state") or ("ready_for_source_scope" if exit_code == 0 else "binding_requested"))
+    message = str(ctx.metadata.get("message") or "")
+
+    return ProjectRegistrationDagResult(
+        exit_code=exit_code,
+        run_id=run_id,
+        project_id=project_id,
+        registration_state=registration_state,
+        pipeline_dir=pipeline_dir,
+        repo_root=repo_root,
+        workspace_path=workspace_path,
+        registry_entry=registry_entry,
+        state_history=state_history,
+        message=message,
+    )