feat(task-019): add deterministic end-to-end demo stack flow

apps/backend/src/application/agent_jobs.py

@@ -18,6 +18,10 @@ from src.domain.contracts import (
     Role,
 )
 from src.application.observability import evaluate_retry_policy, project_job_for_view
+from src.application.demo_runtime import (
+    build_demo_section_completion_payload,
+    should_auto_retry_section_job,
+)
 
 
 VALID_FAKE_AGENT_PROFILE = "fake-codex"
@@ -91,6 +95,21 @@ def retry_agent_job(
             "job_type": retry.job_type.value,
         },
     )
+    if should_auto_retry_section_job(retry):
+        completion = build_demo_section_completion_payload(
+            payload=retry.payload,
+            failed=False,
+        )
+        return complete_agent_job(
+            repository,
+            job_id=retry.id,
+            workspace_path=f"/tmp/demo/{retry.id}",
+            stdout="deterministic demo section retry succeeded\n",
+            stderr="",
+            exit_code=0,
+            duration_ms=8,
+            output=completion,
+        )
     return AgentJobResponse(job=_project_admin_view(repository, retry))
 
 

apps/backend/src/application/demo_runtime.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from src.domain.contracts import AgentJobSummary
+
+
+_DEMO_MODE_ENV = "PIPELINE_DEMO_MODE"
+_DEMO_REPOSITORY_ENV = "PIPELINE_DEMO_PUBLISH_REPO_PATH"
+_DEFAULT_DEMO_REPOSITORY_PATH = "/tmp/pipeline-demo-site.git"
+
+
+def is_demo_mode() -> bool:
+    value = os.environ.get(_DEMO_MODE_ENV, "").strip().lower()
+    return value in {"1", "true", "yes", "on"}
+
+
+def resolve_demo_repository_path() -> Path:
+    configured = os.environ.get(_DEMO_REPOSITORY_ENV, _DEFAULT_DEMO_REPOSITORY_PATH)
+    return Path(configured).expanduser().resolve()
+
+
+def ensure_demo_bare_repository(path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if not path.exists():
+        _run_git(["init", "--bare", str(path)])
+    if _has_main_branch(path):
+        return
+
+    with tempfile.TemporaryDirectory(prefix="demo-site-seed-") as temp_dir:
+        worktree = Path(temp_dir) / "seed"
+        worktree.mkdir(parents=True, exist_ok=True)
+        _run_git(["init"], cwd=worktree)
+        _run_git(["config", "user.name", "Pipeline Demo Bot"], cwd=worktree)
+        _run_git(["config", "user.email", "pipeline-demo-bot@example.com"], cwd=worktree)
+        (worktree / "README.md").write_text("# Pipeline Demo Site\n", encoding="utf-8")
+        _run_git(["add", "README.md"], cwd=worktree)
+        _run_git(["commit", "-m", "seed demo repository"], cwd=worktree)
+        _run_git(["branch", "-M", "main"], cwd=worktree)
+        _run_git(["remote", "add", "origin", str(path)], cwd=worktree)
+        _run_git(["push", "origin", "main"], cwd=worktree)
+
+
+def should_auto_run_section_jobs() -> bool:
+    return is_demo_mode()
+
+
+def should_auto_retry_section_job(job: AgentJobSummary) -> bool:
+    if not is_demo_mode():
+        return False
+    if job.payload.get("demo_fail_once") is True and job.attempt > 1:
+        return True
+    return False
+
+
+def build_demo_section_completion_payload(
+    *,
+    payload: dict[str, Any],
+    failed: bool,
+) -> dict[str, Any]:
+    heading = _string_value(payload.get("heading")) or "Section"
+    section_id = _string_value(payload.get("section_id")) or "section"
+    draft_markdown = (
+        f"## {heading}\n\n"
+        f"This demo section is generated deterministically for `{section_id}`.\n\n"
+        "Read the related architecture guide: [internal reference](/guides/pipeline-demo).\n"
+    )
+    if failed:
+        return {
+            "status": "FAILED",
+            "error_category": "CLI_EXIT_CODE_FAILURE",
+            "error_message": "Deterministic demo failure for retry walkthrough.",
+            "payload": {
+                "section_id": section_id,
+                "heading": heading,
+                "artifact_label": heading,
+                "last_successful_step": "outline generated",
+                "unsupported_claims": [],
+                "draft_markdown": "",
+            },
+        }
+
+    return {
+        "status": "SUCCEEDED",
+        "output_files": [{"path": f"outputs/{section_id}.md"}],
+        "payload": {
+            "section_id": section_id,
+            "heading": heading,
+            "artifact_label": heading,
+            "unsupported_claims": [],
+            "last_successful_step": "section scaffold complete",
+            "suggested_visuals": [f"{heading} diagram"],
+            "draft_markdown": draft_markdown,
+        },
+    }
+
+
+def slugify(value: str) -> str:
+    normalized = re.sub(r"[^a-zA-Z0-9]+", "-", value.strip().lower()).strip("-")
+    return normalized or "article"
+
+
+def _has_main_branch(path: Path) -> bool:
+    result = subprocess.run(
+        ["git", "--git-dir", str(path), "rev-parse", "--verify", "refs/heads/main"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return result.returncode == 0
+
+
+def _run_git(command: list[str], *, cwd: Path | None = None) -> None:
+    subprocess.run(
+        ["git", *command] if command[0] != "git" else command,
+        cwd=str(cwd) if cwd is not None else None,
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+
+
+def _string_value(value: Any) -> str:
+    if isinstance(value, str):
+        return value.strip()
+    return ""

apps/backend/src/application/evidence.py

@@ -3,6 +3,11 @@ from __future__ import annotations
 from datetime import UTC, datetime
 from uuid import UUID
 
+from src.application.agent_jobs import complete_agent_job
+from src.application.demo_runtime import (
+    build_demo_section_completion_payload,
+    should_auto_run_section_jobs,
+)
 from src.domain.contracts import (
     AgentJobListResponse,
     AgentJobStatus,
@@ -189,6 +194,7 @@ def start_draft(repository: object, *, article_id: UUID) -> AgentJobListResponse
     jobs = []
     for section in approved_plan.sections:
         used_evidence_ids = claim_evidence_by_section.get(str(section.id), [])
+        demo_fail_once = should_auto_run_section_jobs() and len(jobs) == 0
         jobs.append(
             repository.agent_jobs.create(
                 article_id=article_id,
@@ -212,11 +218,16 @@ def start_draft(repository: object, *, article_id: UUID) -> AgentJobListResponse
                     "unsupported_claims": [],
                     "suggested_visuals": [],
                     "draft_markdown": "",
+                    "demo_fail_once": demo_fail_once,
                 },
                 queued_at=now,
             )
         )
 
+    if should_auto_run_section_jobs():
+        _auto_complete_demo_section_jobs(repository, jobs)
+        jobs = repository.agent_jobs.list_for_article(article_id)
+
     return AgentJobListResponse(jobs=jobs)
 
 
@@ -313,3 +324,29 @@ def _insufficient_reasons(claims: list[object]) -> list[str]:
 
 def _now() -> datetime:
     return datetime.now(UTC)
+
+
+def _auto_complete_demo_section_jobs(
+    repository: object,
+    jobs: list[object],
+) -> None:
+    for index, job in enumerate(jobs):
+        failed = index == 0
+        output = build_demo_section_completion_payload(
+            payload=job.payload,
+            failed=failed,
+        )
+        complete_agent_job(
+            repository,
+            job_id=job.id,
+            workspace_path=f"/tmp/demo/{job.id}",
+            stdout=(
+                "deterministic demo failure; retry to continue\n"
+                if failed
+                else "deterministic demo section scaffold succeeded\n"
+            ),
+            stderr="" if not failed else "exit code 1 simulated\n",
+            exit_code=1 if failed else 0,
+            duration_ms=12,
+            output=output,
+        )

apps/backend/src/application/seed_data.py

@@ -4,6 +4,11 @@ from datetime import UTC, datetime
 from hashlib import sha256
 from uuid import NAMESPACE_URL, UUID, uuid5
 
+from src.application.demo_runtime import (
+    ensure_demo_bare_repository,
+    is_demo_mode,
+    resolve_demo_repository_path,
+)
 from src.domain.contracts import (
     PublishingRules,
     Role,
@@ -44,8 +49,9 @@ def seed_reference_data(repository: object) -> None:
         updated_at=SEED_TIMESTAMP,
     )
 
+    repository_url = _repository_url_for_seed()
     publishing_rules = PublishingRules(
-        repository_url="git@github.com:example/site.git",
+        repository_url=repository_url,
         production_branch="main",
         content_format="mdx",
         content_path_template="content/articles/{slug}.mdx",
@@ -85,15 +91,15 @@ def seed_reference_data(repository: object) -> None:
         updated_at=SEED_TIMESTAMP,
     )
 
-    publishing_yaml = """target: b2b_saas_blog
+    publishing_yaml = f"""target: b2b_saas_blog
 repository:
-  url: git@github.com:example/site.git
+  url: {repository_url}
   branch: main
 content:
   format: mdx
-  path_template: content/articles/{slug}.mdx
+  path_template: content/articles/{{slug}}.mdx
 assets:
-  path_template: public/articles/{slug}/{filename}
+  path_template: public/articles/{{slug}}/{{filename}}
 """
     transform_script = """export function transformArticle(article) {
   return {
@@ -121,6 +127,14 @@ assets:
     )
 
 
+def _repository_url_for_seed() -> str:
+    if not is_demo_mode():
+        return "git@github.com:example/site.git"
+    demo_repo_path = resolve_demo_repository_path()
+    ensure_demo_bare_repository(demo_repo_path)
+    return str(demo_repo_path)
+
+
 def _stable_uuid(value: str) -> UUID:
     return uuid5(NAMESPACE_URL, f"ai-content-pipeline:{value}")