devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/source_doc_mutation_dag.py

@@ -0,0 +1,1606 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+import os
+import subprocess
+import sys
+from typing import Any
+
+from pydantic import BaseModel, field_validator
+
+from .agentic_prompts import load_agentic_prompt_lines
+from .agentic_runtime import run_agent_step
+from .source_doc_assumptions import reconcile_assumptions_registry, register_assumption
+from .source_docs_schema import source_doc_template_payloads
+from .source_docs_updater import ensure_source_doc_scaffold
+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.concurrent import ConcurrentNode
+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 = "source_doc_mutation_dag"
+CANONICAL_SOURCE_DOCS = tuple(source_doc_template_payloads().keys())
+PROJECT_DOC_TARGETS = (
+    "project_charter.md",
+    "prd.md",
+    "architecture.md",
+    "ux_design.md",
+    "delivery_plan.md",
+)
+PROJECT_DOC_REFERENCE_DOCS = {
+    "richness_contract": "docs/project-doc-richness-contract.md",
+    "agent_contracts": "docs/project-doc-agent-contracts.md",
+    "reference_map": "docs/source-to-project-doc-reference-map.md",
+    "cross_reference_rules": "docs/project-doc-cross-reference-rules.md",
+}
+SUPPORT_INDEX_DOCS = {
+    "internal_source": "docs/support/source_doc_mutation/internal_source.json",
+    "internal_project": "docs/support/source_doc_mutation/internal_project.json",
+    "cross_sourceXproject": "docs/support/source_doc_mutation/cross_sourceXproject.json",
+}
+PROJECT_DOC_PRIMARY_SOURCE_DOCS = {
+    "project_charter.md": ["product_brief.json", "assumptions_registry.json"],
+    "prd.md": ["product_brief.json", "user_workflows.json", "assumptions_registry.json"],
+    "architecture.md": ["domain_entities.json", "product_brief.json", "assumptions_registry.json"],
+    "ux_design.md": ["user_workflows.json", "product_brief.json", "assumptions_registry.json"],
+    "delivery_plan.md": ["product_brief.json", "user_workflows.json", "domain_entities.json", "assumptions_registry.json"],
+}
+PROJECT_DOC_SECTION_IMPACT_MAP = {
+    "product_brief.json": ["project_charter.md", "prd.md", "architecture.md", "ux_design.md", "delivery_plan.md"],
+    "user_workflows.json": ["prd.md", "architecture.md", "ux_design.md", "delivery_plan.md"],
+    "domain_entities.json": ["prd.md", "architecture.md", "ux_design.md", "delivery_plan.md"],
+    "assumptions_registry.json": list(PROJECT_DOC_TARGETS),
+}
+REPO_BOOTSTRAP_ALLOWED_SUFFIXES = {
+    ".md",
+    ".mdx",
+    ".txt",
+    ".rst",
+    ".py",
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".json",
+    ".yaml",
+    ".yml",
+    ".toml",
+}
+REPO_BOOTSTRAP_IGNORE_DIRS = {
+    ".git",
+    ".hg",
+    ".svn",
+    ".venv",
+    "venv",
+    "node_modules",
+    "dist",
+    "build",
+    ".next",
+    ".turbo",
+    ".pytest_cache",
+    "__pycache__",
+    ".mypy_cache",
+    ".ruff_cache",
+    ".devflow",
+}
+
+
+@dataclass(frozen=True)
+class SourceDocMutationDagResult:
+    run_id: str
+    pipeline_dir: Path
+    mutation_ref: dict[str, Any]
+    result: dict[str, Any]
+
+
+class SourceDocMutationDagEvent(BaseModel):
+    project_id: str
+    idea_id: str
+    repo_root: str
+    raw_text: str = ""
+    grounded_raw_text: str = ""
+    mode: str | None = None
+    agent_runtime_mode: str | None = None
+    history_grounding_ref: str | None = None
+    existing_source_doc_refs: list[str] = []
+    explicit_source_doc_payload: dict[str, Any] | None = None
+    message_id: str | None = None
+    session_id: str | None = None
+    invoked_from: str = "idea_context_resolution"
+    pipeline_key: str | None = None
+
+
+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 _clone(value: Any) -> Any:
+    return json.loads(json.dumps(value))
+
+
+def _write_json(path: Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def _load_json_dict(path: Path, *, default: dict[str, Any]) -> dict[str, Any]:
+    if not path.exists():
+        return _clone(default)
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return _clone(default)
+    return payload if isinstance(payload, dict) else _clone(default)
+
+
+def _source_docs_dir(repo_root: Path) -> Path:
+    return repo_root / "ai_docs" / "context" / "source_docs"
+
+
+def _v2_project_docs_dir(repo_root: Path) -> Path:
+    return repo_root / "ai_docs" / "context" / "v2" / "project_docs"
+
+
+def _pipeline_root(repo_root: Path, *, idea_id: str, pipeline_key: str) -> Path:
+    safe_idea_id = idea_id or "bootstrap"
+    return repo_root / ".devflow" / "ideas" / safe_idea_id / "pipelines" / DAG_ID / pipeline_key
+
+
+def _dedupe_str_list(values: list[Any]) -> list[str]:
+    out: list[str] = []
+    for item in values:
+        if not isinstance(item, str):
+            continue
+        text = item.strip()
+        if text and text not in out:
+            out.append(text)
+    return out
+
+
+def _guess_doc_type_from_message(raw_text: str) -> str:
+    lowered = raw_text.lower()
+    for token, label in [
+        ("portal", "portal"),
+        ("dashboard", "dashboard"),
+        ("app", "app"),
+        ("api", "API"),
+        ("workflow", "workflow automation"),
+        ("system", "system"),
+        ("platform", "platform"),
+    ]:
+        if token in lowered:
+            return label
+    return "software product"
+
+
+def _infer_users(raw_text: str) -> list[str]:
+    lowered = raw_text.lower()
+    tokens = {token.strip(".,:;!?()[]{}\"'`") for token in lowered.split()}
+    users: list[str] = []
+    if "leadership" in tokens or "executive" in tokens or "executives" in tokens:
+        users.append("leadership")
+    if "board" in tokens:
+        users.append("board members")
+    if "office" in lowered and "field" in lowered:
+        users.append("team members")
+    if "team" in lowered:
+        if "service team" in lowered:
+            users.append("service team")
+        elif "support team" in lowered:
+            users.append("support team")
+        else:
+            users.append("team members")
+    if "operator" in lowered:
+        users.append("operators")
+    return list(dict.fromkeys(users))
+
+
+def _infer_scope_bullets(raw_text: str) -> list[str]:
+    lowered = raw_text.lower()
+    bullets: list[str] = []
+    for token, label in [
+        ("assignment", "task assignments"),
+        ("due date", "due dates"),
+        ("dashboard", "dashboard view"),
+        ("route", "routing"),
+        ("queue", "review queue"),
+        ("report", "report generation"),
+        ("trend", "trend analysis"),
+    ]:
+        if token in lowered:
+            bullets.append(label)
+    return list(dict.fromkeys(bullets))
+
+
+def _infer_problem(raw_text: str) -> str | None:
+    lowered = raw_text.lower()
+    if "managing tasks" in lowered or "manage tasks" in lowered:
+        return "The team needs a simpler way to manage and track work."
+    if "assignments" in lowered or "due dates" in lowered:
+        return "The team lacks a clear system for tracking assignments and due dates."
+    return None
+
+
+def _infer_goal(raw_text: str) -> str | None:
+    lowered = raw_text.lower()
+    if "dashboard" in lowered and ("assignment" in lowered or "due date" in lowered):
+        return "Give the team one place to track assignments, due dates, and task status."
+    if "managing tasks" in lowered or "manage tasks" in lowered:
+        return "Create a simple app for organizing team tasks."
+    return None
+
+
+def extract_sufficient_idea(raw_text: str) -> dict[str, Any]:
+    users = _infer_users(raw_text)
+    problem = _infer_problem(raw_text) or ""
+    goal = _infer_goal(raw_text) or ""
+    scope = _infer_scope_bullets(raw_text)
+    summary = raw_text.strip().splitlines()[0][:240] if raw_text.strip() else ""
+    return {
+        "summary": summary,
+        "problem": problem,
+        "goal": goal,
+        "target_users": users,
+        "scope": scope,
+        "constraints": [],
+        "acceptance_criteria": [],
+    }
+
+
+def _derive_product_summary(raw_text: str, sufficient_idea: dict[str, Any]) -> str:
+    summary = str(sufficient_idea.get("summary") or "").strip()
+    if summary:
+        return summary
+    users = _dedupe_str_list(list(sufficient_idea.get("target_users") or [])) or _infer_users(raw_text)
+    goal = str(sufficient_idea.get("goal") or _infer_goal(raw_text) or "").strip()
+    doc_type = _guess_doc_type_from_message(raw_text)
+    if users and goal:
+        lowered_goal = goal[0].lower() + goal[1:] if len(goal) > 1 else goal.lower()
+        return f"{doc_type.capitalize()} for {users[0]} so they can {lowered_goal}."
+    if users:
+        return f"{doc_type.capitalize()} for {users[0]}."
+    return raw_text.strip().splitlines()[0][:240] if raw_text.strip() else ""
+
+
+def _load_source_doc_state(repo_root: Path) -> dict[str, dict[str, Any]]:
+    source_docs_dir = ensure_source_doc_scaffold(repo_root).source_docs_dir
+    return {
+        name: _load_json_dict(source_docs_dir / name, default=payload)
+        for name, payload in source_doc_template_payloads().items()
+    }
+
+
+def _record_assumption(
+    *,
+    assumptions: list[dict[str, Any]],
+    doc_path: str,
+    section_key: str,
+    topic_key: str,
+    current_value: Any,
+    reasoning: str,
+    source: str,
+    message_id: str,
+) -> None:
+    registry = register_assumption(
+        {"assumptions": assumptions},
+        doc_path=doc_path,
+        section_key=section_key,
+        topic_key=topic_key,
+        current_value=current_value,
+        reasoning=reasoning,
+        source=source,
+        message_id=message_id,
+    )
+    assumptions[:] = [item for item in registry.get("assumptions") or [] if isinstance(item, dict)]
+
+
+def _render_markdown(doc_name: str, payload: Any, *, shell_only: bool = False) -> str:
+    title = doc_name.replace("_", " ").replace(".json", "").title()
+    pretty_json = json.dumps(payload, indent=2, sort_keys=True)
+    summary_lines = [f"# {title}", "", f"Derived from `ai_docs/context/source_docs/{doc_name}`.", ""]
+    if shell_only:
+        summary_lines.extend([
+            "## Scaffold Status",
+            "",
+            "Minimal scaffold-only placeholder. Repo evidence was too sparse to ground this doc yet.",
+            "",
+        ])
+    if isinstance(payload, dict):
+        for key, value in payload.items():
+            summary_lines.append(f"## {str(key).replace('_', ' ').title()}")
+            if isinstance(value, list):
+                if value:
+                    for item in value:
+                        summary_lines.append(
+                            f"- {json.dumps(item, sort_keys=True) if isinstance(item, (dict, list)) else item}"
+                        )
+                else:
+                    summary_lines.append("- _empty_")
+            elif isinstance(value, dict):
+                if value:
+                    for sub_key, sub_value in value.items():
+                        rendered = json.dumps(sub_value, sort_keys=True) if isinstance(sub_value, (dict, list)) else sub_value
+                        summary_lines.append(f"- **{sub_key}**: {rendered}")
+                else:
+                    summary_lines.append("- _empty_")
+            else:
+                summary_lines.append(str(value) if value not in (None, "") else "_empty_")
+            summary_lines.append("")
+    summary_lines.extend(["## Canonical JSON", "", "```json", pretty_json, "```", ""])
+    return "\n".join(summary_lines)
+
+
+def _compute_assumptions_delta(before: list[dict[str, Any]], after: list[dict[str, Any]]) -> dict[str, Any]:
+    before_by_id = {str(item.get("assumption_id") or item.get("assumption_key") or ""): item for item in before if isinstance(item, dict)}
+    after_by_id = {str(item.get("assumption_id") or item.get("assumption_key") or ""): item for item in after if isinstance(item, dict)}
+    added = [item for key, item in after_by_id.items() if key and key not in before_by_id]
+    removed = [item for key, item in before_by_id.items() if key and key not in after_by_id]
+    status_changes: list[dict[str, Any]] = []
+    for key, item in after_by_id.items():
+        if key not in before_by_id:
+            continue
+        prior = before_by_id[key]
+        if str(prior.get("status") or "") != str(item.get("status") or ""):
+            status_changes.append(
+                {
+                    "assumption_id": key,
+                    "assumption_key": item.get("assumption_key"),
+                    "from_status": prior.get("status"),
+                    "to_status": item.get("status"),
+                    "doc_path": item.get("doc_path"),
+                    "section_key": item.get("section_key"),
+                    "topic_key": item.get("topic_key"),
+                }
+            )
+    return {
+        "before_count": len(before_by_id),
+        "after_count": len(after_by_id),
+        "added": added,
+        "removed": removed,
+        "status_changes": status_changes,
+    }
+
+
+def _sync_v2_project_docs(
+    *,
+    repo_root: Path,
+    changed_docs: list[str],
+    source_docs: dict[str, dict[str, Any]],
+    shell_only: bool = False,
+    sync_reason: str = "deterministic_markdown_render",
+) -> dict[str, Any]:
+    v2_root = _v2_project_docs_dir(repo_root)
+    source_doc_root = v2_root / "source_docs"
+    source_doc_root.mkdir(parents=True, exist_ok=True)
+    updated_outputs: list[str] = []
+    source_hashes: dict[str, str] = {}
+
+    for doc_name, payload in sorted(source_docs.items()):
+        source_hashes[doc_name] = _stable_hash(payload)
+        md_path = source_doc_root / doc_name.replace(".json", ".md")
+        md_path.write_text(_render_markdown(doc_name, payload, shell_only=shell_only), encoding="utf-8")
+        updated_outputs.append(str(md_path.relative_to(repo_root)))
+
+    index_title = "# Canonical Source Docs Sync Index"
+    index_intro = "This directory contains derived project docs generated from canonical source docs under `ai_docs/context/source_docs/`."
+    if shell_only:
+        index_intro = (
+            "This directory contains scaffold-only derived project doc shells. Repo evidence was too sparse to infer a grounded project shape."
+        )
+    index_lines = [index_title, "", index_intro, "", "## Source Docs", ""]
+    for doc_name in sorted(source_docs):
+        md_name = doc_name.replace(".json", ".md")
+        marker = "updated" if doc_name in changed_docs else "current"
+        index_lines.append(f"- `source_docs/{md_name}` ← `{doc_name}` ({marker})")
+    index_lines.extend(["", "## Source Hashes", ""])
+    for doc_name, digest in sorted(source_hashes.items()):
+        index_lines.append(f"- `{doc_name}`: `{digest}`")
+    index_path = source_doc_root / "index.md"
+    index_path.write_text("\n".join(index_lines) + "\n", encoding="utf-8")
+    updated_outputs.append(str(index_path.relative_to(repo_root)))
+
+    return {
+        "status": "completed",
+        "derived_project_docs_root": str(v2_root),
+        "derived_source_doc_root": str(source_doc_root),
+        "updated_outputs": updated_outputs,
+        "changed_docs": changed_docs,
+        "source_hashes": source_hashes,
+        "sync_mode": sync_reason,
+        "shell_only": shell_only,
+    }
+
+
+def _list_repo_bootstrap_candidates(repo_root: Path) -> list[Path]:
+    candidates: list[Path] = []
+    for path in sorted(repo_root.rglob("*")):
+        if not path.is_file():
+            continue
+        rel = path.relative_to(repo_root).as_posix()
+        if any(part in REPO_BOOTSTRAP_IGNORE_DIRS for part in path.parts):
+            continue
+        if rel.startswith("ai_docs/context/source_docs/") or rel.startswith("ai_docs/context/v2/project_docs/") or rel.startswith("ai_docs/context/project_docs/"):
+            continue
+        if path.suffix.lower() not in REPO_BOOTSTRAP_ALLOWED_SUFFIXES:
+            continue
+        candidates.append(path)
+    return candidates
+
+
+def _read_text_safely(path: Path, *, max_chars: int = 4000) -> str:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except Exception:
+        return ""
+    return text[:max_chars]
+
+
+def _repo_bootstrap_inventory(repo_root: Path) -> dict[str, Any]:
+    candidates = _list_repo_bootstrap_candidates(repo_root)
+    evidence_files: list[dict[str, Any]] = []
+    matched_signal_files = 0
+    aggregate_tokens: set[str] = set()
+    signal_hits = {
+        "readme": 0,
+        "docs": 0,
+        "product_terms": 0,
+        "workflow_terms": 0,
+        "entity_terms": 0,
+        "scope_terms": 0,
+    }
+    product_terms = ("dashboard", "portal", "platform", "workflow", "app", "api", "service", "report")
+    workflow_terms = ("user", "users", "actor", "workflow", "journey", "task", "queue", "assign")
+    entity_terms = ("entity", "entities", "model", "models", "schema", "record", "task", "report")
+    scope_terms = ("feature", "features", "mvp", "scope", "requirements", "acceptance", "goal")
+
+    for path in candidates[:24]:
+        rel = path.relative_to(repo_root).as_posix()
+        text = _read_text_safely(path)
+        lowered = text.lower()
+        hit_count = 0
+        if path.name.lower().startswith("readme"):
+            signal_hits["readme"] += 1
+            hit_count += 1
+        if "docs/" in rel or rel.startswith("docs/") or "ai_docs/" in rel or rel.startswith("ai_docs/"):
+            signal_hits["docs"] += 1
+            hit_count += 1
+        for key, tokens in (
+            ("product_terms", product_terms),
+            ("workflow_terms", workflow_terms),
+            ("entity_terms", entity_terms),
+            ("scope_terms", scope_terms),
+        ):
+            token_hits = [token for token in tokens if token in lowered]
+            if token_hits:
+                signal_hits[key] += 1
+                hit_count += 1
+                aggregate_tokens.update(token_hits)
+        if hit_count:
+            matched_signal_files += 1
+        evidence_files.append({"path": rel, "matched_signal_count": hit_count, "size_bytes": path.stat().st_size})
+
+    has_genuine_signal = (
+        signal_hits["readme"] >= 1
+        and matched_signal_files >= 2
+        and len(aggregate_tokens) >= 3
+        and (signal_hits["product_terms"] + signal_hits["workflow_terms"] + signal_hits["entity_terms"] + signal_hits["scope_terms"]) >= 3
+    )
+
+    return {
+        "candidate_file_count": len(candidates),
+        "inspected_file_count": min(len(candidates), 24),
+        "matched_signal_files": matched_signal_files,
+        "signal_hits": signal_hits,
+        "aggregate_tokens": sorted(aggregate_tokens),
+        "evidence_files": evidence_files,
+        "has_genuine_signal": has_genuine_signal,
+        "decision_rule": {
+            "requires_readme": True,
+            "minimum_signal_files": 2,
+            "minimum_distinct_tokens": 3,
+            "minimum_signal_buckets": 3,
+        },
+    }
+
+
+def _pick_repo_grounding_text(repo_root: Path) -> tuple[str, list[str]]:
+    preferred_names = ("README.md", "README.mdx", "README.txt")
+    snippets: list[str] = []
+    evidence_paths: list[str] = []
+    for name in preferred_names:
+        path = repo_root / name
+        if path.exists() and path.is_file():
+            text = _read_text_safely(path, max_chars=2500).strip()
+            if text:
+                snippets.append(text)
+                evidence_paths.append(path.relative_to(repo_root).as_posix())
+                break
+    for path in _list_repo_bootstrap_candidates(repo_root):
+        rel = path.relative_to(repo_root).as_posix()
+        if rel in evidence_paths:
+            continue
+        if not (rel.startswith("docs/") or rel.startswith("ai_docs/")):
+            continue
+        text = _read_text_safely(path, max_chars=1800).strip()
+        if not text:
+            continue
+        snippets.append(text)
+        evidence_paths.append(rel)
+        if len(snippets) >= 3:
+            break
+    return "\n\n".join(snippets).strip(), evidence_paths
+
+
+def _has_meaningful_value(value: Any) -> bool:
+    if isinstance(value, str):
+        return bool(value.strip())
+    if isinstance(value, (list, dict, tuple, set)):
+        return bool(value)
+    return value is not None
+
+
+def _load_reference_doc(repo_root: Path, relative_path: str) -> str:
+    path = repo_root / relative_path
+    if not path.exists():
+        return ""
+    return path.read_text(encoding="utf-8")
+
+
+
+
+def _project_doc_reference_payload(repo_root: Path) -> dict[str, Any]:
+    references: dict[str, Any] = {}
+    for key, rel_path in PROJECT_DOC_REFERENCE_DOCS.items():
+        content = _load_reference_doc(repo_root, rel_path)
+        references[key] = {
+            "path": rel_path,
+            "content": content,
+            "loaded": bool(content.strip()),
+        }
+    return references
+
+
+def _load_support_index(repo_root: Path, relative_path: str, *, expected_name: str) -> dict[str, Any]:
+    path = repo_root / relative_path
+    if not path.exists():
+        bundled_path = Path(__file__).resolve().parents[2] / relative_path
+        if bundled_path.exists():
+            path = bundled_path
+    payload = _load_json_dict(path, default={})
+    return {
+        "path": relative_path,
+        "loaded": path.exists() and bool(payload),
+        "classification": str(payload.get("classification") or "unknown"),
+        "contract": str(payload.get("contract") or ""),
+        "index_name": str(payload.get("index_name") or expected_name),
+        "payload": payload,
+    }
+
+
+def _support_indexes_payload(repo_root: Path) -> dict[str, Any]:
+    indexes = {name: _load_support_index(repo_root, rel_path, expected_name=name) for name, rel_path in SUPPORT_INDEX_DOCS.items()}
+    return {
+        "classification": "support_docs",
+        "indexes": indexes,
+    }
+
+
+def _compute_changed_sections(*, before_docs: dict[str, dict[str, Any]], after_docs: dict[str, dict[str, Any]], changed_docs: list[str]) -> list[str]:
+    changed_sections: list[str] = []
+    for doc_name in changed_docs:
+        before = before_docs.get(doc_name) if isinstance(before_docs.get(doc_name), dict) else {}
+        after = after_docs.get(doc_name) if isinstance(after_docs.get(doc_name), dict) else {}
+        section_keys = sorted(set(before.keys()) | set(after.keys()))
+        for section_key in section_keys:
+            if json.dumps(before.get(section_key), sort_keys=True) != json.dumps(after.get(section_key), sort_keys=True):
+                changed_sections.append(f"{doc_name}:{section_key}")
+    return changed_sections
+
+
+def _project_doc_target_payloads(*, repo_root: Path, docs: dict[str, dict[str, Any]], changed_docs: list[str], changed_sections: list[str], support_indexes: dict[str, Any]) -> list[dict[str, Any]]:
+    cross_routes = (((support_indexes.get("indexes") or {}).get("cross_sourceXproject") or {}).get("payload") or {}).get("section_routes") or {}
+    project_entries = (((support_indexes.get("indexes") or {}).get("internal_project") or {}).get("payload") or {}).get("project_docs") or []
+    current_project_docs_root = _v2_project_docs_dir(repo_root) / "source_docs"
+    targets: list[dict[str, Any]] = []
+    for project_entry in project_entries:
+        if not isinstance(project_entry, dict):
+            continue
+        project_doc_name = str(project_entry.get("project_doc_name") or "").strip()
+        if not project_doc_name:
+            continue
+        primary_source_docs = _dedupe_str_list(list(project_entry.get("primary_source_docs") or []))
+        routed_sections = [section_ref for section_ref in changed_sections if project_doc_name in list(cross_routes.get(section_ref) or [])]
+        directly_impacted_by_changed_docs = _dedupe_str_list([section_ref.split(":", 1)[0] for section_ref in routed_sections])
+        supporting_source_docs = list(dict.fromkeys(primary_source_docs + directly_impacted_by_changed_docs))
+        existing_project_doc_path = current_project_docs_root / project_doc_name
+        existing_project_doc_content = existing_project_doc_path.read_text(encoding="utf-8") if existing_project_doc_path.exists() else ""
+        targets.append(
+            {
+                "project_doc_name": project_doc_name,
+                "primary_source_docs": primary_source_docs,
+                "supporting_source_docs": supporting_source_docs,
+                "directly_impacted_by_changed_docs": directly_impacted_by_changed_docs,
+                "routed_changed_sections": routed_sections,
+                "canonical_source_docs": {name: _clone(docs.get(name, {})) for name in supporting_source_docs},
+                "existing_project_doc": {
+                    "path": str(existing_project_doc_path.relative_to(repo_root)) if existing_project_doc_path.exists() else str(existing_project_doc_path.relative_to(repo_root)),
+                    "content": existing_project_doc_content,
+                    "loaded": bool(existing_project_doc_content.strip()),
+                },
+            }
+        )
+    if not targets:
+        return []
+    fallback_targets: list[dict[str, Any]] = []
+    for item in targets:
+        if item["routed_changed_sections"]:
+            fallback_targets.append(item)
+            continue
+        if any(doc_name in changed_docs for doc_name in item["primary_source_docs"]):
+            copied = dict(item)
+            copied["directly_impacted_by_changed_docs"] = [doc_name for doc_name in item["primary_source_docs"] if doc_name in changed_docs]
+            fallback_targets.append(copied)
+    return fallback_targets
+
+
+def _apply_explicit_source_doc_payload(
+    *, docs: dict[str, dict[str, Any]], explicit_payload: dict[str, Any], changed_docs: list[str]
+) -> None:
+    for doc_name in CANONICAL_SOURCE_DOCS:
+        incoming = explicit_payload.get(doc_name)
+        if not isinstance(incoming, dict):
+            continue
+        merged = dict(docs[doc_name])
+        for key, value in incoming.items():
+            merged[key] = value
+        if json.dumps(merged, sort_keys=True) != json.dumps(docs[doc_name], sort_keys=True):
+            docs[doc_name] = merged
+            if doc_name not in changed_docs:
+                changed_docs.append(doc_name)
+
+
+def build_source_doc_mutation_request(
+    *,
+    project_id: str,
+    idea_id: str,
+    repo_root: Path,
+    raw_text: str,
+    grounded_raw_text: str,
+    mode: str | None = None,
+    agent_runtime_mode: str | None = None,
+    history_grounding_ref: str | None = None,
+    existing_source_doc_refs: list[str] | None = None,
+    explicit_source_doc_payload: dict[str, Any] | None = None,
+    message_id: str | None = None,
+    session_id: str | None = None,
+    invoked_from: str = "idea_context_resolution",
+    pipeline_key: str | None = None,
+) -> dict[str, Any]:
+    effective_mode = mode
+    if effective_mode is None:
+        effective_mode = "ideation_mutation" if (raw_text or grounded_raw_text or explicit_source_doc_payload) else "repo_bootstrap"
+    event = SourceDocMutationDagEvent(
+        project_id=project_id,
+        idea_id=idea_id,
+        repo_root=str(repo_root),
+        raw_text=raw_text,
+        grounded_raw_text=grounded_raw_text,
+        mode=effective_mode,
+        agent_runtime_mode=agent_runtime_mode,
+        history_grounding_ref=history_grounding_ref,
+        existing_source_doc_refs=existing_source_doc_refs or [],
+        explicit_source_doc_payload=explicit_source_doc_payload,
+        message_id=message_id,
+        session_id=session_id,
+        invoked_from=invoked_from,
+        pipeline_key=pipeline_key,
+    )
+    payload = event.model_dump()
+    if not payload.get("message_id"):
+        payload["message_id"] = _stable_id(
+            "msg_",
+            {"idea_id": idea_id, "raw_text": raw_text, "mode": payload.get("mode")},
+            size=16,
+        )
+    if not payload.get("pipeline_key"):
+        payload["pipeline_key"] = _stable_id(
+            "sdm_",
+            {
+                "idea_id": idea_id,
+                "project_id": project_id,
+                "raw_text": raw_text,
+                "grounded_raw_text": grounded_raw_text,
+                "mode": payload.get("mode"),
+            },
+            size=16,
+        )
+    return payload
+
+
+class SourceDocSectionArtifact(BaseModel):
+    explicit_facts: list[str] = []
+    assumed_facts: list[str] = []
+    rationale: list[str] = []
+    confidence_notes: list[str] = []
+    section_payload: dict[str, Any]
+    assumption_entries: list[dict[str, Any]] = []
+    cross_section_dependencies: list[str] = []
+    mode: str = "unknown"
+
+
+class SourceDocCoherenceArtifact(BaseModel):
+    docs: dict[str, dict[str, Any]]
+    assumptions: list[dict[str, Any]]
+    notes: list[str] = []
+    mode: str = "unknown"
+
+
+class ProjectDocCoherenceArtifact(BaseModel):
+    notes: list[str] = []
+    mode: str = "unknown"
+
+    @field_validator("notes", mode="before")
+    @classmethod
+    def _normalize_notes(cls, value: Any) -> list[str]:
+        if value is None:
+            return []
+        if not isinstance(value, list):
+            value = [value]
+        out: list[str] = []
+        for item in value:
+            if isinstance(item, str):
+                text = item.strip()
+            elif isinstance(item, dict):
+                text = str(item.get("note") or item.get("summary") or item.get("detail") or json.dumps(item, sort_keys=True))
+            else:
+                text = str(item)
+            text = text.strip()
+            if text:
+                out.append(text)
+        return out
+
+
+def _resolve_agent_runtime_mode(payload: dict[str, Any]) -> str:
+    requested = str(payload.get("agent_runtime_mode") or os.environ.get("DEVFLOW_SOURCE_DOC_AGENT_MODE") or "").strip().lower()
+    if requested:
+        if requested not in {"real", "stub"}:
+            raise RuntimeError(f"Unsupported source doc agent runtime mode: {requested!r}. Use 'real' or 'stub'.")
+        return requested
+    if os.environ.get("PYTEST_CURRENT_TEST"):
+        return "stub"
+    return "real"
+
+
+def _record_agent_run(*, task_context: TaskContext, node_name: str, stage_name: str, runtime_mode: str, response_mode: str, prompt: dict[str, Any] | None = None, response: dict[str, Any] | None = None, raw_stdout: str = "", raw_stderr: str = "", error: str | None = None) -> None:
+    runs = task_context.metadata.setdefault("agent_runs", [])
+    runs.append({
+        "node_name": node_name,
+        "stage_name": stage_name,
+        "runtime_mode": runtime_mode,
+        "response_mode": response_mode,
+        "prompt": prompt,
+        "response": response,
+        "raw_stdout": raw_stdout,
+        "raw_stderr": raw_stderr,
+        "error": error,
+    })
+
+
+def _mark_changed(changed_docs: list[str], name: str) -> None:
+    if name not in changed_docs:
+        changed_docs.append(name)
+
+
+def _contains_any(text: str, tokens: tuple[str, ...]) -> bool:
+    lowered = text.lower()
+    return any(token in lowered for token in tokens)
+
+
+def _infer_out_of_scope(raw_text: str) -> list[str]:
+    lowered = raw_text.lower()
+    exclusions: list[str] = []
+    if "task" in lowered:
+        exclusions.append("advanced workforce planning beyond task assignment and tracking")
+    if "dashboard" in lowered or "app" in lowered or "platform" in lowered:
+        exclusions.append("fully custom reporting outside the core workflow views")
+    return list(dict.fromkeys(exclusions))
+
+
+def _infer_non_goals(raw_text: str) -> list[str]:
+    lowered = raw_text.lower()
+    non_goals: list[str] = []
+    if "task" in lowered:
+        non_goals.append("replace every surrounding back-office process in the first release")
+    if "staff" in lowered or "team" in lowered or "operator" in lowered:
+        non_goals.append("optimize for external customer self-service in the first release")
+    return list(dict.fromkeys(non_goals))
+
+
+def _infer_constraints(raw_text: str) -> list[str]:
+    lowered = raw_text.lower()
+    constraints: list[str] = []
+    if "staff" in lowered or "team" in lowered or "operator" in lowered:
+        constraints.append("Permissions should keep assignment and status changes visible only to the relevant internal team roles.")
+    if "dashboard" in lowered:
+        constraints.append("The initial experience should fit a lightweight dashboard-first workflow rather than a complex multi-surface suite.")
+    if "task" in lowered:
+        constraints.append("The first release should keep the data model simple enough for dependable task creation, assignment, and status tracking.")
+    return list(dict.fromkeys(constraints))
+
+
+def _infer_success_criteria(raw_text: str) -> list[str]:
+    lowered = raw_text.lower()
+    criteria: list[str] = []
+    if "task" in lowered:
+        criteria.append("Staff can create a task, assign an owner, and update status without leaving the product.")
+    if "assign" in lowered:
+        criteria.append("Managers can see who owns each task and which work is unassigned or overdue.")
+    if "dashboard" in lowered or "app" in lowered or "platform" in lowered:
+        criteria.append("The team can review the current work queue from a shared dashboard view.")
+    return list(dict.fromkeys(criteria))
+
+
+def _derive_primary_actor(users: list[str], raw_text: str) -> str:
+    if users:
+        return users[0]
+    lowered = raw_text.lower()
+    if "staff" in lowered:
+        return "staff"
+    return "internal operators"
+
+
+def _infer_primary_workflows(raw_text: str, users: list[str]) -> list[dict[str, Any]]:
+    lowered = raw_text.lower()
+    actor = _derive_primary_actor(users, raw_text)
+    workflows: list[dict[str, Any]] = []
+    if "task" in lowered:
+        workflows.append({
+            "workflow_key": "wf_capture_task",
+            "actor": actor,
+            "summary": "Capture a new task with enough context for the team to act on it.",
+            "trigger": "New work or follow-up request is identified.",
+            "steps": [
+                "Open the task app and create a new task record.",
+                "Add the core task details, priority, and any due-date context.",
+                "Save the task so it becomes visible to the team queue.",
+            ],
+            "result": "A trackable task exists in the shared system.",
+            "status": "draft",
+        })
+        if ("task" in lowered or "assignment" in lowered or "assign" in lowered) and _contains_any(lowered, ("assign", "staff", "team", "operator")):
+            workflows.append({
+                "workflow_key": "wf_assign_and_track_task",
+                "actor": actor,
+                "summary": "Assign a task to the right staff member and track progress to completion.",
+                "trigger": "A task needs an owner or updated status.",
+                "steps": [
+                    "Review the open task queue or dashboard.",
+                    "Assign the task to a staff owner based on responsibility or availability.",
+                    "Update task status as work starts, pauses, or completes.",
+                    "Review overdue or blocked work and reassign if needed.",
+                ],
+                "result": "Each active task has a visible owner and current status.",
+                "status": "draft",
+            })
+    return workflows
+
+
+def _infer_alternate_flows(raw_text: str, users: list[str]) -> list[dict[str, Any]]:
+    lowered = raw_text.lower()
+    actor = _derive_primary_actor(users, raw_text)
+    alternates: list[dict[str, Any]] = []
+    if "task" in lowered and _contains_any(lowered, ("assign", "staff", "team", "operator")):
+        alternates.append({
+            "workflow_key": "wf_reassign_task",
+            "actor": actor,
+            "summary": "Reassign work when the original owner is unavailable or the task was routed incorrectly.",
+            "status": "draft",
+        })
+    if "due date" in lowered or "deadline" in lowered or "task" in lowered:
+        alternates.append({
+            "workflow_key": "wf_handle_overdue_task",
+            "actor": actor,
+            "summary": "Escalate or reprioritize overdue tasks so they do not disappear from the team queue.",
+            "status": "draft",
+        })
+    return alternates
+
+
+def _infer_edge_cases(raw_text: str) -> list[str]:
+    lowered = raw_text.lower()
+    edge_cases: list[str] = []
+    if "task" in lowered:
+        edge_cases.extend([
+            "Tasks may be created without enough detail to assign confidently on the first pass.",
+            "Tasks can become blocked or overdue and need an escalation path.",
+        ])
+    if "assign" in lowered or "staff" in lowered or "team" in lowered:
+        edge_cases.append("A task may need reassignment when the initial owner is unavailable or the wrong role picked it up.")
+    return list(dict.fromkeys(edge_cases))
+
+
+def _infer_entity_bundle(raw_text: str, users: list[str]) -> tuple[list[dict[str, Any]], list[dict[str, Any]], list[str]]:
+    lowered = raw_text.lower()
+    entities: list[dict[str, Any]] = []
+    relationships: list[dict[str, Any]] = []
+    ownership: list[str] = []
+    primary_actor = _derive_primary_actor(users, raw_text)
+    if "task" in lowered:
+        entities.append({
+            "entity_key": "task",
+            "label": "Task",
+            "purpose": "Represents a unit of work the team needs to capture, assign, and track through completion.",
+            "attributes": [
+                {"name": "title", "type": "string", "required": True, "notes": "Short operator-facing summary."},
+                {"name": "details", "type": "text", "required": False, "notes": "Working description or handoff context."},
+                {"name": "status", "type": "enum", "required": True, "notes": "Compact lifecycle state for visibility and reporting."},
+                {"name": "priority", "type": "enum", "required": False, "notes": "Simple urgency cue for triage."},
+                {"name": "due_date", "type": "datetime", "required": False, "notes": "Deadline used for queue ordering and overdue handling."},
+            ],
+            "integrity_rules": [
+                "A task must have a title before it can be saved.",
+                "A completed task should retain a terminal status until intentionally reopened.",
+            ],
+            "business_rules": [
+                "Each active task has at most one current assignee in the first release.",
+                "Tasks may exist unassigned immediately after capture.",
+            ],
+            "authority_rules": [
+                "Task content and assignment changes are managed by internal team members, not external users.",
+            ],
+            "lifecycle": ["created", "assigned", "in_progress", "completed"],
+            "workflow_links": ["wf_capture_task", "wf_assign_and_track_task"],
+            "unresolved_questions": [
+                "Whether blocked/cancelled states are needed beyond the compact default lifecycle.",
+            ],
+            "status": "draft",
+        })
+    if ("task" in lowered or "assignment" in lowered or "assign" in lowered) and _contains_any(lowered, ("assign", "staff", "team", "operator")):
+        entities.append({
+            "entity_key": "staff_member",
+            "label": "Staff Member",
+            "purpose": "Represents an internal person who can own work and update task progress.",
+            "attributes": [
+                {"name": "display_name", "type": "string", "required": True, "notes": "Human-readable owner name."},
+                {"name": "role", "type": "string", "required": False, "notes": "Informational role/persona label until permissions are clarified."},
+                {"name": "availability_state", "type": "enum", "required": False, "notes": "Optional signal for assignment decisions."},
+            ],
+            "integrity_rules": [
+                "An assignee reference should resolve to one active internal staff record.",
+            ],
+            "business_rules": [
+                "Staff members can own many tasks over time.",
+            ],
+            "authority_rules": [
+                "Staff identity data is maintained by the internal operating team or its delegated manager.",
+            ],
+            "workflow_links": ["wf_assign_and_track_task"],
+            "unresolved_questions": [
+                "Whether roles remain informational or become permission-bearing in v1.",
+            ],
+            "status": "draft",
+        })
+        ownership.append(f"{primary_actor} or a related team lead is assumed to control assignment decisions until role permissions are clarified.")
+    if "dashboard" in lowered or "queue" in lowered:
+        entities.append({
+            "entity_key": "task_queue_view",
+            "label": "Task Queue View",
+            "purpose": "Represents the shared operational view of open and in-progress work rather than a separate business record.",
+            "entity_kind": "derived_view",
+            "attributes": [
+                {"name": "filters", "type": "object", "required": False, "notes": "Simple filtering for status, owner, or urgency."},
+                {"name": "sort_order", "type": "enum", "required": False, "notes": "Queue ordering such as due date or priority."},
+                {"name": "status_groups", "type": "list", "required": False, "notes": "Compact groupings for dashboard visibility."},
+            ],
+            "integrity_rules": [
+                "The queue view is derived from task records and should not become the source of truth for task state.",
+            ],
+            "business_rules": [
+                "The initial release assumes one shared queue view is sufficient for the team.",
+            ],
+            "authority_rules": [
+                "View configuration may be adjustable, but task records remain authoritative for workflow state.",
+            ],
+            "workflow_links": ["wf_assign_and_track_task"],
+            "unresolved_questions": [
+                "Whether multiple team-specific queue views are needed after the first release.",
+            ],
+            "status": "draft",
+        })
+    entity_keys = {item["entity_key"] for item in entities}
+    if {"task", "staff_member"}.issubset(entity_keys):
+        relationships.append({
+            "relationship_key": "task_current_assignee",
+            "relationship_type": "assignment",
+            "from_entity": "task",
+            "to_entity": "staff_member",
+            "cardinality": "many_to_one",
+            "summary": "Each active task may reference one current owner, while a staff member can own many tasks.",
+            "integrity_rules": [
+                "A task cannot reference more than one current assignee at the same time.",
+            ],
+            "business_rules": [
+                "Assignment may change over time without creating a new task record.",
+            ],
+            "authority_rules": [
+                "Assignment changes are controlled by internal operators or managers until a stricter RBAC model is confirmed.",
+            ],
+            "unresolved_questions": [
+                "Whether reassignment history needs its own event log in the first release.",
+            ],
+            "status": "draft",
+        })
+    if {"task", "task_queue_view"}.issubset(entity_keys):
+        relationships.append({
+            "relationship_key": "task_visible_in_queue_view",
+            "relationship_type": "projection",
+            "from_entity": "task",
+            "to_entity": "task_queue_view",
+            "cardinality": "many_to_many",
+            "summary": "Open and in-progress tasks appear in the shared queue/dashboard used for triage and tracking.",
+            "integrity_rules": [
+                "Queue membership is derived from task state rather than stored as an independent authoritative record.",
+            ],
+            "business_rules": [
+                "Closed tasks may drop out of the default queue while remaining searchable elsewhere.",
+            ],
+            "authority_rules": [
+                "Queue visibility rules should follow task visibility and team permissions.",
+            ],
+            "unresolved_questions": [
+                "Whether completed work stays visible by default or moves to a historical view.",
+            ],
+            "status": "draft",
+        })
+    if not ownership and entities:
+        ownership.append("One internal team is assumed to own task and staff assignment records until a fuller authority model is confirmed.")
+    return entities, relationships, ownership
+
+
+def _enrich_sparse_source_docs(*, grounded_text: str, docs: dict[str, dict[str, Any]], assumptions: list[dict[str, Any]], payload: dict[str, Any], requested_mode: str) -> tuple[dict[str, dict[str, Any]], list[dict[str, Any]], list[str]]:
+    if requested_mode != "ideation_mutation":
+        return docs, assumptions, []
+    notes: list[str] = []
+    product = docs["product_brief.json"]
+    workflows = docs["user_workflows.json"]
+    entities = docs["domain_entities.json"]
+    if not isinstance(product.get("scope"), dict):
+        product["scope"] = {}
+    users = _dedupe_str_list(list(product.get("target_users") or []) + list(workflows.get("actors") or []) + _infer_users(grounded_text))
+    if not product.get("target_users") and users:
+        product["target_users"] = users
+        notes.append("Aligned target users from workflow actors/inferred sparse intake roles.")
+    if not workflows.get("actors") and users:
+        workflows["actors"] = users
+        notes.append("Filled workflow actors from the reconciled target-user set.")
+    product["scope"]["out_of_scope"] = _dedupe_str_list(list((product.get("scope") or {}).get("out_of_scope") or []) + _infer_out_of_scope(grounded_text))
+    product["non_goals"] = _dedupe_str_list(list(product.get("non_goals") or []) + _infer_non_goals(grounded_text))
+    product["constraints"] = _dedupe_str_list(list(product.get("constraints") or []) + _infer_constraints(grounded_text))
+    product["success_criteria"] = _dedupe_str_list(list(product.get("success_criteria") or []) + _infer_success_criteria(grounded_text))
+    primary_workflows = list(workflows.get("primary_workflows") or [])
+    if not primary_workflows:
+        workflows["primary_workflows"] = _infer_primary_workflows(grounded_text, users)
+        if workflows["primary_workflows"]:
+            notes.append("Added compact primary workflows so sparse source docs still preserve trigger/steps/result shape.")
+    workflows["alternate_flows"] = list(workflows.get("alternate_flows") or [])
+    if not workflows["alternate_flows"]:
+        workflows["alternate_flows"] = _infer_alternate_flows(grounded_text, users)
+    workflows["edge_cases"] = _dedupe_str_list(list(workflows.get("edge_cases") or []) + _infer_edge_cases(grounded_text))
+    workflow_assumptions = _dedupe_str_list(list(workflows.get("workflow_assumptions") or []))
+    if not workflow_assumptions and workflows["primary_workflows"] and _contains_any(grounded_text, ("task", "assign", "workflow", "queue")):
+        workflow_assumptions.append("The initial workflow model assumes one primary work-capture path with only the most likely operational branches filled in.")
+        _record_assumption(assumptions=assumptions, doc_path="ai_docs/context/source_docs/user_workflows.json", section_key="workflow_assumptions", topic_key="default_primary_workflow", current_value=workflow_assumptions[0], reasoning="Sparse intake still implies at least one end-to-end operational path.", source="grounded_inference", message_id=str(payload["message_id"]))
+    if workflows["alternate_flows"] and workflow_assumptions and len(workflow_assumptions) == 1:
+        workflow_assumptions.append("Alternate flows stay limited to reassignment and overdue handling until more workflow policy is known.")
+        _record_assumption(assumptions=assumptions, doc_path="ai_docs/context/source_docs/user_workflows.json", section_key="workflow_assumptions", topic_key="sparse_workflow_policy", current_value="Alternate flows are limited to reassignment and overdue handling until clarified.", reasoning="The request implies task operations but not a full exception catalog.", source="grounded_inference", message_id=str(payload["message_id"]))
+    workflows["workflow_assumptions"] = workflow_assumptions
+    inferred_entities, inferred_relationships, inferred_ownership = _infer_entity_bundle(grounded_text, users)
+    entities_were_sparse = not bool(list(entities.get("entities") or []))
+    if entities_were_sparse:
+        entities["entities"] = inferred_entities
+        if inferred_entities:
+            notes.append("Inferred compact domain entities from sparse workflow verbs and actor roles.")
+    if not entities.get("relationships"):
+        entities["relationships"] = inferred_relationships
+        if inferred_relationships:
+            notes.append("Added entity relationships needed to keep workflows and architecture grounding coherent.")
+    entities["ownership_assumptions"] = _dedupe_str_list(list(entities.get("ownership_assumptions") or []) + inferred_ownership)
+    if inferred_entities and entities_were_sparse:
+        _record_assumption(assumptions=assumptions, doc_path="ai_docs/context/source_docs/domain_entities.json", section_key="ownership_assumptions", topic_key="entity_authority", current_value=entities["ownership_assumptions"][0] if entities["ownership_assumptions"] else "One internal team maintains task and assignment state until record authority is clarified.", reasoning="Sparse intake implies ownership for task and assignment data, but not the final authority model.", source="grounded_inference", message_id=str(payload["message_id"]))
+    return docs, assumptions, notes
+
+
+def _heuristic_section_payloads(*, grounded_text: str, docs: dict[str, dict[str, Any]], assumptions: list[dict[str, Any]], payload: dict[str, Any], requested_mode: str, effective_mode: str) -> dict[str, SourceDocSectionArtifact]:
+    base_product = dict(docs["product_brief.json"])
+    base_workflows = dict(docs["user_workflows.json"])
+    base_entities = dict(docs["domain_entities.json"])
+    product_assumptions = _dedupe_str_list(list(base_product.get("assumptions") or []))
+    workflow_assumptions = _dedupe_str_list(list(base_workflows.get("workflow_assumptions") or []))
+    ownership_assumptions = _dedupe_str_list(list(base_entities.get("ownership_assumptions") or []))
+    if effective_mode != "scaffold_only":
+        sufficient_idea = extract_sufficient_idea(grounded_text)
+        users = _dedupe_str_list(list(base_product.get("target_users") or []) + list(sufficient_idea.get("target_users") or []) + _infer_users(grounded_text))
+        product_summary = _derive_product_summary(grounded_text, sufficient_idea)
+        if product_summary:
+            base_product["product_summary"] = product_summary
+        problem = str(sufficient_idea.get("problem") or _infer_problem(grounded_text) or base_product.get("problem_statement") or "").strip()
+        if problem:
+            base_product["problem_statement"] = problem
+        elif requested_mode == "ideation_mutation":
+            inferred_problem = "The team is handling work through an unclear or manual process, making ownership and progress hard to track."
+            base_product["problem_statement"] = inferred_problem
+            product_assumptions.append("The current workflow likely relies on manual tracking or fragmented tools.")
+            _record_assumption(assumptions=assumptions, doc_path="ai_docs/context/source_docs/product_brief.json", section_key="problem_statement", topic_key="primary_problem", current_value=inferred_problem, reasoning="The intake asks for software support but does not spell out the current-state pain in detail.", source="grounded_inference", message_id=str(payload["message_id"]))
+        base_product["target_users"] = users
+        base_workflows["actors"] = _dedupe_str_list(list(base_workflows.get("actors") or []) + users)
+        goals = _dedupe_str_list(list(base_product.get("goals") or []) + [sufficient_idea.get("goal") or _infer_goal(grounded_text)])
+        if not goals and requested_mode == "ideation_mutation" and _contains_any(grounded_text, ("task", "assign", "workflow", "queue", "dashboard")):
+            goals = ["Create a lightweight shared workflow so the team can capture, assign, and complete work reliably."]
+            product_assumptions.append("The first release should improve day-to-day operational visibility more than advanced analytics.")
+            _record_assumption(assumptions=assumptions, doc_path="ai_docs/context/source_docs/product_brief.json", section_key="goals", topic_key="primary_goal", current_value=goals[0], reasoning="Sparse software requests still imply an operational outcome even when the target metric is unstated.", source="grounded_inference", message_id=str(payload["message_id"]))
+        base_product["goals"] = goals
+        scope = dict(base_product.get("scope") or {"in_scope": [], "out_of_scope": []})
+        scope["in_scope"] = _dedupe_str_list(list(scope.get("in_scope") or []) + list(sufficient_idea.get("scope") or []) + _infer_scope_bullets(grounded_text))
+        base_product["scope"] = scope
+        if requested_mode == "ideation_mutation":
+            if not users:
+                _record_assumption(assumptions=assumptions, doc_path="ai_docs/context/source_docs/product_brief.json", section_key="target_users", topic_key="primary_users", current_value=["internal operators"], reasoning="Software-delivery intake typically targets an operator or requester cohort even when the exact role is missing.", source="grounded_inference", message_id=str(payload["message_id"]))
+                product_assumptions.append("Primary users are likely internal operators until clarified.")
+            if not scope["in_scope"]:
+                _record_assumption(assumptions=assumptions, doc_path="ai_docs/context/source_docs/product_brief.json", section_key="scope", topic_key="initial_scope", current_value=["first build should focus on the smallest workflow that resolves the request"], reasoning="The message asks for software work but does not yet define a narrow first release scope.", source="grounded_inference", message_id=str(payload["message_id"]))
+                product_assumptions.append("Initial scope should stay tightly limited until the first release boundaries are confirmed.")
+        base_product["scope"]["out_of_scope"] = _dedupe_str_list(list(scope.get("out_of_scope") or []) + _infer_out_of_scope(grounded_text))
+        base_product["non_goals"] = _dedupe_str_list(list(base_product.get("non_goals") or []) + _infer_non_goals(grounded_text))
+        base_product["constraints"] = _dedupe_str_list(list(base_product.get("constraints") or []) + list(sufficient_idea.get("constraints") or []) + _infer_constraints(grounded_text))
+        base_product["success_criteria"] = _dedupe_str_list(list(base_product.get("success_criteria") or []) + list(sufficient_idea.get("acceptance_criteria") or []) + _infer_success_criteria(grounded_text))
+        base_product["assumptions"] = _dedupe_str_list(product_assumptions)
+
+        inferred_primary_workflows = _infer_primary_workflows(grounded_text, users)
+        inferred_alternates = _infer_alternate_flows(grounded_text, users)
+        had_primary_workflows = bool(list(base_workflows.get("primary_workflows") or []))
+        base_workflows["primary_workflows"] = list(base_workflows.get("primary_workflows") or []) or inferred_primary_workflows
+        base_workflows["alternate_flows"] = list(base_workflows.get("alternate_flows") or []) or inferred_alternates
+        base_workflows["edge_cases"] = _dedupe_str_list(list(base_workflows.get("edge_cases") or []) + _infer_edge_cases(grounded_text))
+        if (not had_primary_workflows) and inferred_primary_workflows and not workflow_assumptions and requested_mode == "ideation_mutation":
+            workflow_assumptions.append("The first release centers on one capture-and-assignment workflow with only the most important exception paths filled in.")
+            _record_assumption(assumptions=assumptions, doc_path="ai_docs/context/source_docs/user_workflows.json", section_key="workflow_assumptions", topic_key="sparse_workflow_model", current_value=workflow_assumptions[0], reasoning="Sparse intake names the problem shape but not the complete operating playbook.", source="grounded_inference", message_id=str(payload["message_id"]))
+        base_workflows["workflow_assumptions"] = _dedupe_str_list(workflow_assumptions)
+
+        inferred_entities, inferred_relationships, inferred_ownership = _infer_entity_bundle(grounded_text, users)
+        base_entities["entities"] = list(base_entities.get("entities") or []) or inferred_entities
+        base_entities["relationships"] = list(base_entities.get("relationships") or []) or inferred_relationships
+        ownership_assumptions = _dedupe_str_list(ownership_assumptions + inferred_ownership)
+        base_entities["ownership_assumptions"] = ownership_assumptions
+        if inferred_entities and requested_mode == "ideation_mutation":
+            _record_assumption(assumptions=assumptions, doc_path="ai_docs/context/source_docs/domain_entities.json", section_key="ownership_assumptions", topic_key="entity_authority", current_value=ownership_assumptions[0] if ownership_assumptions else "One internal team maintains task and assignment state until record authority is clarified.", reasoning="Sparse intake implies a compact operating model but does not define final data authority boundaries.", source="grounded_inference", message_id=str(payload["message_id"]))
+    return {
+        "product_brief": SourceDocSectionArtifact(section_payload=base_product, explicit_facts=[f for f in [base_product.get("product_summary"), base_product.get("problem_statement")] if f], assumed_facts=list(base_product.get("assumptions") or []), rationale=["Populate the product brief to a canonically sufficient planning shape even when intake is sparse."], confidence_notes=["Sparse-input heuristics keep the brief compact and assumption-aware rather than pseudo-PRD level."], mode="heuristic"),
+        "user_workflows": SourceDocSectionArtifact(section_payload=base_workflows, explicit_facts=list(base_workflows.get("actors") or []), assumed_facts=list(base_workflows.get("workflow_assumptions") or []), rationale=["Preserve at least one end-to-end workflow shape so downstream PRD and UX docs have grounded flow structure."], confidence_notes=["Workflow depth is intentionally compact and should not expand into full story decomposition here."], mode="heuristic"),
+        "domain_entities": SourceDocSectionArtifact(section_payload=base_entities, explicit_facts=[str(item.get("label") or item.get("entity_key") or "") for item in list(base_entities.get("entities") or []) if isinstance(item, dict)], assumed_facts=list(base_entities.get("ownership_assumptions") or []), rationale=["Infer only the minimum business objects and relationships required to keep sparse workflows coherent."], confidence_notes=["Entity inference stays compact and avoids turning source docs into pseudo-architecture documents."], mode="heuristic"),
+    }
+
+
+def _run_source_doc_agent(*, repo_root: Path, node_name: str, stage_name: str, output_model: type[BaseModel], context_payload: dict[str, Any], guidance: list[str], fallback: BaseModel, runtime_mode: str, task_context: TaskContext) -> tuple[BaseModel, str]:
+    if runtime_mode == "stub":
+        _record_agent_run(task_context=task_context, node_name=node_name, stage_name=stage_name, runtime_mode=runtime_mode, response_mode="test_stub", response=fallback.model_dump() if hasattr(fallback, "model_dump") else None)
+        return fallback, "test_stub"
+    model, envelope = run_agent_step(repo_root=repo_root, stage_name=f"source_doc_mutation_{stage_name}", output_model=output_model, context_payload=context_payload, guidance=guidance)
+    _record_agent_run(task_context=task_context, node_name=node_name, stage_name=stage_name, runtime_mode=runtime_mode, response_mode="agent", prompt=envelope.prompt, response=envelope.response, raw_stdout=envelope.raw_stdout, raw_stderr=envelope.raw_stderr)
+    return model, "agent"
+
+
+def _normalize_text_tokens(text: str) -> list[str]:
+    return re.findall(r"[a-z0-9_]+", text.lower())
+
+
+_STOPWORDS = {
+    "the", "and", "for", "with", "that", "this", "from", "into", "your", "their", "then", "than", "when", "where", "while", "must", "should", "would", "could", "have", "has", "had", "was", "were", "are", "our", "out", "use", "using", "used", "one", "two", "three", "same", "each", "only", "also", "does", "did", "done", "not", "but", "can", "all", "any", "per", "via", "its", "it's", "it", "a", "an", "of", "to", "in", "on", "by", "or", "as", "at", "be", "is",
+}
+
+
+def _content_keyword_set(value: Any) -> set[str]:
+    if isinstance(value, dict):
+        out: set[str] = set()
+        for key, item in value.items():
+            out.update(_content_keyword_set(key))
+            out.update(_content_keyword_set(item))
+        return out
+    if isinstance(value, list):
+        out: set[str] = set()
+        for item in value:
+            out.update(_content_keyword_set(item))
+        return out
+    if not isinstance(value, str):
+        return set()
+    return {token for token in _normalize_text_tokens(value) if len(token) >= 4 and token not in _STOPWORDS}
+
+
+def _project_doc_grounding_issues(*, project_doc_name: str, content: str, target_payload: dict[str, Any]) -> list[str]:
+    if project_doc_name != "prd.md":
+        return []
+    canonical_source_docs = dict(target_payload.get("canonical_source_docs") or {})
+    existing_project_doc = dict(target_payload.get("existing_project_doc") or {})
+    output_keywords = _content_keyword_set(content)
+    source_keywords = _content_keyword_set(canonical_source_docs)
+    baseline_keywords = _content_keyword_set(str(existing_project_doc.get("content") or ""))
+    actor_keywords = _content_keyword_set((canonical_source_docs.get("user_workflows.json") or {}).get("actors") or [])
+    entity_keywords = _content_keyword_set((canonical_source_docs.get("domain_entities.json") or {}).get("entities") or [])
+    workflow_keywords = _content_keyword_set((canonical_source_docs.get("user_workflows.json") or {}).get("primary_workflows") or [])
+    required_keywords = {token for token in actor_keywords | entity_keywords | workflow_keywords if len(token) >= 4}
+    issues: list[str] = []
+    if required_keywords and not (output_keywords & required_keywords):
+        issues.append("PRD lost all grounded actor/entity/workflow anchors from the canonical source docs.")
+    baseline_anchor_keywords = {token for token in baseline_keywords if token in source_keywords and len(token) >= 4}
+    if baseline_anchor_keywords and len(output_keywords & baseline_anchor_keywords) < min(3, len(baseline_anchor_keywords)):
+        issues.append("PRD does not preserve enough baseline product identity anchors from the existing PRD/source-doc overlap.")
+    product_summary_keywords = _content_keyword_set(str((canonical_source_docs.get("product_brief.json") or {}).get("product_summary") or ""))
+    if product_summary_keywords and not (output_keywords & product_summary_keywords):
+        issues.append("PRD is not recognizably grounded in the current product summary.")
+    return issues
+
+
+def _run_project_doc_subagent_cli(*, repo_root: str, output_path: str, project_doc_name: str, target_payload: dict[str, Any], shell_only: bool, runtime_mode: str) -> None:
+    path = Path(output_path)
+    canonical_source_docs = dict(target_payload.get("canonical_source_docs") or {})
+    supporting_source_docs = list(target_payload.get("supporting_source_docs") or [])
+    primary_source_docs = list(target_payload.get("primary_source_docs") or [])
+    reference_docs = dict(target_payload.get("reference_docs") or {})
+    direct_impacts = list(target_payload.get("directly_impacted_by_changed_docs") or [])
+    existing_project_doc = dict(target_payload.get("existing_project_doc") or {})
+    if runtime_mode == "stub":
+        rendered = "\n".join([
+            f"# {project_doc_name.replace('_', ' ').replace('.md', '').title()}",
+            "",
+            f"Grounded in: {', '.join(supporting_source_docs) or 'none'}.",
+            f"Primary sources: {', '.join(primary_source_docs) or 'none'}.",
+            f"Direct impacts: {', '.join(direct_impacts) or 'none'}.",
+            f"Existing baseline doc loaded: {'yes' if existing_project_doc.get('loaded') else 'no'}.",
+            "",
+            "## Grounding Notes",
+            "",
+            "- Project-doc richness and cross-reference contracts were supplied.",
+            "- This stub output stays thin by design; richer prose requires the real agent runtime.",
+            "",
+            "## Canonical Source Snapshot",
+            "",
+            "```json",
+            json.dumps(canonical_source_docs, indent=2, sort_keys=True),
+            "```",
+            "",
+        ])
+        _write_json(path, {"project_doc_name": project_doc_name, "status": "completed", "mode": "test_stub_subagent", "runtime_mode": runtime_mode, "content": rendered, "source_doc_dependencies": supporting_source_docs, "primary_source_docs": primary_source_docs, "impact_rationale": direct_impacts, "reference_docs_supplied": {key: value.get('path') for key, value in reference_docs.items() if isinstance(value, dict)}, "confidence_notes": ["Stub runtime cannot demonstrate full richness/depth."]})
+        return
+    class _ProjectDocArtifact(BaseModel):
+        content: str
+        source_doc_dependencies: list[str] = []
+        assumptions_used: list[str] = []
+        impact_rationale: list[str] = []
+        confidence_notes: list[str] = []
+
+    base_guidance = load_agentic_prompt_lines("source_doc_mutation_project_doc_render")
+    attempts: list[dict[str, Any]] = []
+    last_model = None
+    last_envelope = None
+    for attempt in range(2):
+        guidance = list(base_guidance)
+        if attempt == 1 and attempts:
+            guidance.append("Your previous draft failed grounding validation. Repair it instead of changing products.")
+            guidance.extend([f"Validation failure: {issue}" for issue in attempts[-1].get("issues") or []])
+        model, envelope = run_agent_step(repo_root=Path(repo_root), stage_name=f"project_doc_mutation_{project_doc_name.replace('.', '_')}", output_model=_ProjectDocArtifact, context_payload={"project_doc_name": project_doc_name, "target_payload": target_payload, "shell_only": shell_only}, guidance=guidance)
+        issues = _project_doc_grounding_issues(project_doc_name=project_doc_name, content=model.content, target_payload=target_payload)
+        attempts.append({"attempt": attempt + 1, "issues": issues, "prompt": envelope.prompt, "response": envelope.response})
+        last_model = model
+        last_envelope = envelope
+        if not issues:
+            break
+    final_issues = _project_doc_grounding_issues(project_doc_name=project_doc_name, content=last_model.content if last_model else "", target_payload=target_payload)
+    status = "completed" if not final_issues else "failed_validation"
+    _write_json(path, {"project_doc_name": project_doc_name, "status": status, "mode": "agent_subprocess", "runtime_mode": runtime_mode, "content": last_model.content if last_model else "", "source_doc_dependencies": last_model.source_doc_dependencies if last_model else [], "assumptions_used": last_model.assumptions_used if last_model else [], "impact_rationale": last_model.impact_rationale if last_model else [], "confidence_notes": (last_model.confidence_notes if last_model else []) + ([f"Grounding validation failed: {issue}" for issue in final_issues] if final_issues else []), "primary_source_docs": primary_source_docs, "reference_docs_supplied": {key: value.get('path') for key, value in reference_docs.items() if isinstance(value, dict)}, "existing_project_doc_supplied": bool(existing_project_doc.get("loaded")), "validation_issues": final_issues, "attempts": attempts, "prompt": last_envelope.prompt if last_envelope else {}, "response": last_envelope.response if last_envelope else {}, "raw_stdout": last_envelope.raw_stdout if last_envelope else "", "raw_stderr": last_envelope.raw_stderr if last_envelope else ""})
+
+
+class NormalizeAndGatherSupportContextNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        payload = build_source_doc_mutation_request(project_id=str(task_context.event.project_id or ""), idea_id=str(task_context.event.idea_id or ""), repo_root=Path(str(task_context.event.repo_root or "")), raw_text=str(task_context.event.raw_text or ""), grounded_raw_text=str(task_context.event.grounded_raw_text or task_context.event.raw_text or ""), mode=str(task_context.event.mode or "").strip() or None, history_grounding_ref=task_context.event.history_grounding_ref, existing_source_doc_refs=list(task_context.event.existing_source_doc_refs or []), explicit_source_doc_payload=task_context.event.explicit_source_doc_payload, message_id=task_context.event.message_id, session_id=task_context.event.session_id, invoked_from=str(task_context.event.invoked_from or "idea_context_resolution"), pipeline_key=task_context.event.pipeline_key)
+        repo_root = Path(payload["repo_root"]).expanduser().resolve()
+        pipeline_key = str(payload["pipeline_key"])
+        pipeline_dir = _pipeline_root(repo_root, idea_id=str(payload["idea_id"]), pipeline_key=pipeline_key)
+        pipeline_dir.mkdir(parents=True, exist_ok=True)
+        run_id = f"{DAG_ID}:{pipeline_key}"
+        docs = _load_source_doc_state(repo_root)
+        source_docs_before = _clone(docs)
+        registry_before = [item for item in list((docs.get("assumptions_registry.json") or {}).get("assumptions") or []) if isinstance(item, dict)]
+        repo_inventory = _repo_bootstrap_inventory(repo_root)
+        requested_mode = str(payload.get("mode") or "ideation_mutation")
+        agent_runtime_mode = _resolve_agent_runtime_mode(payload)
+        grounded_text = str(payload.get("grounded_raw_text") or payload.get("raw_text") or "")
+        repo_grounding_text, repo_grounding_refs = ("", [])
+        effective_mode = requested_mode
+        trust_level = "source_docs_mutated"
+        mutation_origin = "message_grounded"
+        plan_notes: list[str] = []
+        shell_only = False
+        if requested_mode == "repo_bootstrap":
+            repo_grounding_text, repo_grounding_refs = _pick_repo_grounding_text(repo_root)
+            if repo_inventory["has_genuine_signal"] and repo_grounding_text:
+                grounded_text = repo_grounding_text
+                mutation_origin = "repo_grounded_bootstrap"
+                plan_notes.append("Repo evidence cleared bootstrap threshold; grounding source docs from repo files.")
+            else:
+                effective_mode = "scaffold_only"
+                trust_level = "no_source_doc_changes"
+                mutation_origin = "scaffold_only_fallback"
+                shell_only = True
+                plan_notes.append("Repo evidence too sparse for grounded bootstrap; emitting scaffold-only docs and derived shells.")
+        inventory = {"requested_mode": requested_mode, "repo_root": str(repo_root), "canonical_source_docs_root": str(_source_docs_dir(repo_root)), "derived_project_docs_root": str(_v2_project_docs_dir(repo_root)), "existing_source_doc_refs": list(payload.get("existing_source_doc_refs") or []), "source_docs_before": source_docs_before, "preexisting_nonempty_docs": sorted([name for name, doc in source_docs_before.items() if isinstance(doc, dict) and any(_has_meaningful_value(v) for v in doc.values())]), "repo_inventory": repo_inventory}
+        changed_docs: list[str] = []
+        _apply_explicit_source_doc_payload(docs=docs, explicit_payload=payload.get("explicit_source_doc_payload") if isinstance(payload.get("explicit_source_doc_payload"), dict) else {}, changed_docs=changed_docs)
+        project_doc_reference_payload = _project_doc_reference_payload(repo_root)
+        support_indexes = _support_indexes_payload(repo_root)
+        _write_json(pipeline_dir / "source_doc_mutation_request.json", payload)
+        task_context.metadata.update({"payload": payload, "repo_root": repo_root, "pipeline_key": pipeline_key, "pipeline_dir": pipeline_dir, "run_id": run_id, "docs": docs, "source_docs_before": source_docs_before, "registry_before": registry_before, "assumptions": [item for item in registry_before if isinstance(item, dict)], "changed_docs": changed_docs, "inventory": inventory, "repo_inventory": repo_inventory, "requested_mode": requested_mode, "agent_runtime_mode": agent_runtime_mode, "grounded_text": grounded_text, "raw_text": str(payload.get("raw_text") or ""), "effective_mode": effective_mode, "repo_grounding_refs": repo_grounding_refs, "trust_level": trust_level, "plan_notes": plan_notes, "mutation_origin": mutation_origin, "shell_only": shell_only, "agent_runs": [], "project_doc_reference_payload": project_doc_reference_payload, "support_indexes": support_indexes})
+        task_context.update_node(self.node_name, node_type="deterministic", run_id=run_id, effective_mode=effective_mode, agent_runtime_mode=agent_runtime_mode, pipeline_dir=str(pipeline_dir))
+        return task_context
+
+
+class ProductBriefSectionAgentNode(AgentNode):
+    def get_agent_config(self) -> AgentConfig:
+        return AgentConfig(instructions="Mutate the product brief section from grounded evidence.", output_type=SourceDocSectionArtifact)
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        repo_root = task_context.metadata["repo_root"]
+        fallback = _heuristic_section_payloads(grounded_text=task_context.metadata["grounded_text"], docs=_clone(task_context.metadata["docs"]), assumptions=list(task_context.metadata["assumptions"]), payload=task_context.metadata["payload"], requested_mode=task_context.metadata["requested_mode"], effective_mode=task_context.metadata["effective_mode"])["product_brief"]
+        artifact, mode = _run_source_doc_agent(repo_root=repo_root, node_name=self.node_name, stage_name="product_brief", output_model=SourceDocSectionArtifact, context_payload={"grounded_text": task_context.metadata["grounded_text"], "current_doc": task_context.metadata["docs"]["product_brief.json"], "deterministic_hint": fallback.model_dump()}, guidance=load_agentic_prompt_lines("source_doc_mutation_product_brief"), fallback=fallback, runtime_mode=task_context.metadata["agent_runtime_mode"], task_context=task_context)
+        task_context.metadata["product_brief_section"] = SourceDocSectionArtifact.model_validate(artifact.model_dump() if hasattr(artifact, 'model_dump') else artifact)
+        task_context.update_node(self.node_name, node_type="agentic", response_mode=mode)
+        return task_context
+
+
+class UserWorkflowsSectionAgentNode(AgentNode):
+    def get_agent_config(self) -> AgentConfig:
+        return AgentConfig(instructions="Mutate the user workflows section from grounded evidence.", output_type=SourceDocSectionArtifact)
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        repo_root = task_context.metadata["repo_root"]
+        fallback = _heuristic_section_payloads(grounded_text=task_context.metadata["grounded_text"], docs=_clone(task_context.metadata["docs"]), assumptions=list(task_context.metadata["assumptions"]), payload=task_context.metadata["payload"], requested_mode=task_context.metadata["requested_mode"], effective_mode=task_context.metadata["effective_mode"])["user_workflows"]
+        artifact, mode = _run_source_doc_agent(repo_root=repo_root, node_name=self.node_name, stage_name="user_workflows", output_model=SourceDocSectionArtifact, context_payload={"grounded_text": task_context.metadata["grounded_text"], "current_doc": task_context.metadata["docs"]["user_workflows.json"], "deterministic_hint": fallback.model_dump()}, guidance=load_agentic_prompt_lines("source_doc_mutation_user_workflows"), fallback=fallback, runtime_mode=task_context.metadata["agent_runtime_mode"], task_context=task_context)
+        task_context.metadata["user_workflows_section"] = SourceDocSectionArtifact.model_validate(artifact.model_dump() if hasattr(artifact, 'model_dump') else artifact)
+        task_context.update_node(self.node_name, node_type="agentic", response_mode=mode)
+        return task_context
+
+
+class DomainEntitiesSectionAgentNode(AgentNode):
+    def get_agent_config(self) -> AgentConfig:
+        return AgentConfig(instructions="Mutate the domain entities section from grounded evidence.", output_type=SourceDocSectionArtifact)
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        repo_root = task_context.metadata["repo_root"]
+        fallback = _heuristic_section_payloads(grounded_text=task_context.metadata["grounded_text"], docs=_clone(task_context.metadata["docs"]), assumptions=list(task_context.metadata["assumptions"]), payload=task_context.metadata["payload"], requested_mode=task_context.metadata["requested_mode"], effective_mode=task_context.metadata["effective_mode"])["domain_entities"]
+        artifact, mode = _run_source_doc_agent(repo_root=repo_root, node_name=self.node_name, stage_name="domain_entities", output_model=SourceDocSectionArtifact, context_payload={"grounded_text": task_context.metadata["grounded_text"], "current_doc": task_context.metadata["docs"]["domain_entities.json"], "deterministic_hint": fallback.model_dump()}, guidance=load_agentic_prompt_lines("source_doc_mutation_domain_entities"), fallback=fallback, runtime_mode=task_context.metadata["agent_runtime_mode"], task_context=task_context)
+        task_context.metadata["domain_entities_section"] = SourceDocSectionArtifact.model_validate(artifact.model_dump() if hasattr(artifact, 'model_dump') else artifact)
+        task_context.update_node(self.node_name, node_type="agentic", response_mode=mode)
+        return task_context
+
+
+class SourceSectionConcurrentNode(ConcurrentNode):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        await self.execute_nodes_concurrently(task_context)
+        task_context.update_node(self.node_name, node_type="concurrent", children=["ProductBriefSectionAgentNode", "UserWorkflowsSectionAgentNode", "DomainEntitiesSectionAgentNode"])
+        return task_context
+
+
+class SourceDocCoherenceNode(AgentNode):
+    def get_agent_config(self) -> AgentConfig:
+        return AgentConfig(instructions="Reconcile section outputs into a coherent source-doc set.", output_type=SourceDocCoherenceArtifact)
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        docs = task_context.metadata["docs"]
+        changed_docs = task_context.metadata["changed_docs"]
+        assumptions = list(task_context.metadata["assumptions"])
+        payload = task_context.metadata["payload"]
+        for key, doc_name in [("product_brief_section", "product_brief.json"), ("user_workflows_section", "user_workflows.json"), ("domain_entities_section", "domain_entities.json")]:
+            section = task_context.metadata[key]
+            if section.section_payload != docs[doc_name]:
+                docs[doc_name] = section.section_payload
+                _mark_changed(changed_docs, doc_name)
+            assumptions.extend([item for item in section.assumption_entries if isinstance(item, dict)])
+        if task_context.metadata["requested_mode"] == "ideation_mutation":
+            product = docs["product_brief.json"]
+            if not str(product.get("problem_statement") or "").strip():
+                _record_assumption(assumptions=assumptions, doc_path="ai_docs/context/source_docs/product_brief.json", section_key="problem_statement", topic_key="primary_problem", current_value="User needs a better software-supported workflow, but the exact pain point is still unconfirmed.", reasoning="The intake requests software work but does not yet name the concrete pain clearly.", source="grounded_inference", message_id=str(payload["message_id"]))
+            if not list((product.get("scope") or {}).get("in_scope") or []):
+                _record_assumption(assumptions=assumptions, doc_path="ai_docs/context/source_docs/product_brief.json", section_key="scope", topic_key="initial_scope", current_value=["first build should focus on the smallest workflow that resolves the request"], reasoning="The message asks for software work but does not yet define a narrow first release scope.", source="grounded_inference", message_id=str(payload["message_id"]))
+        docs["assumptions_registry.json"] = {"assumptions": assumptions}
+        coherence_fallback = SourceDocCoherenceArtifact(docs={name: _clone(docs[name]) for name in CANONICAL_SOURCE_DOCS}, assumptions=[item for item in assumptions if isinstance(item, dict)], notes=["Deterministic source-doc coherence reconciliation."], mode="heuristic")
+        coherence_artifact, mode = _run_source_doc_agent(repo_root=task_context.metadata["repo_root"], node_name=self.node_name, stage_name="source_doc_coherence", output_model=SourceDocCoherenceArtifact, context_payload={"grounded_text": task_context.metadata["grounded_text"], "docs": {name: docs[name] for name in CANONICAL_SOURCE_DOCS}, "assumptions": assumptions, "changed_docs": changed_docs}, guidance=load_agentic_prompt_lines("source_doc_mutation_source_doc_coherence"), fallback=coherence_fallback, runtime_mode=task_context.metadata["agent_runtime_mode"], task_context=task_context)
+        docs.update({name: value for name, value in coherence_artifact.docs.items() if name in CANONICAL_SOURCE_DOCS and isinstance(value, dict)})
+        docs["assumptions_registry.json"] = {"assumptions": [item for item in coherence_artifact.assumptions if isinstance(item, dict)]}
+        reconciled_registry, registry_changed = reconcile_assumptions_registry(registry_payload=docs["assumptions_registry.json"], source_docs_by_name=docs, changed_docs=changed_docs)
+        docs["assumptions_registry.json"] = reconciled_registry
+        task_context.metadata["assumptions"] = [item for item in list(reconciled_registry.get("assumptions") or []) if isinstance(item, dict)]
+        if registry_changed:
+            _mark_changed(changed_docs, "assumptions_registry.json")
+        task_context.update_node(self.node_name, node_type="agentic", response_mode=mode, changed_docs=list(changed_docs), assumptions_total=len(task_context.metadata["assumptions"]))
+        return task_context
+
+
+class SourceDocEnrichmentCoherenceNode(AgentNode):
+    def get_agent_config(self) -> AgentConfig:
+        return AgentConfig(instructions="Perform a final sparse-safe source-doc enrichment and coherence pass before project-doc sync.", output_type=SourceDocCoherenceArtifact)
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        docs = task_context.metadata["docs"]
+        assumptions = list(task_context.metadata["assumptions"])
+        changed_docs = task_context.metadata["changed_docs"]
+        enriched_docs, enriched_assumptions, enrichment_notes = _enrich_sparse_source_docs(grounded_text=task_context.metadata["grounded_text"], docs={name: _clone(docs[name]) for name in CANONICAL_SOURCE_DOCS}, assumptions=assumptions, payload=task_context.metadata["payload"], requested_mode=task_context.metadata["requested_mode"])
+        fallback = SourceDocCoherenceArtifact(docs=enriched_docs, assumptions=[item for item in enriched_assumptions if isinstance(item, dict)], notes=enrichment_notes + ["Deterministic pre-sync source-doc enrichment/coherence pass."], mode="heuristic")
+        artifact, mode = _run_source_doc_agent(repo_root=task_context.metadata["repo_root"], node_name=self.node_name, stage_name="source_doc_enrichment_coherence", output_model=SourceDocCoherenceArtifact, context_payload={"grounded_text": task_context.metadata["grounded_text"], "docs": {name: docs[name] for name in CANONICAL_SOURCE_DOCS}, "assumptions": assumptions, "support_indexes": task_context.metadata.get("support_indexes") or {}, "changed_docs": changed_docs}, guidance=load_agentic_prompt_lines("source_doc_mutation_source_doc_enrichment_coherence"), fallback=fallback, runtime_mode=task_context.metadata["agent_runtime_mode"], task_context=task_context)
+        notes = list(getattr(artifact, "notes", []) or [])
+        before_docs = {name: json.dumps(docs.get(name, {}), sort_keys=True) for name in CANONICAL_SOURCE_DOCS}
+        docs.update({name: value for name, value in artifact.docs.items() if name in CANONICAL_SOURCE_DOCS and isinstance(value, dict)})
+        docs["assumptions_registry.json"] = {"assumptions": [item for item in artifact.assumptions if isinstance(item, dict)]}
+        task_context.metadata["assumptions"] = [item for item in list(docs["assumptions_registry.json"].get("assumptions") or []) if isinstance(item, dict)]
+        for name in CANONICAL_SOURCE_DOCS:
+            if before_docs[name] != json.dumps(docs.get(name, {}), sort_keys=True):
+                _mark_changed(changed_docs, name)
+        task_context.metadata["source_doc_enrichment_notes"] = notes
+        task_context.update_node(self.node_name, node_type="agentic", response_mode=mode, notes=notes, changed_docs=list(changed_docs))
+        return task_context
+
+
+class PersistSourceDocsAndAssumptionsNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        repo_root = task_context.metadata["repo_root"]
+        docs = task_context.metadata["docs"]
+        changed_docs = task_context.metadata["changed_docs"]
+        source_docs_dir = _source_docs_dir(repo_root)
+        source_docs_dir.mkdir(parents=True, exist_ok=True)
+        docs_to_write = list(CANONICAL_SOURCE_DOCS) if task_context.metadata["shell_only"] else list(dict.fromkeys(changed_docs + ["assumptions_registry.json"]))
+        for name in docs_to_write:
+            _write_json(source_docs_dir / name, docs[name])
+        _mark_changed(changed_docs, "assumptions_registry.json")
+        assumptions_delta = _compute_assumptions_delta(task_context.metadata["registry_before"], task_context.metadata["assumptions"])
+        changed_sections = _compute_changed_sections(before_docs=task_context.metadata["source_docs_before"], after_docs=docs, changed_docs=changed_docs)
+        task_context.metadata.update({"source_docs_dir": source_docs_dir, "assumptions_delta": assumptions_delta, "changed_sections": changed_sections})
+        task_context.update_node(self.node_name, node_type="deterministic", docs_to_write=docs_to_write)
+        return task_context
+
+
+class ProjectDocImpactRoutingNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        changed_docs = list(task_context.metadata["changed_docs"])
+        changed_sections = list(task_context.metadata.get("changed_sections") or [])
+        support_indexes = task_context.metadata.get("support_indexes") or {}
+        routing_targets = _project_doc_target_payloads(repo_root=task_context.metadata["repo_root"], docs=task_context.metadata["docs"], changed_docs=changed_docs, changed_sections=changed_sections, support_indexes=support_indexes)
+        impacted = [item["project_doc_name"] for item in routing_targets if item["directly_impacted_by_changed_docs"]]
+        routing_payload = {
+            "classification": "support_docs",
+            "reference_map_doc": PROJECT_DOC_REFERENCE_DOCS["reference_map"],
+            "support_indexes": {name: {"path": value.get("path"), "classification": value.get("classification"), "loaded": value.get("loaded"), "contract": value.get("contract")} for name, value in (support_indexes.get("indexes") or {}).items()},
+            "changed_docs": changed_docs,
+            "changed_sections": changed_sections,
+            "project_doc_targets": [
+                {
+                    "project_doc_name": item["project_doc_name"],
+                    "primary_source_docs": item["primary_source_docs"],
+                    "supporting_source_docs": item["supporting_source_docs"],
+                    "directly_impacted_by_changed_docs": item["directly_impacted_by_changed_docs"],
+                    "routed_changed_sections": item["routed_changed_sections"],
+                }
+                for item in routing_targets
+            ],
+        }
+        task_context.metadata["project_doc_target_payloads"] = routing_targets
+        task_context.metadata["project_doc_impact_routing"] = routing_payload
+        task_context.metadata["impacted_project_docs"] = impacted
+        task_context.update_node(self.node_name, node_type="deterministic", impacted_project_docs=impacted, routing_targets=[item["project_doc_name"] for item in routing_targets])
+        return task_context
+
+
+class SpawnProjectDocMutationSubagentsNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        repo_root = task_context.metadata["repo_root"]
+        pipeline_dir = task_context.metadata["pipeline_dir"]
+        shell_only = task_context.metadata["shell_only"]
+        reference_payload = task_context.metadata.get("project_doc_reference_payload") or {}
+        subagents: list[dict[str, Any]] = []
+        for item in task_context.metadata.get("project_doc_target_payloads") or []:
+            md_name = item["project_doc_name"]
+            output_path = pipeline_dir / f"subagent_{md_name.replace('.', '_')}.json"
+            target_payload = dict(item)
+            target_payload["reference_docs"] = reference_payload
+            target_payload["support_indexes"] = task_context.metadata.get("support_indexes") or {}
+            cmd = [sys.executable, "-c", f"from devflow_engine.source_doc_mutation_dag import _run_project_doc_subagent_cli; _run_project_doc_subagent_cli(repo_root={str(repo_root)!r}, output_path={str(output_path)!r}, project_doc_name={md_name!r}, target_payload={target_payload!r}, shell_only={shell_only!r}, runtime_mode={task_context.metadata['agent_runtime_mode']!r})"]
+            proc = subprocess.Popen(cmd, cwd=str(repo_root))
+            subagents.append({"project_doc_name": md_name, "pid": proc.pid, "output_path": str(output_path), "primary_source_docs": item.get("primary_source_docs") or [], "supporting_source_docs": item.get("supporting_source_docs") or [], "directly_impacted_by_changed_docs": item.get("directly_impacted_by_changed_docs") or [], "reference_docs_supplied": [value.get("path") for value in reference_payload.values() if isinstance(value, dict) and value.get("path")]})
+        task_context.metadata["project_doc_subagents"] = subagents
+        task_context.update_node(self.node_name, node_type="deterministic", spawned_subagents=subagents)
+        return task_context
+
+
+class AwaitProjectDocMutationSubagentsNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        results: list[dict[str, Any]] = []
+        for item in task_context.metadata.get("project_doc_subagents") or []:
+            pid = int(item["pid"])
+            try:
+                os.waitpid(pid, 0)
+            except ChildProcessError:
+                pass
+            payload = _load_json_dict(Path(item["output_path"]), default={"project_doc_name": item["project_doc_name"], "status": "missing"})
+            results.append(payload)
+        task_context.metadata["project_doc_subagent_results"] = results
+        task_context.update_node(self.node_name, node_type="deterministic", awaited=len(results))
+        return task_context
+
+
+class ProjectDocCoherenceNode(AgentNode):
+    def get_agent_config(self) -> AgentConfig:
+        return AgentConfig(instructions="Review the full project-doc family for coherence against canonical source docs and project-doc support contracts.", output_type=ProjectDocCoherenceArtifact)
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        results = task_context.metadata.get("project_doc_subagent_results") or []
+        notes = [f"{item.get('project_doc_name')}: {item.get('mode')}" for item in results]
+        fallback = ProjectDocCoherenceArtifact(notes=notes + ["Fallback coherence output is thin; richer coherence findings require the real agent runtime."], mode="heuristic")
+        artifact, mode = _run_source_doc_agent(repo_root=task_context.metadata["repo_root"], node_name=self.node_name, stage_name="project_doc_coherence", output_model=ProjectDocCoherenceArtifact, context_payload={"canonical_source_docs": {name: task_context.metadata["docs"].get(name, {}) for name in CANONICAL_SOURCE_DOCS}, "project_doc_results": results, "project_doc_impact_routing": task_context.metadata.get("project_doc_impact_routing") or {}, "project_doc_reference_docs": task_context.metadata.get("project_doc_reference_payload") or {}}, guidance=load_agentic_prompt_lines("source_doc_mutation_project_doc_coherence"), fallback=fallback, runtime_mode=task_context.metadata["agent_runtime_mode"], task_context=task_context)
+        task_context.metadata["project_doc_coherence"] = artifact.model_dump() if hasattr(artifact, "model_dump") else artifact
+        task_context.update_node(self.node_name, node_type="agentic", response_mode=mode, notes=artifact.notes)
+        return task_context
+
+
+class PersistProjectDocsNode(Node):
+    async def process(self, task_context: TaskContext) -> TaskContext:
+        payload = task_context.metadata["payload"]
+        repo_root = task_context.metadata["repo_root"]
+        pipeline_dir = task_context.metadata["pipeline_dir"]
+        run_id = task_context.metadata["run_id"]
+        source_docs_dir = task_context.metadata["source_docs_dir"]
+        project_docs_root = _v2_project_docs_dir(repo_root) / "source_docs"
+        project_docs_root.mkdir(parents=True, exist_ok=True)
+        updated_outputs: list[str] = []
+        for item in task_context.metadata.get("project_doc_subagent_results") or []:
+            md_name = str(item.get("project_doc_name") or "")
+            if not md_name:
+                continue
+            path = project_docs_root / md_name
+            path.write_text(str(item.get("content") or _render_markdown(md_name.replace('.md', '.json'), task_context.metadata["docs"].get(md_name.replace('.md', '.json'), {}), shell_only=task_context.metadata["shell_only"])), encoding="utf-8")
+            updated_outputs.append(str(path.relative_to(repo_root)))
+        index_path = project_docs_root / "index.md"
+        index_intro = "Explicit project-doc subagent outputs derived from canonical source docs."
+        if task_context.metadata["shell_only"]:
+            index_intro = "This directory contains scaffold-only derived project doc shells. Repo evidence was too sparse to infer a grounded project shape."
+        index_lines = ["# Project Doc Family Index", "", index_intro, ""]
+        for md_name in PROJECT_DOC_TARGETS:
+            index_lines.append(f"- `source_docs/{md_name}`")
+        index_path.write_text("\n".join(index_lines) + "\n", encoding="utf-8")
+        updated_outputs.append(str(index_path.relative_to(repo_root)))
+        project_doc_sync_result = {"status": "completed", "derived_project_docs_root": str(_v2_project_docs_dir(repo_root)), "derived_source_doc_root": str(project_docs_root), "updated_outputs": updated_outputs, "changed_docs": task_context.metadata["changed_docs"], "impacted_project_docs": task_context.metadata.get("impacted_project_docs") or [], "sync_mode": "subagent_project_doc_render", "shell_only": task_context.metadata["shell_only"], "agent_runtime_mode": task_context.metadata["agent_runtime_mode"], "project_doc_coherence": task_context.metadata.get("project_doc_coherence") or {}, "source_doc_enrichment_notes": task_context.metadata.get("source_doc_enrichment_notes") or [], "project_doc_impact_routing": task_context.metadata.get("project_doc_impact_routing") or {}, "reference_docs_supplied": {key: value.get("path") for key, value in (task_context.metadata.get("project_doc_reference_payload") or {}).items() if isinstance(value, dict)}, "support_indexes": {name: {"path": value.get("path"), "classification": value.get("classification"), "loaded": value.get("loaded"), "contract": value.get("contract")} for name, value in ((task_context.metadata.get("support_indexes") or {}).get("indexes") or {}).items()}, "subagent_results": task_context.metadata.get("project_doc_subagent_results") or []}
+        assumptions = task_context.metadata["assumptions"]
+        changed_docs = task_context.metadata["changed_docs"]
+        mutation_plan = {"requested_mode": task_context.metadata["requested_mode"], "effective_mode": task_context.metadata["effective_mode"], "agent_runtime_mode": task_context.metadata["agent_runtime_mode"], "mutation_origin": task_context.metadata["mutation_origin"], "trust_level": task_context.metadata["trust_level"], "repo_grounding_refs": task_context.metadata["repo_grounding_refs"], "plan_notes": task_context.metadata["plan_notes"], "change_intent": {name: ("no_op_shell" if task_context.metadata["shell_only"] else "mutate" if name in changed_docs else "no_op") for name in CANONICAL_SOURCE_DOCS}, "decision_rule": task_context.metadata["repo_inventory"].get("decision_rule"), "project_doc_reference_docs": {key: value.get("path") for key, value in (task_context.metadata.get("project_doc_reference_payload") or {}).items() if isinstance(value, dict)}, "support_indexes": {name: value.get("path") for name, value in ((task_context.metadata.get("support_indexes") or {}).get("indexes") or {}).items()}, "project_doc_target_family": list(PROJECT_DOC_TARGETS), "project_doc_impact_routing": task_context.metadata.get("project_doc_impact_routing") or {}, "node_contracts": {"NormalizeAndGatherSupportContextNode": "deterministic request normalization, inventory, and support context assembly", "ProductBriefSectionAgentNode": "agentic source section mutation", "UserWorkflowsSectionAgentNode": "agentic source section mutation", "DomainEntitiesSectionAgentNode": "agentic source section mutation", "SourceDocCoherenceNode": "agentic coherence pass over section outputs", "SourceDocEnrichmentCoherenceNode": "agentic final sparse-safe source-doc enrichment/coherence pass before project-doc sync", "PersistSourceDocsAndAssumptionsNode": "deterministic canonical source-doc persistence", "ProjectDocImpactRoutingNode": "deterministic project-doc routing using source-to-project-doc reference contracts", "SpawnProjectDocMutationSubagentsNode": "deterministic orchestration that spawns project-doc mutation subagents with explicit reference-doc grounding", "AwaitProjectDocMutationSubagentsNode": "deterministic join waiting for all project-doc mutation subagents", "ProjectDocCoherenceNode": "agentic coherence pass over project-doc outputs using project-doc support contracts", "PersistProjectDocsNode": "deterministic artifact packaging and project-doc persistence"}}
+        source_doc_change_set = {"canonical_source_docs_root": str(source_docs_dir), "changed_docs": changed_docs, "before": {name: task_context.metadata["source_docs_before"].get(name, {}) for name in changed_docs}, "after": {name: task_context.metadata["docs"].get(name, {}) for name in changed_docs}, "requested_mode": task_context.metadata["requested_mode"], "effective_mode": task_context.metadata["effective_mode"], "agent_runtime_mode": task_context.metadata["agent_runtime_mode"], "mutation_mode": "agentic_scaffold_only" if task_context.metadata["shell_only"] else "agentic_source_doc_mutation", "source_doc_enrichment_notes": task_context.metadata.get("source_doc_enrichment_notes") or [], "repo_grounding_refs": task_context.metadata["repo_grounding_refs"], "changed_sections": task_context.metadata.get("changed_sections") or []}
+        result_payload = {"contract": DAG_ID, "run_id": run_id, "status": "completed", "artifact_root": str(pipeline_dir), "canonical_source_docs_root": str(source_docs_dir), "derived_project_docs_root": str(_v2_project_docs_dir(repo_root)), "result_artifact": "source_doc_mutation_result.json", "inventory_artifact": "source_doc_inventory.json", "plan_artifact": "source_doc_mutation_plan.json", "change_set_artifact": "source_doc_change_set.json", "assumptions_delta_artifact": "assumptions_delta.json", "project_doc_sync_artifact": "project_doc_sync_result.json", "agent_runs_artifact": "agent_runs.json", "changed_docs": changed_docs, "requested_mode": task_context.metadata["requested_mode"], "effective_mode": task_context.metadata["effective_mode"], "agent_runtime_mode": task_context.metadata["agent_runtime_mode"], "trust_level": task_context.metadata["trust_level"], "project_doc_target_family": list(PROJECT_DOC_TARGETS), "project_doc_reference_docs": {key: value.get("path") for key, value in (task_context.metadata.get("project_doc_reference_payload") or {}).items() if isinstance(value, dict)}, "support_indexes": {name: {"path": value.get("path"), "classification": value.get("classification"), "loaded": value.get("loaded"), "contract": value.get("contract")} for name, value in ((task_context.metadata.get("support_indexes") or {}).get("indexes") or {}).items()}, "assumption_status": {"open_count": len([item for item in assumptions if str(item.get("status") or "open") == "open"]), "total_count": len(assumptions)}, "dag_shape": {"workflow_schema": DAG_ID, "start_node": "NormalizeAndGatherSupportContextNode", "node_sequence": ["NormalizeAndGatherSupportContextNode", "SourceSectionConcurrentNode", "ProductBriefSectionAgentNode", "UserWorkflowsSectionAgentNode", "DomainEntitiesSectionAgentNode", "SourceDocCoherenceNode", "SourceDocEnrichmentCoherenceNode", "PersistSourceDocsAndAssumptionsNode", "ProjectDocImpactRoutingNode", "SpawnProjectDocMutationSubagentsNode", "AwaitProjectDocMutationSubagentsNode", "ProjectDocCoherenceNode", "PersistProjectDocsNode"], "deterministic_nodes": ["NormalizeAndGatherSupportContextNode", "PersistSourceDocsAndAssumptionsNode", "ProjectDocImpactRoutingNode", "SpawnProjectDocMutationSubagentsNode", "AwaitProjectDocMutationSubagentsNode", "PersistProjectDocsNode"], "agent_nodes": ["ProductBriefSectionAgentNode", "UserWorkflowsSectionAgentNode", "DomainEntitiesSectionAgentNode", "SourceDocCoherenceNode", "SourceDocEnrichmentCoherenceNode", "ProjectDocCoherenceNode"], "concurrent_section_nodes": ["ProductBriefSectionAgentNode", "UserWorkflowsSectionAgentNode", "DomainEntitiesSectionAgentNode"], "parallel_source_section_nodes": ["ProductBriefSectionAgentNode", "UserWorkflowsSectionAgentNode", "DomainEntitiesSectionAgentNode"], "project_doc_subagent_barrier": {"spawn_node": "SpawnProjectDocMutationSubagentsNode", "await_node": "AwaitProjectDocMutationSubagentsNode", "all_spawned_subagents_must_complete_before": "ProjectDocCoherenceNode"}, "future_agent_nodes": ["SourceDocSemanticMutationAgentNode"]}, "derivation": {"mutation_mode": "deterministic_scaffold_only" if task_context.metadata["shell_only"] else "deterministic_bootstrap_patch", "actual_runtime_mode": "agentic_scaffold_only" if task_context.metadata["shell_only"] else "agentic_source_doc_mutation", "writes_canonical_source_docs": True, "writes_derived_project_docs": True, "pretend_agentic": False, "repo_grounded": task_context.metadata["mutation_origin"] == "repo_grounded_bootstrap", "shell_only": task_context.metadata["shell_only"], "used_real_llm_runtime": task_context.metadata["agent_runtime_mode"] == "real" and not task_context.metadata["shell_only"]}, "repo_bootstrap_decision": {"requested_mode": task_context.metadata["requested_mode"], "effective_mode": task_context.metadata["effective_mode"], "repo_grounding_refs": task_context.metadata["repo_grounding_refs"], "signal_summary": task_context.metadata["repo_inventory"]}, "agent_runtime_summary": {"requested_mode": task_context.metadata["agent_runtime_mode"], "agent_run_count": len(task_context.metadata.get("agent_runs") or []), "response_modes": [item.get("response_mode") for item in task_context.metadata.get("agent_runs") or []]}, "gaps": ["SourceDocSemanticMutationAgentNode no longer owns the happy path; it has been replaced by explicit ProductBriefSectionAgentNode/UserWorkflowsSectionAgentNode/DomainEntitiesSectionAgentNode plus SourceDocCoherenceNode.", "Contradiction-specific routing/gates/artifacts are still not implemented in this DAG.", "planning summary/open questions/scope readiness artifacts are still not emitted by this DAG.", "Project-doc richness still depends on upstream source-doc breadth and the real LLM runtime; stub runs remain intentionally thin."]}
+        _write_json(pipeline_dir / "source_doc_inventory.json", task_context.metadata["inventory"])
+        _write_json(pipeline_dir / "source_doc_mutation_plan.json", mutation_plan)
+        _write_json(pipeline_dir / "source_doc_change_set.json", source_doc_change_set)
+        _write_json(pipeline_dir / "assumptions_delta.json", task_context.metadata["assumptions_delta"])
+        _write_json(pipeline_dir / "project_doc_sync_result.json", project_doc_sync_result)
+        _write_json(pipeline_dir / "agent_runs.json", {"agent_runtime_mode": task_context.metadata["agent_runtime_mode"], "runs": task_context.metadata.get("agent_runs") or []})
+        _write_json(pipeline_dir / "source_doc_mutation_result.json", result_payload)
+        mutation_ref = {"contract": "source_doc_mutation_dag.ref.v1", "dag_id": DAG_ID, "run_id": run_id, "status": result_payload["status"], "artifact_root": str(pipeline_dir), "result_artifact": result_payload["result_artifact"], "change_set_artifact": result_payload["change_set_artifact"], "assumptions_delta_artifact": result_payload["assumptions_delta_artifact"], "project_doc_sync_artifact": result_payload["project_doc_sync_artifact"], "agent_runs_artifact": result_payload["agent_runs_artifact"], "changed_docs": changed_docs, "trust_level": task_context.metadata["trust_level"], "agent_runtime_mode": task_context.metadata["agent_runtime_mode"]}
+        task_context.metadata["final_result"] = SourceDocMutationDagResult(run_id=run_id, pipeline_dir=pipeline_dir, mutation_ref=mutation_ref, result=result_payload)
+        task_context.update_node(self.node_name, node_type="deterministic", status="completed")
+        return task_context
+
+
+class SourceDocMutationDagWorkflow(Workflow):
+    workflow_schema = WorkflowSchema(description="Current source_doc_mutation_dag aligned to explicit source-section concurrency and project-doc subagent orchestration.", event_schema=SourceDocMutationDagEvent, start=NormalizeAndGatherSupportContextNode, nodes=[NodeConfig(node=NormalizeAndGatherSupportContextNode, connections=[SourceSectionConcurrentNode]), NodeConfig(node=SourceSectionConcurrentNode, connections=[SourceDocCoherenceNode], concurrent_nodes=[ProductBriefSectionAgentNode, UserWorkflowsSectionAgentNode, DomainEntitiesSectionAgentNode]), NodeConfig(node=SourceDocCoherenceNode, connections=[SourceDocEnrichmentCoherenceNode]), NodeConfig(node=SourceDocEnrichmentCoherenceNode, connections=[PersistSourceDocsAndAssumptionsNode]), NodeConfig(node=PersistSourceDocsAndAssumptionsNode, connections=[ProjectDocImpactRoutingNode]), NodeConfig(node=ProjectDocImpactRoutingNode, connections=[SpawnProjectDocMutationSubagentsNode]), NodeConfig(node=SpawnProjectDocMutationSubagentsNode, connections=[AwaitProjectDocMutationSubagentsNode]), NodeConfig(node=AwaitProjectDocMutationSubagentsNode, connections=[ProjectDocCoherenceNode]), NodeConfig(node=ProjectDocCoherenceNode, connections=[PersistProjectDocsNode]), NodeConfig(node=PersistProjectDocsNode, connections=[]), ])
+
+
+def run_source_doc_mutation_dag(*, request: dict[str, Any]) -> SourceDocMutationDagResult:
+    workflow = SourceDocMutationDagWorkflow()
+    task_context = workflow.run(request)
+    return task_context.metadata["final_result"]