rstillwell/Submatter
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions
Submatter/docs/examples/sop-published-flow.md
Randall Stillwell 6f139d6af2 feat(owner-cockpit): forge webhooks + artifacts + copilot (Epic 8/11/12) 
- Forge webhook POST /api/webhooks/forge HMAC sha256 verify, marker echodo-convoy → pr_review→merged as automation
- Completion artifacts table 0017, deterministic summary template, gallery /artifacts
- Ops copilot tRPC copilot + context tools (fleet, convoy, backlog) + panel + Draft Task → backlog.createTask
- Doc-writer SOPs: webhook rotation, copilot prompt, published flow examples
- Allow pr_review→merged as automation for webhook

Convoy: .convoys/owner-cockpit-v02

Co-authored-by: orchestrator
2026-08-25 17:49:38 -05:00

3.4 KiB
Raw Blame History

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:

    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