56 lines
3.4 KiB
Markdown
56 lines
3.4 KiB
Markdown
|
# 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`
|