Submatter/.convoys/worker-closeout-docwriter.md

name	classification	success_metric	skip	status	created	model_policy
worker-closeout-docwriter	server-only	Epic 7 closes — draft PR opens for code + doc_review→published for docs, operator notes work mid-build, doc-writer examples ship, live E2E checklist is runnable without Cursor	ia ux design a11y visual smoke	merged	2026-08-25	roles escalate_to role-conductor role-architect role-implementer role-doc-writer role-reviewer claude-planning claude-planning qwen-coder qwen-coder qwen-coder claude-planning

Worker closeout + doc writers — closing Epic 7 for second-brain v0.1

Why

Second-brain v0.1 shipped harness-agnostic, Plans tree, Fleet. Epic 7 remains in_progress per plans/Plan-automation-foundation/Epic-apps-worker-v1/Epic-apps-worker-v1.md:23 — tool loop + checkpoints are done, but no draft PR via forge adapter blocks Epic 8 dogfood, and live E2E Task-worker-live-e2e-dogfood.md needs operator proof. Doc writers were asked to be included — this convoy adds role-doc-writer for SOPs/book research pipelines (docs that use doc_review→published without worktree).

See docs/decisions/2026-08-25-second-brain-os-pivot.md.

Scope

1. Draft PR via forge Task-worker-draft-pr.md — push branch if needed, createPullRequest(draft) on GitHub/Forgejo from worktree, persist URL to convoy, skip for non-implementer roles, handle both pr_review and doc_review (doc tasks publish without PR but still log).
2. Operator notes mid-build Task-worker-operator-notes.md — convoy_operator_messages table (workspace-scoped, queued|direct), tRPC postOperatorNote/listOperatorNotes, worker poll between tool rounds, Mission control chat thread for in_progress convoys.
3. Doc-writer examples — role-doc-writer routed via harness (uses doc-writer harness needsWorktree:false), writes book/course research example under docs/examples/research-pipeline.md + docs/templates/doc-sop.md, updates docs/worker.md with doc harness section.
4. Live E2E dogfood Task-worker-live-e2e-dogfood.md — operator checklist doc (not code), proves Go → worker without Cursor; done only when checklist true on real Redis/Coolify.

Roles invoked

Conductor → Architect (3 briefs map to 3 tasks + doc example) → Implementer per brief (disjoint: draft PR, operator notes, doc-writer) → Doc-writer (parallel) → Reviewer.

Todos

• Brief 1 draft PR
• Brief 2 operator notes
• Brief 3 doc-writer examples + routing
• Brief 4 live E2E verification (ops doc, no code)

IA

Skipped (ia in skip). No new entities beyond convoy_operator_messages; harness_providers already exists from v0.1.

UX

Skipped (ux in skip). Reuses Mission control detail panel thread section + Gate co-pilot separation.

Architecture

• State machine: doc_review→published already added packages/shared/src/convoy-lifecycle/state-machine.ts:9 — reuse.
• Worker: apps/worker/src/handle-job.ts:40 already optional worktree — add PR call after success before teardown, branch naming echodo/<convoy>-<brief8>, marker echodo-convoy: <uuid> in body for Epic 8 webhook.
• Operator notes: poll convoy_operator_messages where delivered_at IS NULL each checkpointEveryNSteps; inject Queued note: ... into system prompt tail or prepend Direct message: ....