content-factory/tasks/019-end-to-end-demo-stack.md

Task 019: End-To-End Demo Stack

Development description: Assemble and verify a complete demo-ready Docker Compose product path from article brief to Git-backed publish commit using deterministic runner/research/review fixtures and a local demo Next content repository.

Implementation Details

• Add demo fixtures:
  • Seed target site.
  • Demo Admin and Editor users.
  • Fake Codex runner outputs for questions, plan, sections, SEO, language, assets.
  • Fake research search/fetch corpus.
  • Local bare Git repository or mounted demo Next content repository as publish target.
• Add end-to-end test path:
  • Start stack.
  • Create article.
  • Generate/submit boundary answers.
  • Generate/approve plan.
  • Run research.
  • Verify evidence matrix.
  • Run production jobs.
  • Assemble draft.
  • Review assets, SEO, and language.
  • Final approve.
  • Dry run.
  • Create publish commit.
• Add demo documentation:
  • Setup.
  • Login/role selection.
  • Happy path.
  • Failure demo path.
  • How to inspect object storage, database state, and Git commit.

Public Interface

• A reviewer can run one command, open the frontend, and complete the pipeline without external credentials.
• The final demo produces a real Git commit in the configured demo repository.

Acceptance Criteria

• TDD pre-requirement: before implementation, write one failing end-to-end smoke test for the shortest happy path through public UI/API boundaries; add failure-path checks one behavior at a time and record evidence in Result.
• docker compose up --build starts the complete demo stack.
• Demo requires no real Codex, search, WHOIS, cloud S3, or GitHub credentials.
• Editor can complete the happy path from article brief to PUBLISH_COMMIT_CREATED.
• Final commit contains Markdown/MDX, frontmatter, and referenced assets according to site config.
• Object storage contains research source-section artifacts and manifests.
• Workflow timeline shows all major actions.
• Demo includes at least one visible failure/retry scenario.
• README/demo guide is accurate and enough for a new developer to run the product.

Verification

• Run the full end-to-end smoke suite.
• Run docker compose up --build from a clean checkout.
• Manually execute the documented demo path.
• Inspect final Git commit, object storage artifacts, and workflow history.

Result

• Status: Implemented and verified (GREEN).
• Delivered:
  1. Deterministic demo runtime (PIPELINE_DEMO_MODE) with local bare Git publish target bootstrap.
  2. Demo seed data now points to local repository path in demo mode.
  3. Deterministic section scaffold fail-once behavior with visible retry success path.
  4. End-to-end smoke test now covers full public happy path to PUBLISH_COMMIT_CREATED plus failure/retry.
  5. README + dedicated demo guide with setup, roles, happy/failure path, and artifact inspection.
• Red evidence (pre-requirement):
  • apps/backend/tests/integration/test_end_to_end_demo_stack_smoke_public_api.py initially failed during RED phase as documented above.
• Green evidence:
  • test_demo_happy_path_reaches_publish_commit_created_with_failure_retry is green and verifies:
    • article path from brief to publish commit,
    • deterministic failure (AGENT_JOB_FAILED) and retry (AGENT_JOB_RETRIED),
    • commit payload contains frontmatter/markdown and assets in target repository,
    • research manifests/artifacts exist in object storage,
    • timeline includes major workflow events through PUBLISH_COMMIT_CREATED.
• Refactor notes:
  • Introduced demo_runtime.py to isolate demo-only behavior and avoid scattering env checks.
  • Reused existing job completion pipeline (complete_agent_job) for demo auto-completion to preserve observability/audit behavior.
  • Fixed publish YAML template brace escaping in seed data.
• Verification output:
  • PYTHONPATH=/private/tmp/pupline-backend-deps python3 -m unittest apps/backend/tests/integration/test_end_to_end_demo_stack_smoke_public_api.py
    • Ran 1 test ... OK
  • PYTHONPATH=/private/tmp/pupline-backend-deps python3 -m unittest apps/backend/tests/integration/test_draft_assembly_public_api.py apps/backend/tests/integration/test_evidence_matrix_public_api.py apps/backend/tests/integration/test_publishing_git_flow_public_api.py apps/backend/tests/integration/test_final_approval_gate_public_api.py apps/backend/tests/integration/test_agent_job_queue_public_api.py apps/backend/tests/integration/test_parallel_production_public_api.py apps/backend/tests/integration/test_observability_retry_cancel_audit_public_api.py apps/backend/tests/integration/test_boundary_questions_public_api.py
    • Ran 37 tests ... OK
  • node apps/frontend/tests/article_detail.model.test.mjs
    • exit code 0
  • node apps/frontend/tests/admin_script_versions.model.test.mjs
    • exit code 0
  • node apps/frontend/tests/draft_editor.model.test.mjs
    • exit code 0
  • node apps/frontend/tests/final_approval.model.test.mjs
    • exit code 0
  • pnpm --dir apps/frontend typecheck
    • tsc --noEmit completed successfully
  • docker compose up --build -d
    • completed successfully; all services started.
  • docker compose ps
    • backend/frontend/runner/minio/postgres/redis are up (postgres/redis healthy).