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

2026-05-22 01:44:41 +03:00
parent 95fec3ba26
commit 7667819c46
10 changed files with 732 additions and 20 deletions
@@ -0,0 +1,97 @@
+# Demo Stack Guide (Task 019)
+
+This guide runs a deterministic end-to-end demo from article brief to `PUBLISH_COMMIT_CREATED` with no external credentials.
+
+## 1. Setup
+
+From repository root:
+
+```sh
+docker compose up --build
+```
+
+The backend runs in demo mode in Compose:
+
+- `PIPELINE_DEMO_MODE=1`
+- local Git target: `/demo/pipeline-demo-site.git`
+- fake deterministic section runtime with one fail-then-retry branch
+- local infra only (Postgres/Redis/MinIO)
+
+No real Codex, search, WHOIS, cloud S3, or GitHub credentials are required.
+
+## 2. Role Selection
+
+The app uses demo users via backend header selection:
+
+- Editor flow (default): `editor@example.com`
+- Admin actions: `admin@example.com`
+
+For the article detail page, role hint query is available:
+
+- Editor: `/articles/<articleId>?role=editor`
+- Admin: `/articles/<articleId>?role=admin`
+
+## 3. Happy Path
+
+1. Open frontend: `http://localhost:3000`.
+2. Create article from dashboard (`New article`).
+3. Complete boundary questions and submit.
+4. Generate plan and approve.
+5. Start research and open evidence matrix.
+6. Start draft production.
+7. Open article detail:
+   - one section job is expected to fail (deterministic demo failure),
+   - retry it from Admin view.
+8. Assemble draft.
+9. Run SEO and language review, resolve suggestions.
+10. Generate assets, upload files, approve assets.
+11. Final approval with publishing settings.
+12. Run publishing dry run.
+13. Create publish commit.
+
+Expected final status: `PUBLISH_COMMIT_CREATED`.
+
+## 4. Failure Path (Visible)
+
+Demo mode always creates one deterministic failed section scaffold attempt on draft start:
+
+- `SECTION_SCAFFOLD` attempt 1 -> `FAILED`
+- retry from `/api/agent-jobs/{job_id}/retry` -> auto-completes `SUCCEEDED`
+
+This exposes failure/retry timeline behavior and retry policy UI controls.
+
+## 5. Artifact Inspection
+
+### Workflow timeline and job logs
+
+- Open article detail page.
+- Verify mixed timeline entries for user/system/agent events.
+- Admin sees detailed redacted `stdout/stderr`.
+- Editor sees safe failure summary only.
+
+### Object storage (research artifacts/manifests)
+
+In local integration-style runs with `OBJECT_STORAGE_LOCAL_ROOT`, artifacts are under:
+
+- `research/<article_id>/<run_id>/source-*/section.json`
+- `research/<article_id>/<run_id>/source-*/metadata.json`
+
+In Compose (MinIO), inspect bucket `${OBJECT_STORAGE_BUCKET:-pipeline-local}`.
+
+### Final Git commit payload
+
+The publish commit manifest contains:
+
+- `content.path` (markdown/mdx),
+- `frontmatter`,
+- `assets[*].target_path`.
+
+Inspect repo in Compose:
+
+```sh
+docker compose exec backend git --git-dir /demo/pipeline-demo-site.git log --oneline -n 5
+docker compose exec backend git --git-dir /demo/pipeline-demo-site.git show <commit_sha>:<content_path>
+```
+
+For local integration tests, repository path comes from
+`PIPELINE_DEMO_PUBLISH_REPO_PATH` (the smoke test sets a temp path).