Closes the four open items in `docs/development/auto-agents-tier-2-3-plan.md`
§ "Revised remaining scope (2026-05-08)" plus three rounds of fresh-eyes
critique fold-in (rounds 3, 5, and post-round-5 polish).
Highlights:
- New continuous invariant verifiers on a shared `_verify_common.py`
substrate: `verify_review_invariant.py` (R1: approval-without-CI) and
`verify_implementer_invariant.py` (I1: head-commit fails commit-lint,
I2: PR description missing Epic reference). Strictly additive cron-job-
shaped scripts that open idempotent `auto/invariant-violation` issues;
safe to run every 15 minutes in production.
- New `implementer-helpers` skill at
`.opencode/skills/implementer-helpers/SKILL.md` + CLI at
`tools/implementer_validate.py` (4 subcommands:
validate-commit-message, validate-pr-compliance, validate-file-budget,
validate-changelog). Mirrors the reviewer side; `tools/_commit_lint.py`
is shared so a future change to commit policy updates one place.
- `auto-agents.md` watchdog gate: `DISPATCHERS_RUNNING=1` puts the
primary orchestrator into watchdog-only mode. Heartbeat resolution +
age computation factored into `tools/_watchdog_helpers.py` + the CLI
`tools/watchdog_check.py` so the agent only needs
`python3 tools/watchdog_check.py *` and `sleep *` bash permissions.
The reader honours the env-var override first, then falls back to a
freshest-mtime scan across `/var/run` / `$XDG_RUNTIME_DIR` / `/tmp`
(deliberately diverging from the dispatcher's first-existing fallback
to guard against stale heartbeats from previous root-owned sessions
masking healthy user-mode heartbeats).
- `_opencode_worker.py` audit: structured `error_kind` classification
at every transport-error / timeout return site, plumbed through
`_dispatch_runtime.py` into the cycle-log; new `_request_read` retry
helper (3 × 0.5s linear backoff, transport-only) wrapping every
idempotent read in a worker session so a single transient flap on a
polling GET cannot trash a 10-minute worker session.
- Static heredoc lint at `tests/auto_agents/test_prompt_heredoc_lint.py`
glob-walks every agent prompt and skill recipe markdown, rejecting any
heredoc bash recipe in a fenced code block (per `bash-commands.md`
rule 2 — heredocs fail at OpenCode's permission-engine parse time).
- `bash-commands.md` rule 2 + its fix-it advice both lead with
apostrophe-safe `printf "%s" "<body>"` (double-quoted) form;
single-quoted form documented as the fragile JSON-only fallback.
- `CHANGELOG.md` carries the full multi-round narrative (round 3
CRITICAL/HIGH/MEDIUM/LOW fold-in, round 5 docstring drift +
telemetry refactor + broader heredoc lint scope, post-round-5
doc-drift polish).
Net delta: +911 passing tests / 3 skipped (was 825 / 3); ruff clean
on every new file; pre-existing lint debt in `_dispatch_runtime.py`,
`_opencode_worker.py`, `conftest.py`, `_commit_lint.py` unchanged
and out of scope for this commit.
Co-authored-by: Cursor <cursoragent@cursor.com>
drew
2f1be34d12