devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/source_scope/dag.py

@@ -0,0 +1,1626 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from contextlib import contextmanager
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+import re
+from typing import Any, Iterator
+from urllib.parse import quote
+from urllib.request import Request, urlopen
+
+from pydantic import BaseModel
+
+from ..devflow_state import _is_uuid_like
+from ..project_registry import find_project_for_repo_root
+from ..stores.execution_store import ExecutionStore
+from . import agentic as source_scope_agentic
+from ..vendor.datalumina_genai.core.nodes.agent import AgentConfig, AgentNode
+from ..vendor.datalumina_genai.core.nodes.base import Node
+from ..vendor.datalumina_genai.core.nodes.router import BaseRouter, RouterNode
+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 .models import (
+    ApprovalReadyPackageArtifact,
+    AssumptionLedgerItem,
+    CoverageDecisionArtifact,
+    LineageRef,
+    NormalizedSourcePacketArtifact,
+    RegisteredScopeItemArtifact,
+    ScopeCandidateArtifactItem,
+    ScopeCandidatesArtifact,
+    ScopeCoverageReportArtifact,
+    SourceInventoryArtifact,
+    ScopeOutlineArtifact,
+    ScopeOutlineItem,
+    ScopeRegistryRecordArtifact,
+    ScopeRevisionPackageArtifact,
+    SourceInventoryItem,
+    SourceRef,
+    SourceScopeDagSummary,
+)
+
+DAG_ID = "source_to_scope_dag"
+
+_CURRENT_STORE: ExecutionStore | None = None
+_CURRENT_RUN_ID: str | None = None
+
+
+@dataclass(frozen=True)
+class SourceToScopeDagResult:
+    exit_code: int
+    run_id: str
+    pipeline_dir: Path
+    message: str
+    outcome: dict[str, Any]
+
+
+class SourceToScopeDagEvent(BaseModel):
+    repo_root: str
+    project_id: str
+    source_intake_id: str
+    source_refs: list[SourceRef]
+    requested_by: str = "marcus"
+    mode: str = "draft_scope_generation"
+    pipeline_key: str
+
+
+class SourceScopeGenerationFailure(RuntimeError):
+    def __init__(self, *, stage_name: str, reason: str) -> None:
+        self.stage_name = stage_name
+        self.reason = reason
+        super().__init__(f"{stage_name}: {reason}")
+
+
+def _store_run() -> tuple[ExecutionStore, str]:
+    if _CURRENT_STORE is None or _CURRENT_RUN_ID is None:
+        raise RuntimeError("source->scope dag missing runtime store/run_id")
+    return _CURRENT_STORE, _CURRENT_RUN_ID
+
+
+@contextmanager
+def _node_attempt(*, node_id: str, node_name: str, task_context: TaskContext, input_payload: dict[str, Any] | None = None) -> Iterator[str]:
+    store, run_id = _store_run()
+    correlation_id = str(task_context.metadata.get("pipeline_key") or task_context.event.pipeline_key)
+    node_exec_id = store.create_node_attempt(
+        run_id=run_id,
+        node_id=node_id,
+        node_name=node_name,
+        attempt=1,
+        correlation_id=correlation_id,
+        input=input_payload,
+    )
+    try:
+        yield node_exec_id
+    except Exception as exc:
+        store.mark_node_finished(
+            node_exec_id=node_exec_id,
+            status="failed",
+            error={"message": str(exc)},
+            correlation_id=correlation_id,
+        )
+        raise
+
+
+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 _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 _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")
+    key = (
+        os.environ.get("DEVFLOW_SUPABASE_SERVICE_KEY")
+        or os.environ.get("SUPABASE_SERVICE_ROLE_KEY")
+        or os.environ.get("SUPABASE_SERVICE_KEY")
+    )
+    if not url or not key:
+        from ..devflow_state import _keychain_get  # type: ignore
+
+        url = url or _keychain_get("Supabase URL", "Clarity")
+        key = key or _keychain_get("Supabase Service Key", "Clarity")
+    if not url or not key:
+        return None
+    return url.rstrip("/"), key
+
+
+def _postgrest_request(*, method: str, url: str, key: str, body: Any | None = None, prefer: str | None = None) -> Any:
+    payload = None if body is None else json.dumps(body).encode("utf-8")
+    req = Request(url, data=payload, method=method)
+    req.add_header("apikey", key)
+    req.add_header("Authorization", f"Bearer {key}")
+    if body is not None:
+        req.add_header("Content-Type", "application/json")
+    if prefer:
+        req.add_header("Prefer", prefer)
+    with urlopen(req, timeout=30) as resp:
+        raw = resp.read().decode("utf-8")
+        return json.loads(raw) if raw else None
+
+
+def _lookup_supabase_project_uuid_by_field(*, url: str, key: str, field: str, value: str) -> str | None:
+    rows = _postgrest_request(
+        method="GET",
+        url=f"{url}/rest/v1/devflow_projects?select=id&{field}=eq.{quote(value)}&limit=1",
+        key=key,
+    )
+    if not isinstance(rows, list) or not rows:
+        return None
+    resolved = str((rows[0] or {}).get("id") or "").strip()
+    return resolved if _is_uuid_like(resolved) else None
+
+
+def _resolve_source_scope_sync_project_id(*, url: str, key: str, repo_root: Path, project_id: str) -> str:
+    value = str(project_id or "").strip()
+    if _is_uuid_like(value):
+        return value
+
+    resolved_repo_root = str(repo_root.expanduser().resolve())
+    resolved = _lookup_supabase_project_uuid_by_field(
+        url=url,
+        key=key,
+        field="devflow_repo_root",
+        value=resolved_repo_root,
+    )
+    if resolved:
+        return resolved
+
+    project_entry = find_project_for_repo_root(repo_root)
+    remote_url = str((project_entry or {}).get("remote_url") or "").strip()
+    if remote_url:
+        resolved = _lookup_supabase_project_uuid_by_field(
+            url=url,
+            key=key,
+            field="repo_url",
+            value=remote_url,
+        )
+        if resolved:
+            return resolved
+
+    raise RuntimeError(
+        f"Unable to resolve Supabase project UUID for source->scope sync from local project_id={value}"
+    )
+
+
+def _sync_registered_scopes_to_supabase(
+    *,
+    repo_root: Path,
+    project_id: str,
+    scope_set_id: str,
+    run_id: str,
+    pipeline_dir: Path,
+) -> None:
+    config = _resolve_supabase_rest_config()
+    if config is None:
+        return
+    registry_path = pipeline_dir / "scope_registry_record.json"
+    if not registry_path.exists():
+        return
+
+    registry = ScopeRegistryRecordArtifact.model_validate_json(registry_path.read_text(encoding="utf-8"))
+    scope_set_registry_path = Path(str(registry.scope_set_registry_ref or "")).expanduser()
+    scope_set_payload: dict[str, Any] = {}
+    if scope_set_registry_path.exists():
+        scope_set_payload = json.loads(scope_set_registry_path.read_text(encoding="utf-8"))
+
+    rows: list[dict[str, Any]] = []
+    for registered in registry.registered_scope_items:
+        scope_payload_path = Path(registered.registry_ref).expanduser()
+        if not scope_payload_path.exists():
+            continue
+        persisted = json.loads(scope_payload_path.read_text(encoding="utf-8"))
+        scope_item = persisted.get("scope_item") if isinstance(persisted.get("scope_item"), dict) else {}
+        rows.append(
+            {
+                "scope_id": registered.scope_id,
+                "project_id": project_id,
+                "scope_set_id": scope_set_id,
+                "run_id": run_id,
+                "title": str(scope_item.get("title") or registered.scope_id),
+                "summary": scope_item.get("description"),
+                "status": persisted.get("status") or registered.status,
+                "coverage_status": persisted.get("coverage_status") or registry.coverage_status,
+                "review_status": scope_item.get("review_status"),
+                "scope_set_title": scope_set_payload.get("scope_set_title"),
+                "source_traceability_refs": registered.source_traceability_refs,
+                "assumptions": scope_item.get("assumptions") or [],
+                "depends_on": scope_item.get("depends_on") or [],
+                "origin": "source_to_scope",
+                "artifact_path": str(scope_payload_path),
+                "updated_at": datetime.now(UTC).isoformat(),
+            }
+        )
+
+    if not rows:
+        return
+
+    url, key = config
+    resolved_project_id = _resolve_source_scope_sync_project_id(
+        url=url,
+        key=key,
+        repo_root=repo_root,
+        project_id=project_id,
+    )
+    delete_url = (
+        f"{url}/rest/v1/devflow_project_scopes"
+        f"?project_id=eq.{quote(resolved_project_id)}&scope_set_id=eq.{quote(scope_set_id)}"
+    )
+    for row in rows:
+        row["project_id"] = resolved_project_id
+    _postgrest_request(method="DELETE", url=delete_url, key=key)
+    _postgrest_request(
+        method="POST",
+        url=f"{url}/rest/v1/devflow_project_scopes?on_conflict=scope_id",
+        key=key,
+        body=rows,
+        prefer="resolution=merge-duplicates",
+    )
+
+
+def _pipeline_root(repo_root: Path, *, scope_id: str, pipeline_key: str) -> Path:
+    return repo_root / ".devflow" / "scopes" / scope_id / "pipelines" / DAG_ID / pipeline_key
+
+
+def _classify_source_type(raw_type: str) -> str:
+    lowered = raw_type.strip().lower()
+    if lowered in {"transcript", "doc", "repo", "image", "notes", "design"}:
+        return lowered
+    if lowered in {"scope_doc", "brief", "proposal"}:
+        return "doc"
+    return "unknown"
+
+
+def _load_source_text(repo_root: Path, source: SourceRef) -> tuple[str, str]:
+    if source.text:
+        return source.text.strip(), f"inline:{source.type}"
+    if source.path:
+        path = Path(source.path)
+        if not path.is_absolute():
+            path = repo_root / path
+        if path.exists() and path.is_file():
+            return path.read_text(encoding="utf-8").strip(), str(path)
+        return "", str(path)
+    return "", f"unresolved:{source.type}"
+
+
+def _sentence_chunks(text: str) -> list[str]:
+    normalized = re.sub(r"\s+", " ", text.replace("\n", " ")).strip()
+    raw_parts = re.split(r"(?<=[.!?])\s+|\s*[;•]\s*", normalized)
+    chunks: list[str] = []
+    for part in raw_parts:
+        cleaned = part.strip(" .-	")
+        if len(cleaned) >= 12:
+            chunks.append(cleaned)
+    return chunks
+
+
+def _normalize_text(text: str) -> str:
+    return re.sub(r"[^a-z0-9\s]", " ", text.lower())
+
+
+def _keyword_tokens(text: str) -> list[str]:
+    stop = {"the", "and", "with", "from", "that", "this", "into", "for", "will", "must", "should", "have", "has", "need", "needs", "able", "well", "when", "after", "before", "through"}
+    tokens: list[str] = []
+    for token in _normalize_text(text).split():
+        if len(token) >= 4 and token not in stop and token not in tokens:
+            tokens.append(token)
+    return tokens
+
+
+_SCOPE_PATTERNS: list[tuple[str, list[str]]] = [
+    ("Quote Creation", ["create quote", "create quotes", "quotes", "quote creation", "send them to customers"]),
+    ("Quote Approval", ["approve quotes", "quote approval", "approve quote", "digitally", "secure link", "secure portal"]),
+    ("Job Execution", ["create jobs", "jobs", "field staff", "progress updates", "job scheduling", "job completion"]),
+    ("Invoicing", ["invoice", "invoices"]),
+    ("Payments", ["pay online", "payments", "stripe", "payment", "credit card", "e-transfer"]),
+    ("Reporting", ["reporting", "dashboard", "management reporting"]),
+    ("Customer Intake", ["customer intake", "intake", "lead capture", "customer records"]),
+    ("Document Management", ["photo", "upload", "attachment", "document", "supporting documentation"]),
+    ("Field Workflow", ["ipad", "field", "onsite", "mobile"]),
+    ("Admin experience redesign", ["admin dashboard", "organization detail hub", "organizations list", "admin user management", "newsletter", "demo requests", "settings/profile/2fa"]),
+    ("Manager experience redesign", ["manager dashboard", "score trends", "ai analysis", "engagements", "participants", "manager question bank", "manager settings", "board reports"]),
+    ("Participant survey experience redesign", ["landing page", "thank you", "vibe check", "need help", "participant", "scale form", "text form"]),
+    ("Engagement lifecycle", ["create engagement", "recurrence", "group assignment", "question selection", "completed engagement", "calendar", "engagement"]),
+    ("Add Organization wizard", ["add organization", "5-step wizard", "org details", "define groups", "review & send"]),
+    ("Role and access model migration", ["super admin", "super manager", "billing role", "participant token", "permissions overhaul", "require_group_access", "userrole"]),
+    ("Dynamic categories migration", ["dynamic categories", "categories crud", "pillar", "category_id"]),
+    ("Group model and group-scoped permissions", ["hierarchical groups", "tags", "group selector", "manager_group_assignments", "group permissions"]),
+    ("Context Library", ["context library", "about", "pdf_extracted_text", "context entry"]),
+    ("Need Help workflow", ["need help", "988", "crisis lifeline", "safety-critical"]),
+    ("Vibe Check", ["vibe check", "mood", "mood pills"]),
+    ("Billing and invoice history", ["invoice history", "billing contact"]),
+    ("Branding and theming model", ["branding", "theming", "hero image", "overlay", "branded"]),
+    ("Terminology migration", ["terminology", "rename", "organizations", "participants"]),
+    ("Scoring model and display transition", ["0-10", "100-point", "chi score", "rotation weight", "score transformation"]),
+    ("Question type simplification", ["questiontype", "anchor", "narrative", "scale", "text", "event_pulse"]),
+    ("Database migration package", ["migration strategy", "new tables", "modified tables", "enum changes", "deprecations", "phase 1", "phase 2", "phase 3", "phase 4", "database"]),
+    ("API and middleware migration package", ["new route files", "endpoints", "middleware", "dependencies.py", "route file"]),
+    ("Documentation and phased implementation roadmap", ["changelog", "handoff", "roadmap", "implementation plan", "phased rollout", "documentation package"]),
+]
+
+
+def _source_doc_readiness(packet: NormalizedSourcePacketArtifact) -> tuple[str, list[str]]:
+    notes = [str(note).strip() for note in packet.confidence_notes if str(note).strip()]
+    lowered_notes = " ".join(note.lower() for note in notes)
+    reasons: list[str] = []
+
+    low_readiness_markers = [
+        "heuristic_bootstrap",
+        "heuristic bootstrap",
+        "raw intake",
+        "vague intake",
+        "not yet refined",
+        "insufficient",
+        "needs refinement",
+    ]
+    if any(marker in lowered_notes for marker in low_readiness_markers):
+        reasons.append("Source docs still look like heuristic/vague intake rather than refined scope input.")
+    if not packet.facts and packet.open_questions_with_assumptions:
+        reasons.append("Source docs contain open assumptions but no grounded facts yet.")
+    if not packet.lineage and packet.facts:
+        reasons.append("Source docs facts are missing traceable lineage support.")
+
+    return ("needs_refinement", reasons) if reasons else ("ready", [])
+
+
+def _coverage_gate(packet: NormalizedSourcePacketArtifact, outline: ScopeOutlineArtifact) -> ScopeCoverageReportArtifact:
+    fact_chunks = packet.facts[:12]
+    coverage_surface = " ".join(
+        [f"{item.title}. {item.description}" for item in outline.scope_items]
+        + [f"{item.title}. {item.description}" for item in outline.migration_scope_items]
+        + list(outline.cross_cutting_constraints)
+    ).lower()
+    covered: list[str] = []
+    weak: list[str] = []
+    uncovered: list[str] = []
+    for fact in fact_chunks:
+        tokens = [token for token in fact.lower().split() if len(token) > 4][:5]
+        hits = sum(1 for token in tokens if token in coverage_surface)
+        if hits >= max(1, len(tokens) // 2):
+            covered.append(fact)
+        elif hits > 0:
+            weak.append(fact)
+        else:
+            uncovered.append(fact)
+
+    unsupported = [
+        item.title for item in (outline.scope_items + outline.migration_scope_items) if not item.source_support
+    ]
+    ratio = 1.0 if not fact_chunks else len(covered) / len(fact_chunks)
+    source_doc_readiness, source_doc_readiness_reasons = _source_doc_readiness(packet)
+    contradiction_needs_review = (
+        bool(packet.contradictions)
+        and any(item.needs_confirmation for item in packet.open_questions_with_assumptions)
+        and any('source of truth' in item.question.lower() for item in packet.open_questions_with_assumptions)
+    )
+    if contradiction_needs_review:
+        status = "escalate"
+        reasons = ["Source contradictions require human review before scope registration."]
+    elif source_doc_readiness != "ready":
+        status = "revise"
+        reasons = [
+            "Source docs are not yet refined enough to act as the readiness gate for scope generation.",
+            *source_doc_readiness_reasons,
+        ]
+    elif not outline.scope_items:
+        status = "escalate"
+        reasons = ["No product-facing scope items were shaped from the source packet."]
+    elif len(uncovered) >= 2:
+        status = "revise"
+        reasons = ["Multiple source-backed requirements remain uncovered by the draft scope set."]
+    elif uncovered or unsupported or packet.open_questions_with_assumptions or packet.contradictions or weak:
+        status = "pass_with_assumptions"
+        reasons = ["Draft scope is usable, but assumptions, weakly covered items, unsupported items, or survivable contradictions must stay visible in review."]
+    else:
+        status = "pass"
+        reasons = ["Coverage gate found sufficient support and requirement coverage for registration."]
+
+    if packet.open_questions_with_assumptions and not any("open questions" in reason.lower() for reason in reasons):
+        reasons.append("Open questions were carried forward as explicit assumptions for review.")
+
+    return ScopeCoverageReportArtifact(
+        coverage_status=status,
+        covered_requirements=covered,
+        weakly_covered_requirements=weak,
+        uncovered_requirements=uncovered,
+        over_consolidated_scope_items=[],
+        unsupported_inferred_scope_items=unsupported,
+        review_recommendations=["Confirm assumption ledger with Marcus/client before approval."] if status == "pass_with_assumptions" else [],
+        gate_reasons=reasons,
+        gate_metrics={
+            "coverage_ratio": ratio,
+            "unsupported_item_count": len(unsupported),
+            "weak_coverage_count": len(weak),
+            "scope_item_count": len(outline.scope_items),
+            "migration_scope_item_count": len(outline.migration_scope_items),
+            "cross_cutting_constraint_count": len(outline.cross_cutting_constraints),
+            "source_doc_readiness": source_doc_readiness,
+            "source_doc_readiness_reason_count": len(source_doc_readiness_reasons),
+        },
+    )
+
+
+class InventorySourcesNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        event = task_context.event
+        repo_root = Path(event.repo_root)
+        with _node_attempt(
+            node_id="inventory_sources",
+            node_name="InventorySources",
+            task_context=task_context,
+            input_payload={
+                "project_id": event.project_id,
+                "source_intake_id": event.source_intake_id,
+                "source_ref_count": len(event.source_refs),
+            },
+        ) as node_exec_id:
+            sources: list[SourceInventoryItem] = []
+            source_texts: dict[str, str] = {}
+            missing: list[str] = []
+            warnings: list[str] = []
+            for index, source in enumerate(event.source_refs, start=1):
+                source_type = _classify_source_type(source.type)
+                text, resolved_location = _load_source_text(repo_root, source)
+                source_id = f"src_{index:02d}"
+                ingest_status = "resolved" if text else "missing"
+                if not text:
+                    missing.append(source.title or source.path or source.type)
+                    warnings.append(f"Source '{source.title or source.type}' could not be fully resolved.")
+                source_texts[source_id] = text
+                sources.append(
+                    SourceInventoryItem(
+                        source_id=source_id,
+                        source_type=source_type,
+                        location=resolved_location,
+                        title=source.title or Path(resolved_location).name or source.type,
+                        content_ref=resolved_location,
+                        ingest_status=ingest_status,
+                        priority=10 if source_type == "transcript" else 50,
+                        notes=["Transcript/design/repo context should be combined rather than overridden by polished docs."] if source_type in {"transcript", "repo", "design"} else [],
+                    )
+                )
+
+            scope_seed = _stable_id(
+                "scope_seed_",
+                {
+                    "project_id": event.project_id,
+                    "source_intake_id": event.source_intake_id,
+                    "source_refs": [source.model_dump() for source in event.source_refs],
+                },
+            )
+            pipeline_root = _pipeline_root(repo_root, scope_id=scope_seed, pipeline_key=event.pipeline_key)
+            artifact = SourceInventoryArtifact(
+                project_id=event.project_id,
+                source_intake_id=event.source_intake_id,
+                sources=sources,
+                inventory_summary=f"Inventoried {len(sources)} source(s) for scope extraction.",
+                missing_expected_sources=missing,
+                warnings=warnings,
+            )
+            inventory_path = pipeline_root / "source_inventory.json"
+            _write_json(inventory_path, artifact.model_dump())
+            task_context.metadata["scope_seed_id"] = scope_seed
+            task_context.metadata["pipeline_root"] = str(pipeline_root)
+            task_context.metadata["source_inventory"] = artifact
+            task_context.metadata["source_texts"] = source_texts
+            task_context.metadata["artifact_paths"] = {"source_inventory": str(inventory_path)}
+            store, run_id = _store_run()
+            store.add_artifact(run_id=run_id, node_exec_id=node_exec_id, kind="source_scope.source_inventory", uri=str(inventory_path), metadata=artifact.model_dump())
+            store.mark_node_finished(node_exec_id=node_exec_id, status="succeeded", output={"scope_seed_id": scope_seed, "pipeline_root": str(pipeline_root), "source_inventory_ref": str(inventory_path), "resolved_source_count": len([item for item in sources if item.ingest_status == "resolved"]), "missing_source_count": len(missing)})
+            self.save_output(artifact)
+            return task_context
+
+
+def _agent_timeout_seconds() -> int | None:
+    raw = os.environ.get("DEVFLOW_SOURCE_SCOPE_AGENT_TIMEOUT_SECONDS")
+    if raw:
+        try:
+            return max(1, int(raw))
+        except ValueError:
+            pass
+    return 1800
+
+
+def _annotate_packet_confidence(packet: NormalizedSourcePacketArtifact, note: str) -> NormalizedSourcePacketArtifact:
+    data = packet.model_dump()
+    notes = list(data.get("confidence_notes") or [])
+    if note not in notes:
+        notes.append(note)
+    data["confidence_notes"] = notes
+    return NormalizedSourcePacketArtifact.model_validate(data)
+
+
+def _persist_agent_artifact(*, stage_path: Path, artifact: BaseModel, artifact_paths: dict[str, str], key: str, task_context: TaskContext) -> None:
+    _write_json(stage_path, artifact.model_dump())
+    artifact_paths[key] = str(stage_path)
+    task_context.metadata["artifact_paths"] = artifact_paths
+    task_context.metadata[key] = artifact
+
+
+MAX_SCOPE_SHAPING_ATTEMPTS = 3
+
+
+def _scope_validation_feedback(report: ScopeCoverageReportArtifact) -> dict[str, Any]:
+    return {
+        "coverage_status": report.coverage_status,
+        "gate_reasons": list(report.gate_reasons),
+        "uncovered_requirements": list(report.uncovered_requirements),
+        "weakly_covered_requirements": list(report.weakly_covered_requirements),
+        "unsupported_inferred_scope_items": list(report.unsupported_inferred_scope_items),
+        "review_recommendations": list(report.review_recommendations),
+        "gate_metrics": dict(report.gate_metrics),
+    }
+
+
+def _persist_scope_shaping_attempts(*, pipeline_root: Path, attempts: list[dict[str, Any]]) -> Path:
+    path = pipeline_root / "scope_shaping_attempts.json"
+    payload = {
+        "max_attempts": MAX_SCOPE_SHAPING_ATTEMPTS,
+        "attempt_count": len(attempts),
+        "attempts": attempts,
+    }
+    _write_json(path, payload)
+    return path
+
+
+def _generation_failure_result(
+    *,
+    pipeline_dir: Path,
+    run_id: str,
+    project_id: str,
+    source_intake_id: str,
+    stage_name: str,
+    reason: str,
+) -> SourceToScopeDagResult:
+    failure_payload = {
+        "project_id": project_id,
+        "source_intake_id": source_intake_id,
+        "resolution_status": "generation_failed",
+        "failure_stage": stage_name,
+        "failure_reason": reason,
+        "registered_scope_count": 0,
+    }
+    _write_json(pipeline_dir / "generation_failure.json", failure_payload)
+    summary = SourceScopeDagSummary(
+        exit_code=2,
+        run_id=run_id,
+        pipeline_dir=str(pipeline_dir),
+        message="source->scope generation failed",
+        outcome=failure_payload,
+    )
+    _write_json(pipeline_dir / "summary.json", summary.model_dump())
+    return SourceToScopeDagResult(
+        exit_code=2,
+        run_id=run_id,
+        pipeline_dir=pipeline_dir,
+        message=json.dumps({**failure_payload, "run_id": run_id, "pipeline_dir": str(pipeline_dir)}, sort_keys=True) + "\n",
+        outcome=failure_payload,
+    )
+
+
+def _run_source_scope_agent(
+    *,
+    repo_root: Path,
+    pipeline_root: Path,
+    stage_name: str,
+    output_model: type[BaseModel],
+    context_payload: dict[str, Any],
+    guidance: list[str],
+) -> BaseModel:
+    if os.environ.get("PYTEST_CURRENT_TEST") and os.environ.get("DEVFLOW_ENABLE_SOURCE_SCOPE_AGENT") != "1":
+        raise SourceScopeGenerationFailure(
+            stage_name=stage_name,
+            reason="source->scope agent is disabled under pytest; heuristic fallback is not permitted",
+        )
+    try:
+        artifact, envelope = source_scope_agentic.run_source_scope_agent_step(
+            repo_root=repo_root,
+            stage_name=stage_name,
+            output_model=output_model,
+            context_payload=context_payload,
+            guidance=guidance,
+            timeout_seconds=_agent_timeout_seconds(),
+        )
+        source_scope_agentic.persist_agent_run(pipeline_root=pipeline_root, node_id=stage_name, envelope=envelope)
+        return artifact
+    except SourceScopeGenerationFailure:
+        raise
+    except Exception as exc:
+        raise SourceScopeGenerationFailure(
+            stage_name=stage_name,
+            reason=f"source->scope agent step failed: {exc}",
+        ) from exc
+
+
+class NormalizeSourcePacketNode(AgentNode):
+    def get_agent_config(self) -> AgentConfig:
+        return AgentConfig(
+            instructions="Normalize messy project input into a structured source packet with facts, assumptions, contradictions, and lineage.",
+            output_type=NormalizedSourcePacketArtifact,
+        )
+
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        event = task_context.event
+        repo_root = Path(event.repo_root)
+        pipeline_root = Path(task_context.metadata["pipeline_root"])
+        inventory = task_context.metadata["source_inventory"]
+        source_texts = dict(task_context.metadata.get("source_texts") or {})
+        artifact_paths = dict(task_context.metadata.get("artifact_paths") or {})
+        with _node_attempt(node_id="normalize_source_packet", node_name="NormalizeSourcePacket", task_context=task_context, input_payload={"project_id": event.project_id, "source_intake_id": event.source_intake_id}) as node_exec_id:
+            artifact = _run_source_scope_agent(
+                repo_root=repo_root,
+                pipeline_root=pipeline_root,
+                stage_name="normalize_source_packet",
+                output_model=NormalizedSourcePacketArtifact,
+                context_payload={
+                    "project_id": event.project_id,
+                    "source_intake_id": event.source_intake_id,
+                    "source_inventory": inventory.model_dump(),
+                    "source_texts": source_texts,
+                },
+                guidance=[
+                    "Return a normalized packet with evidence-backed facts, explicit assumptions, open questions, contradictions, and lineage.",
+                    "Do not collapse multiple requirements into one vague summary if the source distinguishes them.",
+                    "Preserve traceability by returning lineage refs that map back to source chunks.",
+                ],
+            )
+            note = "CLI LLM agent produced normalized source packet."
+            artifact = _annotate_packet_confidence(NormalizedSourcePacketArtifact.model_validate(artifact.model_dump()), note)
+            stage_path = pipeline_root / "normalized_source_packet.json"
+            _persist_agent_artifact(stage_path=stage_path, artifact=artifact, artifact_paths=artifact_paths, key="normalized_source_packet", task_context=task_context)
+            store, run_id = _store_run()
+            store.add_artifact(run_id=run_id, node_exec_id=node_exec_id, kind="source_scope.normalized_source_packet", uri=str(stage_path), metadata=artifact.model_dump())
+            store.mark_node_finished(node_exec_id=node_exec_id, status="succeeded", output={"normalized_source_packet_ref": str(stage_path), "mode": "agent", "lineage_count": len(artifact.lineage), "fact_count": len(artifact.facts), "open_question_count": len(artifact.open_questions_with_assumptions), "contradiction_count": len(artifact.contradictions)})
+            self.save_output(artifact)
+            return task_context
+
+
+class ExtractScopeCandidatesNode(AgentNode):
+    def get_agent_config(self) -> AgentConfig:
+        return AgentConfig(
+            instructions="Extract candidate client-facing scope units from the normalized source packet while preserving source traceability.",
+            output_type=ScopeCandidatesArtifact,
+        )
+
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        event = task_context.event
+        repo_root = Path(event.repo_root)
+        pipeline_root = Path(task_context.metadata["pipeline_root"])
+        packet = task_context.metadata["normalized_source_packet"]
+        artifact_paths = dict(task_context.metadata.get("artifact_paths") or {})
+        with _node_attempt(node_id="extract_scope_candidates", node_name="ExtractScopeCandidates", task_context=task_context, input_payload={"project_id": event.project_id}) as node_exec_id:
+            artifact = _run_source_scope_agent(
+                repo_root=repo_root,
+                pipeline_root=pipeline_root,
+                stage_name="extract_scope_candidates",
+                output_model=ScopeCandidatesArtifact,
+                context_payload={
+                    "project_id": event.project_id,
+                    "normalized_source_packet": packet.model_dump(),
+                },
+                guidance=[
+                    "Extract client-facing scope candidates, not implementation stories or task lists.",
+                    "Each candidate should carry concrete source support when available.",
+                    "Surface overlaps and candidate gaps explicitly rather than hiding ambiguity.",
+                ],
+            )
+            artifact = ScopeCandidatesArtifact.model_validate(artifact.model_dump())
+            artifact.extraction_notes.append("CLI LLM agent extracted candidate scope units.")
+            stage_path = pipeline_root / "scope_candidates.json"
+            _persist_agent_artifact(stage_path=stage_path, artifact=artifact, artifact_paths=artifact_paths, key="scope_candidates", task_context=task_context)
+            store, run_id = _store_run()
+            store.add_artifact(run_id=run_id, node_exec_id=node_exec_id, kind="source_scope.scope_candidates", uri=str(stage_path), metadata=artifact.model_dump())
+            store.mark_node_finished(node_exec_id=node_exec_id, status="succeeded", output={"scope_candidates_ref": str(stage_path), "mode": "agent", "candidate_count": len(artifact.scope_candidates), "candidate_gap_count": len(artifact.candidate_gaps)})
+            self.save_output(artifact)
+            return task_context
+
+
+class ShapeScopeDocumentNode(AgentNode):
+    def get_agent_config(self) -> AgentConfig:
+        return AgentConfig(
+            instructions="Shape candidate scope units into a reviewable scope outline without collapsing affirmed intent.",
+            output_type=ScopeOutlineArtifact,
+        )
+
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        event = task_context.event
+        repo_root = Path(event.repo_root)
+        pipeline_root = Path(task_context.metadata["pipeline_root"])
+        packet = task_context.metadata["normalized_source_packet"]
+        candidates = task_context.metadata["scope_candidates"]
+        artifact_paths = dict(task_context.metadata.get("artifact_paths") or {})
+        scope_set_id = _stable_id("scope_set_", {"project_id": event.project_id, "source_intake_id": event.source_intake_id})
+        with _node_attempt(node_id="shape_scope_document", node_name="ShapeScopeDocument", task_context=task_context, input_payload={"project_id": event.project_id, "scope_set_id": scope_set_id, "max_attempts": MAX_SCOPE_SHAPING_ATTEMPTS}) as node_exec_id:
+            shaping_feedback: dict[str, Any] | None = None
+            prior_outline: ScopeOutlineArtifact | None = None
+            attempts: list[dict[str, Any]] = []
+            latest_outline_path = pipeline_root / "scope_outline.json"
+            latest_report_path = pipeline_root / "scope_coverage_report.json"
+            for attempt_number in range(1, MAX_SCOPE_SHAPING_ATTEMPTS + 1):
+                artifact = _run_source_scope_agent(
+                    repo_root=repo_root,
+                    pipeline_root=pipeline_root,
+                    stage_name="shape_scope_document",
+                    output_model=ScopeOutlineArtifact,
+                    context_payload={
+                        "project_id": event.project_id,
+                        "scope_set_id": scope_set_id,
+                        "normalized_source_packet": packet.model_dump(),
+                        "scope_candidates": candidates.model_dump(),
+                        "shape_attempt": attempt_number,
+                        "max_shape_attempts": MAX_SCOPE_SHAPING_ATTEMPTS,
+                        "previous_scope_outline": prior_outline.model_dump() if prior_outline is not None else None,
+                        "validation_feedback": shaping_feedback,
+                    },
+                    guidance=[
+                        "Shape candidates into a reviewable scope outline that preserves source-backed boundaries.",
+                        "Keep assumptions, out-of-scope notes, and review notes visible.",
+                        "Do not invent dependency chains unless the source clearly implies them.",
+                        "If validation feedback is provided, revise the outline against that feedback while staying grounded strictly in source docs and explicit assumptions.",
+                        "Do not mask failed validation with a packaging artifact; either produce a gate-passing outline within the allowed attempts or fail clearly.",
+                    ],
+                )
+                artifact = ScopeOutlineArtifact.model_validate(artifact.model_dump())
+                artifact.review_notes.append(f"CLI LLM agent shaped the reviewable scope outline on attempt {attempt_number}.")
+                if shaping_feedback:
+                    artifact.review_notes.append("Validation feedback from the prior attempt was applied during reshaping.")
+
+                attempt_outline_path = pipeline_root / f"scope_outline_attempt_{attempt_number}.json"
+                _write_json(attempt_outline_path, artifact.model_dump())
+                _write_json(latest_outline_path, artifact.model_dump())
+                report = _coverage_gate(packet, artifact)
+                report.gate_metrics["shape_attempt"] = attempt_number
+                report.gate_metrics["max_shape_attempts"] = MAX_SCOPE_SHAPING_ATTEMPTS
+                attempt_report_path = pipeline_root / f"scope_coverage_report_attempt_{attempt_number}.json"
+                _write_json(attempt_report_path, report.model_dump())
+                _write_json(latest_report_path, report.model_dump())
+
+                attempts.append(
+                    {
+                        "attempt": attempt_number,
+                        "scope_outline_ref": str(attempt_outline_path),
+                        "scope_coverage_report_ref": str(attempt_report_path),
+                        "coverage_status": report.coverage_status,
+                        "gate_reasons": list(report.gate_reasons),
+                    }
+                )
+                attempts_path = _persist_scope_shaping_attempts(pipeline_root=pipeline_root, attempts=attempts)
+                artifact_paths["scope_shaping_attempts"] = str(attempts_path)
+                artifact_paths["scope_outline"] = str(latest_outline_path)
+                artifact_paths["scope_coverage_report"] = str(latest_report_path)
+                task_context.metadata["artifact_paths"] = artifact_paths
+                task_context.metadata["scope_outline"] = artifact
+                task_context.metadata["scope_coverage_report"] = report
+                task_context.metadata["scope_shaping_attempt_count"] = attempt_number
+                task_context.metadata["scope_shaping_attempts"] = attempts
+                prior_outline = artifact
+
+                if report.coverage_status in {"pass", "pass_with_assumptions"}:
+                    store, run_id = _store_run()
+                    store.add_artifact(run_id=run_id, node_exec_id=node_exec_id, kind="source_scope.scope_outline", uri=str(latest_outline_path), metadata=artifact.model_dump())
+                    store.add_artifact(run_id=run_id, node_exec_id=node_exec_id, kind="source_scope.scope_coverage_report", uri=str(latest_report_path), metadata=report.model_dump())
+                    store.mark_node_finished(node_exec_id=node_exec_id, status="succeeded", output={"scope_outline_ref": str(latest_outline_path), "scope_coverage_report_ref": str(latest_report_path), "mode": "agent_loop", "scope_item_count": len(artifact.scope_items), "scope_set_id": artifact.scope_set_id, "attempt_count": attempt_number, "coverage_status": report.coverage_status})
+                    self.save_output(artifact)
+                    return task_context
+
+                shaping_feedback = _scope_validation_feedback(report)
+
+            raise SourceScopeGenerationFailure(
+                stage_name="shape_scope_document",
+                reason=(
+                    f"scope shaping validation failed after {MAX_SCOPE_SHAPING_ATTEMPTS} attempts; "
+                    f"last coverage_status={report.coverage_status}; "
+                    f"gate_reasons={' | '.join(report.gate_reasons)}"
+                ),
+            )
+
+
+class CoverageGateNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        packet = task_context.metadata["normalized_source_packet"]
+        outline = task_context.metadata["scope_outline"]
+        artifact = _coverage_gate(packet, outline)
+        stage_path = Path(task_context.metadata["pipeline_root"]) / "scope_coverage_report.json"
+        _write_json(stage_path, artifact.model_dump())
+        artifact_paths = dict(task_context.metadata.get("artifact_paths") or {})
+        artifact_paths["scope_coverage_report"] = str(stage_path)
+        task_context.metadata["artifact_paths"] = artifact_paths
+        task_context.metadata["scope_coverage_report"] = artifact
+        self.save_output(artifact)
+        return task_context
+
+
+class CoverageDecisionNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        report = task_context.metadata["scope_coverage_report"]
+        next_node = "RegisterScopeSetNode" if report.coverage_status in {"pass", "pass_with_assumptions"} else "EscalationPackageNode"
+        artifact = CoverageDecisionArtifact(
+            decision=report.coverage_status,
+            reason="; ".join(report.gate_reasons) or report.coverage_status,
+            next_node=next_node,
+        )
+        stage_path = Path(task_context.metadata["pipeline_root"]) / "coverage_decision.json"
+        _write_json(stage_path, artifact.model_dump())
+        task_context.metadata["coverage_decision"] = artifact
+        self.save_output(artifact)
+        return task_context
+
+
+class _RoutePass(RouterNode):
+    def determine_next_node(self, task_context: TaskContext) -> Node | None:
+        decision = task_context.metadata["coverage_decision"]
+        if decision.decision == "pass":
+            return RegisterScopeSetNode(task_context=task_context)
+        return None
+
+
+class _RoutePassWithAssumptions(RouterNode):
+    def determine_next_node(self, task_context: TaskContext) -> Node | None:
+        decision = task_context.metadata["coverage_decision"]
+        if decision.decision == "pass_with_assumptions":
+            return RegisterScopeSetNode(task_context=task_context)
+        return None
+
+
+class _RouteRevise(RouterNode):
+    def determine_next_node(self, task_context: TaskContext) -> Node | None:
+        decision = task_context.metadata["coverage_decision"]
+        if decision.decision == "revise":
+            return EscalationPackageNode(task_context=task_context)
+        return None
+
+
+class _RouteEscalate(RouterNode):
+    def determine_next_node(self, task_context: TaskContext) -> Node | None:
+        decision = task_context.metadata["coverage_decision"]
+        if decision.decision == "escalate":
+            return EscalationPackageNode(task_context=task_context)
+        return None
+
+
+class CoverageDecisionRouter(BaseRouter):
+    def __init__(self) -> None:
+        self.routes = [_RoutePass(), _RoutePassWithAssumptions(), _RouteRevise(), _RouteEscalate()]
+        self.fallback = EscalationPackageNode()
+
+
+class RegisterScopeSetNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        repo_root = Path(task_context.event.repo_root)
+        outline = task_context.metadata["scope_outline"]
+        report = task_context.metadata["scope_coverage_report"]
+        run_id = _store_run()[1]
+        registry_root = repo_root / ".devflow" / "projects" / outline.project_id / "scopes"
+        registry_root.mkdir(parents=True, exist_ok=True)
+        registered: list[RegisteredScopeItemArtifact] = []
+        for item in outline.scope_items:
+            registry_path = registry_root / f"{item.scope_id}.json"
+            persisted = {
+                "project_id": outline.project_id,
+                "scope_set_id": outline.scope_set_id,
+                "scope_id": item.scope_id,
+                "status": "ready_for_review",
+                "coverage_status": report.coverage_status,
+                "scope_item": item.model_dump(),
+            }
+            _write_json(registry_path, persisted)
+            registered.append(
+                RegisteredScopeItemArtifact(
+                    scope_id=item.scope_id,
+                    registry_ref=str(registry_path),
+                    status="ready_for_review",
+                    source_traceability_refs=item.source_support,
+                )
+            )
+        scope_set_registry_root = repo_root / ".devflow" / "projects" / outline.project_id / "scope_sets"
+        scope_set_registry_root.mkdir(parents=True, exist_ok=True)
+        scope_set_registry_path = scope_set_registry_root / f"{outline.scope_set_id}.json"
+        _write_json(
+            scope_set_registry_path,
+            {
+                "project_id": outline.project_id,
+                "scope_set_id": outline.scope_set_id,
+                "scope_set_title": outline.scope_set_title,
+                "status": "ready_for_review",
+                "coverage_status": report.coverage_status,
+                "scope_item_ids": [item.scope_id for item in outline.scope_items],
+                "cross_cutting_constraints": outline.cross_cutting_constraints,
+                "review_notes": outline.review_notes,
+                "approval_required_before_scope_to_idea": True,
+            },
+        )
+        artifact = ScopeRegistryRecordArtifact(
+            project_id=outline.project_id,
+            scope_set_id=outline.scope_set_id,
+            registered_scope_items=registered,
+            coverage_status=report.coverage_status,
+            run_id=run_id,
+            registration_timestamp=datetime.now(UTC).isoformat(),
+            scope_set_registry_ref=str(scope_set_registry_path),
+        )
+        stage_path = Path(task_context.metadata["pipeline_root"]) / "scope_registry_record.json"
+        _write_json(stage_path, artifact.model_dump())
+        task_context.metadata["scope_registry_record"] = artifact
+        self.save_output(artifact)
+        return task_context
+
+
+class ApprovalReadyPackageNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        outline = task_context.metadata["scope_outline"]
+        report = task_context.metadata["scope_coverage_report"]
+        registry = task_context.metadata["scope_registry_record"]
+        artifact = ApprovalReadyPackageArtifact(
+            project_id=outline.project_id,
+            scope_set_id=outline.scope_set_id,
+            scope_summary=outline.project_summary,
+            scope_items_for_review=[
+                {
+                    "scope_id": item.scope_id,
+                    "title": item.title,
+                    "description": item.description,
+                    "assumptions": item.assumptions,
+                    "source_support": item.source_support,
+                }
+                for item in outline.scope_items
+            ],
+            key_assumptions_to_confirm=[entry.assumed_answer for entry in outline.assumptions_ledger],
+            known_open_questions=[entry.question for entry in outline.assumptions_ledger],
+            coverage_status=report.coverage_status,
+            recommended_next_action="Review and approve this registered draft scope set. Do not treat it as idea-sufficiency output until humans approve the scope boundary.",
+            downstream_ready_if_approved="Once approved, these registered scope artifacts become the canonical client-affirmed scope boundary for downstream scope->idea enrichment, not direct story decomposition.",
+            scope_registry_record_ref=registry.scope_set_registry_ref,
+        )
+        stage_path = Path(task_context.metadata["pipeline_root"]) / "approval_package.json"
+        _write_json(stage_path, artifact.model_dump())
+        summary = SourceScopeDagSummary(
+            exit_code=0,
+            run_id=_store_run()[1],
+            pipeline_dir=str(task_context.metadata["pipeline_root"]),
+            message="source->scope run complete",
+            outcome={
+                "project_id": outline.project_id,
+                "scope_set_id": outline.scope_set_id,
+                "coverage_status": report.coverage_status,
+                "registered_scope_count": len(registry.registered_scope_items),
+                "assumption_count": len(outline.assumptions_ledger),
+                "scope_shaping_attempt_count": int(task_context.metadata.get("scope_shaping_attempt_count") or 1),
+                "resolution_status": "ready_for_review",
+            },
+        )
+        _write_json(Path(task_context.metadata["pipeline_root"]) / "summary.json", summary.model_dump())
+        task_context.metadata["outcome"] = dict(summary.outcome)
+        task_context.metadata["message"] = json.dumps({**summary.outcome, "run_id": summary.run_id, "pipeline_dir": summary.pipeline_dir}, sort_keys=True) + "\n"
+        task_context.metadata["exit_code"] = 0
+        self.save_output(artifact)
+        return task_context
+
+
+class EscalationPackageNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        event = task_context.event
+        report = task_context.metadata["scope_coverage_report"]
+        outline = task_context.metadata["scope_outline"]
+        packet = task_context.metadata["normalized_source_packet"]
+        artifact = ScopeRevisionPackageArtifact(
+            project_id=event.project_id,
+            scope_set_id=outline.scope_set_id,
+            proposed_status="needs_revision" if report.coverage_status == "revise" else "human_review_required",
+            major_gaps=report.uncovered_requirements,
+            unsupported_items=report.unsupported_inferred_scope_items,
+            recommended_revision_actions=report.review_recommendations or ["Tighten scope coverage and ensure each major source-backed requirement is represented."],
+            manual_review_questions=[item.question for item in packet.open_questions_with_assumptions],
+            coverage_status=report.coverage_status,
+        )
+        stage_path = Path(task_context.metadata["pipeline_root"]) / "scope_revision_package.json"
+        _write_json(stage_path, artifact.model_dump())
+        resolution_status = "human_review_required" if report.coverage_status == "escalate" else "needs_revision"
+        summary = SourceScopeDagSummary(
+            exit_code=2,
+            run_id=_store_run()[1],
+            pipeline_dir=str(task_context.metadata["pipeline_root"]),
+            message="source->scope run complete with revision/escalation package",
+            outcome={
+                "project_id": event.project_id,
+                "scope_set_id": outline.scope_set_id,
+                "coverage_status": report.coverage_status,
+                "registered_scope_count": 0,
+                "assumption_count": len(packet.open_questions_with_assumptions),
+                "resolution_status": resolution_status,
+            },
+        )
+        _write_json(Path(task_context.metadata["pipeline_root"]) / "summary.json", summary.model_dump())
+        task_context.metadata["outcome"] = dict(summary.outcome)
+        task_context.metadata["message"] = json.dumps({**summary.outcome, "run_id": summary.run_id, "pipeline_dir": summary.pipeline_dir}, sort_keys=True) + "\n"
+        task_context.metadata["exit_code"] = int(summary.exit_code)
+        self.save_output(artifact)
+        return task_context
+
+
+SourceDocsToScopesDagResult = SourceToScopeDagResult
+
+
+class SourceToScopeWorkflow(Workflow):
+    workflow_schema = WorkflowSchema(
+        description="Source docs -> scopes DAG (inventory -> normalize -> extract -> shape+validate loop -> register -> approval package)",
+        event_schema=SourceToScopeDagEvent,
+        start=InventorySourcesNode,
+        nodes=[
+            NodeConfig(node=InventorySourcesNode, connections=[NormalizeSourcePacketNode]),
+            NodeConfig(node=NormalizeSourcePacketNode, connections=[ExtractScopeCandidatesNode]),
+            NodeConfig(node=ExtractScopeCandidatesNode, connections=[ShapeScopeDocumentNode]),
+            NodeConfig(node=ShapeScopeDocumentNode, connections=[RegisterScopeSetNode]),
+            NodeConfig(node=RegisterScopeSetNode, connections=[ApprovalReadyPackageNode]),
+            NodeConfig(node=ApprovalReadyPackageNode, connections=[]),
+        ],
+    )
+
+
+def build_pipeline_key(*, repo_root: Path, project_id: str, source_intake_id: str, source_refs: list[dict[str, Any]]) -> str:
+    return _stable_id(
+        "run_",
+        {
+            "repo_root": str(repo_root),
+            "project_id": project_id,
+            "source_intake_id": source_intake_id,
+            "source_refs": source_refs,
+        },
+    )
+
+
+def run_source_docs_to_scopes_dag(
+    *,
+    repo_root: Path,
+    store: ExecutionStore,
+    project_id: str,
+    source_intake_id: str | None = None,
+    source_refs: list[dict[str, Any]] | None = None,
+    source_packet_id: str | None = None,
+    source_texts: list[dict[str, Any]] | None = None,
+    requested_by: str = "marcus",
+    mode: str = "draft_scope_generation",
+) -> SourceToScopeDagResult:
+    return run_source_to_scope_dag(
+        repo_root=repo_root,
+        store=store,
+        project_id=project_id,
+        source_intake_id=source_intake_id,
+        source_refs=source_refs,
+        source_packet_id=source_packet_id,
+        source_texts=source_texts,
+        requested_by=requested_by,
+        mode=mode,
+    )
+
+
+def run_source_to_scope_resume(
+    *,
+    repo_root: Path,
+    store: ExecutionStore,
+    project_id: str,
+    source_intake_id: str,
+    source_refs: list[dict[str, Any]],
+    resume_from: str,
+) -> SourceToScopeDagResult:
+    normalized_refs = [SourceRef.model_validate(item) for item in source_refs]
+    pipeline_key = build_pipeline_key(
+        repo_root=repo_root,
+        project_id=project_id,
+        source_intake_id=source_intake_id,
+        source_refs=[item.model_dump() for item in normalized_refs],
+    )
+    scope_seed = _stable_id("scope_seed_", {"project_id": project_id, "source_intake_id": source_intake_id, "source_refs": [item.model_dump() for item in normalized_refs]})
+    pipeline_dir = _pipeline_root(repo_root, scope_id=scope_seed, pipeline_key=pipeline_key)
+    if not pipeline_dir.exists():
+        raise ValueError(f"pipeline_dir not found for resume: {pipeline_dir}")
+
+    run_id = store.create_run(
+        dag_id=f"{DAG_ID}_resume",
+        dag_version="v1_resume",
+        root_correlation_id=f"corr_{pipeline_key}_resume_{resume_from}",
+        config={
+            "project_id": project_id,
+            "source_intake_id": source_intake_id,
+            "pipeline_key": pipeline_key,
+            "resume_from": resume_from,
+        },
+    )
+    store.mark_run_started(run_id=run_id)
+    global _CURRENT_STORE, _CURRENT_RUN_ID
+    _CURRENT_STORE = store
+    _CURRENT_RUN_ID = run_id
+    try:
+        event = SourceToScopeDagEvent(
+            repo_root=str(repo_root),
+            project_id=project_id,
+            source_intake_id=source_intake_id,
+            source_refs=normalized_refs,
+            requested_by="resume",
+            mode="draft_scope_generation",
+            pipeline_key=pipeline_key,
+        )
+        ctx = TaskContext(event=event)
+        ctx.metadata["pipeline_root"] = str(pipeline_dir)
+        ctx.metadata["scope_seed_id"] = scope_seed
+        ctx.metadata["artifact_paths"] = {}
+
+        inventory = _load_json_model(pipeline_dir / "source_inventory.json", SourceInventoryArtifact)
+        ctx.metadata["source_inventory"] = inventory
+
+        if resume_from == "normalize_source_packet":
+            ctx = run_sync(NormalizeSourcePacketNode().process(ctx))
+            ctx.metadata["normalized_source_packet"] = _load_json_model(pipeline_dir / "normalized_source_packet.json", NormalizedSourcePacketArtifact)
+            ctx = run_sync(ExtractScopeCandidatesNode().process(ctx))
+            ctx.metadata["scope_candidates"] = _load_json_model(pipeline_dir / "scope_candidates.json", ScopeCandidatesArtifact)
+            ctx = run_sync(ShapeScopeDocumentNode().process(ctx))
+        elif resume_from == "extract_scope_candidates":
+            ctx.metadata["normalized_source_packet"] = _load_json_model(pipeline_dir / "normalized_source_packet.json", NormalizedSourcePacketArtifact)
+            ctx = run_sync(ExtractScopeCandidatesNode().process(ctx))
+            ctx.metadata["scope_candidates"] = _load_json_model(pipeline_dir / "scope_candidates.json", ScopeCandidatesArtifact)
+            ctx = run_sync(ShapeScopeDocumentNode().process(ctx))
+        elif resume_from == "shape_scope_document":
+            ctx.metadata["normalized_source_packet"] = _load_json_model(pipeline_dir / "normalized_source_packet.json", NormalizedSourcePacketArtifact)
+            ctx.metadata["scope_candidates"] = _load_json_model(pipeline_dir / "scope_candidates.json", ScopeCandidatesArtifact)
+            ctx = run_sync(ShapeScopeDocumentNode().process(ctx))
+        else:
+            raise ValueError("resume_from must be one of normalize_source_packet, extract_scope_candidates, shape_scope_document")
+
+        ctx = run_sync(RegisterScopeSetNode().process(ctx))
+        ctx = run_sync(ApprovalReadyPackageNode().process(ctx))
+        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")
+        return SourceToScopeDagResult(
+            exit_code=exit_code,
+            run_id=run_id,
+            pipeline_dir=Path(str(ctx.metadata.get("pipeline_root") or pipeline_dir)),
+            message=str(ctx.metadata.get("message") or f"Resumed source->scope from {resume_from}"),
+            outcome=dict(ctx.metadata.get("outcome") or {"resume_from": resume_from}),
+        )
+    except SourceScopeGenerationFailure as exc:
+        store.mark_run_finished(run_id=run_id, status="failed")
+        return _generation_failure_result(
+            pipeline_dir=pipeline_dir,
+            run_id=run_id,
+            project_id=project_id,
+            source_intake_id=source_intake_id,
+            stage_name=exc.stage_name,
+            reason=exc.reason,
+        )
+    except Exception:
+        store.mark_run_finished(run_id=run_id, status="failed")
+        raise
+    finally:
+        _CURRENT_STORE = None
+        _CURRENT_RUN_ID = None
+
+
+def run_source_to_scope_dag(
+    *,
+    repo_root: Path,
+    store: ExecutionStore,
+    project_id: str,
+    source_intake_id: str | None = None,
+    source_refs: list[dict[str, Any]] | None = None,
+    source_packet_id: str | None = None,
+    source_texts: list[dict[str, Any]] | None = None,
+    requested_by: str = "marcus",
+    mode: str = "draft_scope_generation",
+) -> SourceToScopeDagResult:
+    effective_source_intake_id = source_intake_id or source_packet_id
+    if not effective_source_intake_id:
+        raise ValueError("source_intake_id or source_packet_id is required")
+    effective_refs = source_refs
+    if effective_refs is None and source_texts is not None:
+        effective_refs = [
+            {
+                "type": item.get("source_type") or item.get("type") or "notes",
+                "path": item.get("path") or item.get("location"),
+                "title": item.get("title"),
+                "text": item.get("text"),
+                "metadata": item.get("metadata") or {},
+            }
+            for item in source_texts
+        ]
+    if effective_refs is None:
+        raise ValueError("source_refs or source_texts is required")
+    normalized_refs = [SourceRef.model_validate(item) for item in effective_refs]
+    pipeline_key = build_pipeline_key(
+        repo_root=repo_root,
+        project_id=project_id,
+        source_intake_id=effective_source_intake_id,
+        source_refs=[item.model_dump() for item in normalized_refs],
+    )
+    scope_seed = _stable_id("scope_seed_", {"project_id": project_id, "source_intake_id": effective_source_intake_id, "source_refs": [item.model_dump() for item in normalized_refs]})
+    pipeline_dir = _pipeline_root(repo_root, scope_id=scope_seed, pipeline_key=pipeline_key)
+    pipeline_dir.mkdir(parents=True, exist_ok=True)
+
+    run_id = store.create_run(
+        dag_id=DAG_ID,
+        dag_version="v1_scaffold",
+        root_correlation_id=f"corr_{pipeline_key}",
+        config={
+            "project_id": project_id,
+            "source_intake_id": effective_source_intake_id,
+            "pipeline_key": pipeline_key,
+            "requested_by": requested_by,
+            "mode": mode,
+        },
+    )
+    store.mark_run_started(run_id=run_id)
+
+    wf = SourceToScopeWorkflow()
+    global _CURRENT_STORE, _CURRENT_RUN_ID
+    _CURRENT_STORE = store
+    _CURRENT_RUN_ID = run_id
+    try:
+        ctx = wf.run(
+            {
+                "repo_root": str(repo_root),
+                "project_id": project_id,
+                "source_intake_id": effective_source_intake_id,
+                "source_refs": [item.model_dump() for item in normalized_refs],
+                "requested_by": requested_by,
+                "mode": mode,
+                "pipeline_key": pipeline_key,
+            }
+        )
+    except SourceScopeGenerationFailure as exc:
+        store.mark_run_finished(run_id=run_id, status="failed")
+        return _generation_failure_result(
+            pipeline_dir=pipeline_dir,
+            run_id=run_id,
+            project_id=project_id,
+            source_intake_id=effective_source_intake_id,
+            stage_name=exc.stage_name,
+            reason=exc.reason,
+        )
+    finally:
+        _CURRENT_STORE = None
+        _CURRENT_RUN_ID = None
+
+    exit_code = int(ctx.metadata.get("exit_code") or 0)
+    try:
+        if exit_code == 0:
+            _sync_registered_scopes_to_supabase(
+                repo_root=repo_root,
+                project_id=project_id,
+                scope_set_id=str(ctx.metadata.get("outcome", {}).get("scope_set_id") or ""),
+                run_id=run_id,
+                pipeline_dir=Path(str(ctx.metadata.get("pipeline_root") or pipeline_dir)),
+            )
+    except Exception:
+        store.mark_run_finished(run_id=run_id, status="failed")
+        raise
+    store.mark_run_finished(run_id=run_id, status="succeeded" if exit_code == 0 else "failed")
+    return SourceToScopeDagResult(
+        exit_code=exit_code,
+        run_id=run_id,
+        pipeline_dir=Path(str(ctx.metadata.get("pipeline_root") or pipeline_dir)),
+        message=str(ctx.metadata.get("message") or ""),
+        outcome=dict(ctx.metadata.get("outcome") or {}),
+    )
+
+# Deterministic gating/persistence scaffold for pre-shaped source->scope artifacts.
+
+SourceDocsToScopesDagResult = SourceToScopeDagResult
+
+
+class SourceDocsToScopesDagEvent(BaseModel):
+    repo_root: str
+    project_id: str
+    source_packet_path: str | None = None
+    source_packet_inline: dict[str, Any] | None = None
+    scope_outline_path: str | None = None
+    scope_outline_inline: dict[str, Any] | None = None
+    pipeline_key: str
+
+
+def _load_json_payload(*, inline_payload: dict[str, Any] | None, payload_path: Path | None) -> dict[str, Any]:
+    if inline_payload and payload_path:
+        raise ValueError("Provide exactly one of inline payload or payload path")
+    if payload_path:
+        return json.loads(payload_path.read_text(encoding="utf-8"))
+    if inline_payload:
+        return dict(inline_payload)
+    raise ValueError("Missing required DAG payload")
+
+
+class LoadCoverageInputsNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        event = task_context.event
+        repo_root = Path(event.repo_root)
+        source_packet = NormalizedSourcePacketArtifact.model_validate(
+            _load_json_payload(
+                inline_payload=event.source_packet_inline,
+                payload_path=Path(event.source_packet_path) if event.source_packet_path else None,
+            )
+        )
+        outline = ScopeOutlineArtifact.model_validate(
+            _load_json_payload(
+                inline_payload=event.scope_outline_inline,
+                payload_path=Path(event.scope_outline_path) if event.scope_outline_path else None,
+            )
+        )
+        if source_packet.project_id != event.project_id or outline.project_id != event.project_id:
+            raise ValueError("source->scope deterministic gate received mismatched project_id")
+        pipeline_root = _pipeline_root(repo_root, scope_id=outline.scope_set_id, pipeline_key=event.pipeline_key)
+        _write_json(pipeline_root / "normalized_source_packet.json", source_packet.model_dump())
+        _write_json(pipeline_root / "scope_outline.json", outline.model_dump())
+        task_context.metadata["pipeline_root"] = str(pipeline_root)
+        task_context.metadata["normalized_source_packet"] = source_packet
+        task_context.metadata["scope_outline"] = outline
+        self.save_output(outline)
+        return task_context
+
+
+class DeterministicEscalationPackageNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        event = task_context.event
+        report = task_context.metadata["scope_coverage_report"]
+        outline = task_context.metadata["scope_outline"]
+        packet = task_context.metadata["normalized_source_packet"]
+        artifact = ScopeRevisionPackageArtifact(
+            project_id=event.project_id,
+            scope_set_id=outline.scope_set_id,
+            proposed_status="needs_revision" if report.coverage_status == "revise" else "human_review_required",
+            major_gaps=report.uncovered_requirements,
+            unsupported_items=report.unsupported_inferred_scope_items,
+            recommended_revision_actions=report.review_recommendations
+            or ["Tighten scope coverage and ensure each major source-backed requirement is represented."],
+            manual_review_questions=[item.question for item in packet.open_questions_with_assumptions],
+            coverage_status=report.coverage_status,
+        )
+        stage_path = Path(task_context.metadata["pipeline_root"]) / "scope_revision_package.json"
+        _write_json(stage_path, artifact.model_dump())
+        resolution_status = "human_review_required" if report.coverage_status == "escalate" else "needs_revision"
+        summary = SourceScopeDagSummary(
+            exit_code=2,
+            run_id=_store_run()[1],
+            pipeline_dir=str(task_context.metadata["pipeline_root"]),
+            message="source->scope run complete with revision/escalation package",
+            outcome={
+                "project_id": event.project_id,
+                "scope_set_id": outline.scope_set_id,
+                "coverage_status": report.coverage_status,
+                "registered_scope_count": 0,
+                "resolution_status": resolution_status,
+            },
+        )
+        _write_json(Path(task_context.metadata["pipeline_root"]) / "summary.json", summary.model_dump())
+        task_context.metadata["outcome"] = dict(summary.outcome)
+        task_context.metadata["message"] = json.dumps({**summary.outcome, "run_id": summary.run_id, "pipeline_dir": summary.pipeline_dir}, sort_keys=True) + "\n"
+        task_context.metadata["exit_code"] = int(summary.exit_code)
+        self.save_output(artifact)
+        return task_context
+
+
+class _DeterministicRoutePass(RouterNode):
+    def determine_next_node(self, task_context: TaskContext) -> Node | None:
+        decision = task_context.metadata["coverage_decision"]
+        if decision.decision == "pass":
+            return DeterministicRegisterScopeSetNode(task_context=task_context)
+        return None
+
+
+class _DeterministicRoutePassWithAssumptions(RouterNode):
+    def determine_next_node(self, task_context: TaskContext) -> Node | None:
+        decision = task_context.metadata["coverage_decision"]
+        if decision.decision == "pass_with_assumptions":
+            return DeterministicRegisterScopeSetNode(task_context=task_context)
+        return None
+
+
+class _DeterministicRouteRevise(RouterNode):
+    def determine_next_node(self, task_context: TaskContext) -> Node | None:
+        decision = task_context.metadata["coverage_decision"]
+        if decision.decision == "revise":
+            return DeterministicEscalationPackageNode(task_context=task_context)
+        return None
+
+
+class _DeterministicRouteEscalate(RouterNode):
+    def determine_next_node(self, task_context: TaskContext) -> Node | None:
+        decision = task_context.metadata["coverage_decision"]
+        if decision.decision == "escalate":
+            return DeterministicEscalationPackageNode(task_context=task_context)
+        return None
+
+
+class DeterministicCoverageDecisionRouter(BaseRouter):
+    def __init__(self) -> None:
+        self.routes = [
+            _DeterministicRoutePass(),
+            _DeterministicRoutePassWithAssumptions(),
+            _DeterministicRouteRevise(),
+            _DeterministicRouteEscalate(),
+        ]
+        self.fallback = DeterministicEscalationPackageNode()
+
+
+class DeterministicRegisterScopeSetNode(RegisterScopeSetNode):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        await super().process(task_context)
+        outline = task_context.metadata["scope_outline"]
+        repo_root = Path(task_context.event.repo_root)
+        registry_root = repo_root / ".devflow" / "projects" / outline.project_id / "scope_sets"
+        registry_root.mkdir(parents=True, exist_ok=True)
+        scope_set_registry_path = registry_root / f"{outline.scope_set_id}.json"
+        record = task_context.metadata["scope_registry_record"]
+        _write_json(
+            scope_set_registry_path,
+            {
+                "project_id": outline.project_id,
+                "scope_set_id": outline.scope_set_id,
+                "scope_set_title": outline.scope_set_title,
+                "status": "draft",
+                "coverage_status": record.coverage_status,
+                "scope_item_ids": [item.scope_id for item in outline.scope_items],
+                "cross_cutting_constraints": outline.cross_cutting_constraints,
+                "review_notes": outline.review_notes,
+                "approval_required_before_scope_to_idea": True,
+            },
+        )
+        record.scope_set_registry_ref = str(scope_set_registry_path)
+        _write_json(Path(task_context.metadata["pipeline_root"]) / "scope_registry_record.json", record.model_dump())
+        task_context.metadata["scope_registry_record"] = record
+        return task_context
+
+
+class DeterministicApprovalReadyPackageNode(ApprovalReadyPackageNode):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        await super().process(task_context)
+        outline = task_context.metadata["scope_outline"]
+        report = task_context.metadata["scope_coverage_report"]
+        registry = task_context.metadata["scope_registry_record"]
+        stage_path = Path(task_context.metadata["pipeline_root"]) / "approval_package.json"
+        artifact = ApprovalReadyPackageArtifact.model_validate(json.loads(stage_path.read_text(encoding="utf-8")))
+        artifact.recommended_next_action = (
+            "Review and approve this registered draft scope set. Do not treat it as idea-sufficiency output until humans approve the scope boundary."
+        )
+        artifact.downstream_ready_if_approved = (
+            "Once approved, these registered scope artifacts become the canonical client-affirmed scope boundary for downstream scope->idea enrichment, not direct story decomposition."
+        )
+        artifact.scope_registry_record_ref = registry.scope_set_registry_ref
+        _write_json(stage_path, artifact.model_dump())
+        summary = SourceScopeDagSummary(
+            exit_code=0,
+            run_id=_store_run()[1],
+            pipeline_dir=str(task_context.metadata["pipeline_root"]),
+            message="source->scope run complete",
+            outcome={
+                "project_id": outline.project_id,
+                "scope_set_id": outline.scope_set_id,
+                "coverage_status": report.coverage_status,
+                "registered_scope_count": len(registry.registered_scope_items),
+                "resolution_status": "ready_for_review",
+            },
+        )
+        _write_json(Path(task_context.metadata["pipeline_root"]) / "summary.json", summary.model_dump())
+        task_context.metadata["outcome"] = dict(summary.outcome)
+        task_context.metadata["message"] = json.dumps({**summary.outcome, "run_id": summary.run_id, "pipeline_dir": summary.pipeline_dir}, sort_keys=True) + "\n"
+        task_context.metadata["exit_code"] = int(summary.exit_code)
+        return task_context
+
+
+class SourceDocsToScopesWorkflow(Workflow):
+    workflow_schema = WorkflowSchema(
+        description="Source docs -> scopes deterministic gate/register DAG (load packet+outline -> gate -> route -> register/package)",
+        event_schema=SourceDocsToScopesDagEvent,
+        start=LoadCoverageInputsNode,
+        nodes=[
+            NodeConfig(node=LoadCoverageInputsNode, connections=[CoverageGateNode]),
+            NodeConfig(node=CoverageGateNode, connections=[CoverageDecisionNode]),
+            NodeConfig(node=CoverageDecisionNode, connections=[DeterministicCoverageDecisionRouter]),
+            NodeConfig(node=DeterministicCoverageDecisionRouter, connections=[DeterministicRegisterScopeSetNode, DeterministicEscalationPackageNode], is_router=True),
+            NodeConfig(node=DeterministicRegisterScopeSetNode, connections=[DeterministicApprovalReadyPackageNode]),
+            NodeConfig(node=DeterministicApprovalReadyPackageNode, connections=[]),
+            NodeConfig(node=DeterministicEscalationPackageNode, connections=[]),
+        ],
+    )
+
+
+def run_source_docs_to_scopes_dag(
+    *,
+    repo_root: Path,
+    store: ExecutionStore,
+    project_id: str,
+    source_packet_inline: dict[str, Any] | None = None,
+    source_packet_path: Path | None = None,
+    scope_outline_inline: dict[str, Any] | None = None,
+    scope_outline_path: Path | None = None,
+) -> SourceDocsToScopesDagResult:
+    source_packet = _load_json_payload(inline_payload=source_packet_inline, payload_path=source_packet_path)
+    outline = _load_json_payload(inline_payload=scope_outline_inline, payload_path=scope_outline_path)
+    scope_set_id = str(outline.get("scope_set_id") or "scope_set_unknown")
+    pipeline_key = _stable_id(
+        "run_",
+        {"repo_root": str(repo_root), "project_id": project_id, "source_packet": source_packet, "scope_outline": outline},
+    )
+    pipeline_dir = _pipeline_root(repo_root, scope_id=scope_set_id, pipeline_key=pipeline_key)
+    pipeline_dir.mkdir(parents=True, exist_ok=True)
+
+    run_id = store.create_run(
+        dag_id="source_docs_to_scopes_dag",
+        dag_version="v1_gates_scaffold",
+        root_correlation_id=f"corr_{pipeline_key}",
+        config={"project_id": project_id, "scope_set_id": scope_set_id, "pipeline_key": pipeline_key},
+    )
+    store.mark_run_started(run_id=run_id)
+
+    wf = SourceDocsToScopesWorkflow()
+    global _CURRENT_STORE, _CURRENT_RUN_ID
+    _CURRENT_STORE = store
+    _CURRENT_RUN_ID = run_id
+    try:
+        ctx = wf.run(
+            {
+                "repo_root": str(repo_root),
+                "project_id": project_id,
+                "source_packet_inline": source_packet,
+                "source_packet_path": None,
+                "scope_outline_inline": outline,
+                "scope_outline_path": None,
+                "pipeline_key": pipeline_key,
+            }
+        )
+    finally:
+        _CURRENT_STORE = None
+        _CURRENT_RUN_ID = None
+
+    exit_code = int(ctx.metadata.get("exit_code") or 0)
+    try:
+        if exit_code == 0:
+            _sync_registered_scopes_to_supabase(
+                repo_root=repo_root,
+                project_id=project_id,
+                scope_set_id=scope_set_id,
+                run_id=run_id,
+                pipeline_dir=Path(str(ctx.metadata.get("pipeline_root") or pipeline_dir)),
+            )
+    except Exception:
+        store.mark_run_finished(run_id=run_id, status="failed")
+        raise
+    store.mark_run_finished(run_id=run_id, status="succeeded" if exit_code == 0 else "failed")
+    if exit_code == 0:
+        scope_set_registry_path = repo_root / ".devflow" / "projects" / project_id / "scope_sets" / f"{scope_set_id}.json"
+        scope_set_registry = json.loads(scope_set_registry_path.read_text(encoding="utf-8")) if scope_set_registry_path.exists() else {}
+        if not bool(scope_set_registry.get("approval_required_before_scope_to_idea")):
+            registry_path = pipeline_dir / "scope_registry_record.json"
+            if registry_path.exists():
+                registry = json.loads(registry_path.read_text(encoding="utf-8"))
+                for item in registry.get("registered_scope_items") or []:
+                    if not isinstance(item, dict):
+                        continue
+                    scope_id = str(item.get("scope_id") or "").strip()
+                    scope_payload_path = str(item.get("registry_ref") or "").strip()
+                    if not scope_id or not scope_payload_path:
+                        continue
+                    store.enqueue_scope_task(
+                        project_id=project_id,
+                        enqueue_run_id=run_id,
+                        scope_set_id=scope_set_id,
+                        scope_id=scope_id,
+                        title=scope_id,
+                        scope_payload_path=scope_payload_path,
+                    )
+    return SourceDocsToScopesDagResult(
+        exit_code=exit_code,
+        run_id=run_id,
+        pipeline_dir=Path(str(ctx.metadata.get("pipeline_root") or pipeline_dir)),
+        message=str(ctx.metadata.get("message") or ""),
+        outcome=dict(ctx.metadata.get("outcome") or {}),
+    )