Implement Next Task

implement-next-task

Drives the autonomous 2.0.0 ESP32-S3-only async + FreeRTOS migration (epic TASK-865, ADR-123/128). The deterministic multi-agent engine is the workflow script; it is continuous and self-announcing — one invocation drains as many tasks as it can.

Run (single lane, default worktree)

Branch model changed 2026-06-20: the 2.0.0 async line was promoted to dev (the former feature-2.0.0-esp32s3-async). dev is the default working line and the default worktree (D:/Users/Robert/Documents/GitHub/RvdB/OTGW-firmware); the old async worktree is gone. otgw-1.x.x is the 1.x maintenance line; main is always the latest public release.

Workflow({ scriptPath: "D:/Users/Robert/Documents/GitHub/RvdB/OTGW-firmware/.claude/workflows/implement-next-task.js" })

The engine, in one run:

1. Audit — captures the run's start commit (git rev-parse HEAD, the stable startHead..HEAD range the ADR-Evaluation pass diffs later), then reads every In Progress / In Review async-esp32s3 task. Resets STUCK ones (abandoned partial edits from a transient abort) to To Do; moves FINISHABLE ones (all remaining ACs build/evaluator-verifiable, committed + green, no hardware AC) to Done; leaves correctly-In-Review (field-validation pending) ones alone. It decides this itself — no permission prompt.
2. Drain loop — repeatedly: Select the lowest actionable task (deps Done/In Review; single-flight-guarded per worktree) -> Implement (coding agent, ACs + CLAUDE rules) -> build (python build.py) + evaluate.py --quick -> adversarial Review (one fix pass) -> Land (set status In Review / Done, bump prerelease if src/** touched, commit, push — no ADR in the per-task commit) -> Announce (Discord, below). Then it advances to the next task immediately — it does NOT wait for the next tick.
3. ADR Evaluation (end of run) — after the drain loop exits (whether it drained the backlog or breaks on a transient failure), if any task landed this run a single pass reviews the whole-run diff (startHead..HEAD) plus the landed task bodies, dedups the architectural decisions across all tasks into one entry each, has the JS assign the next free ADR numbers (no LLM number-picking → no collision), drafts one Proposed ADR per decision (adr-kit:adr-generator, never Accepted), runs the self-accept governance guard over them, commits them in one docs(adr): ... (TASK-865) commit (docs-only, no bump), pushes, and posts a maintainer-facing "N Proposed ADRs drafted for review" note to #dev-sat-mqtt. Each ADR's References section cites the contributing task ids + their commit hashes (the traceability that replaces riding the ADR inside the code commit). This is the only place the loop authors ADRs — moved out of the per-task path 2026-06-24 (TASK-928) so one evaluation sees cross-task decisions and the maintainer reviews a coherent batch instead of a per-task drip.
   • Process-death recovery. Every Land stamps the task note ADR-PENDING; the ADR-Evaluation pass stamps ADR-EVALUATED: <ADR-ids|none> ONLY on confirmed completion (ADRs drafted + committed, or nothing architectural to draft). If the pass dies (rate-limit) before stamping, the ADR-PENDING marker survives in git, so the NEXT run's Audit returns the task in adrOrphans and this pass sweeps it up alongside its own tasks. Enumerate greps docs/adr/ for the task ids first and skips any decision already documented, so a retry after a partial death never double-drafts. (The same marker drives the parallel-lane handoff: a skipAdrEval lane leaves its tasks ADR-PENDING for the integrating run to draw in.)
4. Stop when nothing is actionable, on a transient agent death (rate limit — it cleans up the task back to To Do and ends so a later run retries), or when a task fails review twice (flags it for attention). The ADR-Evaluation pass still runs for whatever did land before the stop, plus any ADR-PENDING orphans from a prior dead run.

Returns { done, completed: [...], count, endReason, adrsDrafted: [...] }. endReason tells you whether it drained the backlog, hit a transient rate-limit, or needs attention on a task; adrsDrafted lists the Proposed ADRs the end-of-run pass drafted (awaiting maintainer acceptance).

Parallel lanes (args.skipAdrEval, set automatically alongside skipBump) defer the ADR-Evaluation pass to serial integration so two lanes never race on ADR numbers; the integrating run drafts the ADRs once after the merge.