# SOP published flow — `Task-write-sop → doc_review → published → artifact gallery` e2e

Fixture for `role-doc-writer` via harness `doc-writer` (`apps/worker/src/harness.ts`, `packages/shared/src/convoy-lifecycle/state-machine.ts:9`).

## Objective

Standard path for a doc-only SOP: write markdown under `docs/`, pass `doc_review`, publish, and verify artifact gallery.

## Prerequisites

- Convoy in `ready` or `in_progress` with a doc brief (`role-doc-writer`).
- Workspace has `harness_providers alias: doc-writer` (`minimal`, `needsWorktree: false`, `allowedCommands: []`) and `role_model_routes role-doc-writer → qwen-coder` (local).
- `MARKDOWN_BACKLOG_WORKSPACE_ID` set if backlog import needed.

## Steps

1. **Claim** — orchestrator assigns `role-doc-writer`; worker resolves `doc-writer` harness (`needsWorktree: false` — no worktree under `/tmp/echodo-worker-worktrees`).
2. **Write** — worker tool loop uses only `read_file`, `grep`, `write_file` (no `run_command`). Write target is `docs/...` or SOP file:

   ```ts
   write_file({ path: "docs/operations/webhook-secret-rotation.md", content: "..." })
   ```

3. **Gate: `in_progress → doc_review`** — automation or `role-doc-writer` transitions via `transitionConvoy` (`packages/shared/src/convoy-lifecycle/state-machine.ts:104`). Mission Control shows `doc_review`.
4. **Gate: `doc_review → published`** — `human-gate-2` / `doc-approver` approves (`docs/convoy-lifecycle.md:27`, `state-machine.ts:104`). Event `status_change` with `actor: human-gate-2` or `doc-approver`.
5. **Gallery: `published → released` + artifact** — `convoys.complete` (`apps/web/server/routers/convoys.ts:467`) transitions `published → released` via `human-gate-3`, creates `completionArtifacts` row (`summaryMd` + optional `screenshotUrl`). Listed by `convoys.listArtifacts`.

## Verification

- [ ] Worker trace shows only `read_file`, `grep`, `write_file`; no `run_command` / `pnpm`.
- [ ] `convoy_events` contains `doc_review → published` by `human-gate-2` / `doc-approver`.
- [ ] File exists at `docs/...` with expected frontmatter/content.
- [ ] `convoys.listArtifacts` returns row with `summaryMd` and `screenshotUrl` (placeholder ok) and timeline events.

## Screenshots (placeholder)

Replace placeholders before marking `published → released` demo complete.

- `docs/examples/screenshots/sop-doc-review-gate.png` — Mission Control detail showing `doc_review` gate with Approve / Request changes.
- `docs/examples/screenshots/sop-published-badge.png` — Convoy kanban / detail showing `published` status.
- `docs/examples/screenshots/sop-artifact-gallery.png` — Gallery (`convoys.listArtifacts`) showing summary + screenshot.

> Capture via app at `/[workspaceSlug]/mission-control` and `/[workspaceSlug]/.../artifacts` or equivalent gallery route. Store originals at `docs/examples/screenshots/` (git-ignored if binary-heavy; link anyway).

## Counterparts

- Code flow mirror: `in_progress → pr_review → merged → released` via Forge webhook `POST /api/webhooks/forge` (`apps/web/app/api/webhooks/forge/route.ts`, `docs/operations/webhook-secret-rotation.md`).
- Template: `docs/templates/doc-sop.md`.
- Research fixture: `docs/examples/research-pipeline.md`.

## References

- Lifecycle: `docs/convoy-lifecycle.md`, `packages/shared/src/convoy-lifecycle/state-machine.ts`
- Worker doc harness: `docs/worker.md`, `apps/worker/src/harness.ts`
- Artifacts tRPC: `apps/web/server/routers/convoys.ts:complete`, `convoys.ts:listArtifacts`