Explore Firstmate-style supervision for completion-oriented Workboard

[jtcchan]

Outcome

Upgrade the canonical Workboard engine from a reliable router into a completion-oriented supervisor inspired by Firstmate, while preserving the project/host/thread routing that already works.

This is a weekend exploration and controlled-upgrade project. Do not alter the live midweek polling, claim, worker, QA, or merge path until the replacement loop has passed isolated canaries and an explicit cutover gate.

Central Workboard intake: https://github.com/2xgrowthagency/donna-workboard/issues/94

Problem

Workboard correctly selects eligible Linear work, resolves the saved Codex project and host, creates the canonical Desktop worker, and preserves target locks. After routing, however, the operator still has to babysit worker progress, notice stalls and decisions, trigger validation, route rework, start independent QA, and carry passing work through closeout.

Routing is admission control, not orchestration. The missing layer is durable supervision from worker start to verified completion.

Preserve

• Linear remains the single task and workflow-state authority.
• Workboard remains the owner of eligibility, priority, capacity, project/host routing, target locks, canonical task/thread identity, and recovery reservations.
• Codex Desktop remains the runtime and native managed-worktree owner for Desktop workers.
• Saved-project assignment and app-visible thread readback remain mandatory.
• Builders never certify their own work. Independent QA returns an exact-target PASS, FAIL, or BLOCKED verdict.
• Existing deployment, production, billing, credential, destructive-action, and human-decision gates remain in force.

Explore and design

Firstmate-inspired supervision

Compare Firstmate's supervision invariants with the current Starter/Donna adopter contracts, then design the smallest host-neutral layer that adds:

• durable current worker state distinct from append-only events or transcript prose;
• actionable wakes for blocked decisions, apparent stalls, implementation completion, validation completion, PR/CI changes, QA results, and closeout;
• bounded liveness and stale-worker checks that fail to unknown rather than guessing idle or Done;
• canonical-thread follow-up/steering and restart-safe reconciliation;
• rework loops that return failed QA or warranted review findings to the same canonical worker;
• a terminal proof contract that reconciles Linear, Codex task/thread state, GitHub/PR state, and required artifacts before Done.

Do not install Firstmate as a second orchestrator, queue, or state authority. Firstmate currently does not support Codex App as a runtime backend; borrow verified invariants rather than introducing a competing terminal control plane.

Completion pipeline

Define and prove the lifecycle:

route -> clarify/plan -> implement -> no-mistakes -> independent QA -> rework if needed -> authorized merge/close -> report

• no-mistakes is the implementation validation gate: review, tests, docs, lint, push/PR, and CI.
• Independent Workboard QA evaluates the actual acceptance criteria and product behavior against an immutable target.
• A passing QA result authorizes only the existing bounded merge/close policy; it does not bypass external approval gates.

Conditional planning and parallelism

• Define explicit triggers for Lavish only when a visual comparison, architecture/migration decision, or structured human judgment will materially improve the worker brief.
• Use native Codex Desktop managed worktrees for worker isolation.
• Use native Codex subagents only for bounded internal parallel work such as exploration, tests, or review, with explicit concurrency and write-ownership rules.
• Keep independent QA as a separate root-launched Desktop thread.
• Do not depend on Treehouse for Desktop workers; it has been retired from the Studio and MacBook to avoid two worktree lifecycle owners.

GitHub interface

Use the vetted gh-axi interface for agent GitHub operations when it preserves the required auth and safe-field boundaries. Keep the official gh CLI as a fallback and record any unsupported or behaviorally different operations found during the canary.

Delivery phases

1. Read-only gap analysis: map current routing, recovery, QA, Autoreview/no-mistakes, merge, and closeout behavior against the proposed supervision lifecycle.
2. Protocol and state design: define machine-readable worker state, wake/event schema, reconciliation rules, idempotency, and failure/rollback behavior.
3. Isolated prototype: implement in the canonical Starter engine without changing live adopters or automations.
4. Adversarial tests: cover stalled, dead, ambiguous, duplicate, delayed, reworked, CI-failed, QA-failed, QA-blocked, and exact-head-changed scenarios.
5. Disposable canaries: prove one code task and one browser/QA task end to end in non-production repositories.
6. Independent review: run final tests plus independent QA on the complete diff and resolve findings.
7. Weekend cutover: sync adopters mechanically, verify compatibility manifests/conformance, enable one writer, and retain a tested rollback path.

Acceptance criteria

• Existing saved-project/host routing and deterministic Linear ordering remain unchanged unless a separately justified improvement is approved.
• One Workboard task produces one canonical implementation thread and, when required, one separate canonical QA thread; retries resume or explicitly supersede rather than duplicate.
• The supervisor can distinguish working, blocked/decision-needed, apparently stalled, implementation-complete, validation-running/failed/passed, QA-running/failed/blocked/passed, and terminal closeout states from bounded evidence.
• A worker that stops after routing is surfaced and steered without John polling the thread manually.
• Warranted validation or QA failures return to the same worker with exact findings and invalidate stale proof.
• Done is impossible without bound no-mistakes/CI proof when required, independent exact-target QA when required, authoritative PR/merge state, and Linear readback.
• No terminal/Firstmate queue, Treehouse pool, transcript scrape, or second state writer becomes authoritative.
• Live midweek behavior remains unchanged until the weekend cutover gate passes.
• Canonical Starter tests, adopter conformance, compatibility digests, and rollback canaries pass before rollout.

References

• Firstmate: https://github.com/kunchenguid/firstmate
• Firstmate Codex App boundary: https://github.com/kunchenguid/firstmate/blob/main/docs/codex-app-backend.md
• no-mistakes: https://github.com/kunchenguid/no-mistakes
• gh-axi: https://github.com/kunchenguid/gh-axi
• Codex worktrees: https://learn.chatgpt.com/docs/environments/git-worktrees
• Codex subagents: https://learn.chatgpt.com/docs/agent-configuration/subagents