standards

Autopilot standards

These are the rules that keep an autonomous agent alive and trustworthy. They are project-agnostic: they speak in the engine's abstract verbs, never in a specific tool. Your project's config binds the verbs to real commands — the base roadmap.config.md (plumbing), composed with the active initiative's roadmaps/<id>.md overlay (source + queue). Wherever a rule says verify, push, merge, comment-pr, etc., run the binding the effective config defines for that verb.

Every rule below was earned the hard way. Treat them as non-negotiable unless the project's config (base or overlay) explicitly overrides one.

1. Verify before you claim

The cardinal sin is reporting success you did not observe.

• Run gates in the foreground. Never end your turn while a build, test, or verify command runs in the background waiting for a notification. Agents die there. A gate that takes twenty minutes in the foreground is correct; a backgrounded one that "completes" while you were composing a message means you died, not finished.
• A "completed" notification with a mid-flight final message means death, not done. If an agent's last words are "waiting for CI" or a half-written report, it crashed. Treat its branch as work-in-progress to recover, never as finished.
• Capture long-command output to a file, then read the file: cmd > run.log 2>&1; echo "exit=$?". Piping through tail/head discards the real exit code, and temp filesystems hit transient out-of-space errors that a pipe will hide.
• verify must run against committed state. Many verify commands diff against the remote base and see only committed changes — commit first, or you will "pass" having tested nothing.
• A post-rebase build is a new build. After resolving any source conflict, re-run the full verify gate. It is not a formality.
• Confirm every push was accepted. After pushing, check the remote tip equals your local tip. A rejected (non-fast-forward) push followed by a squash-merge silently drops your commits. Never treat a branch as current until the push is confirmed.

2. Scope and safety

• Never weaken, skip, or delete a failing test to get a green gate. Fix the cause or park the task. A disabled test is a lie told to the next agent.
• merge only when every gate is satisfied: verify green on the rebased branch, all required reviews triaged with no open high-severity finding, and the task's own checklist done. If a project marks a class of decision as reserved to a human, build everything around the reserved core, leave a clearly-tagged pending note, and continue — never implement the reserved part yourself.
• The base branch is untouchable directly. All work flows through branch → push → open-pr → merge. Never commit to or force-push the base.
• Reversible-by-default. Prefer additive, reversible changes. New dependencies are a last resort; if unavoidable, pin exact versions and justify them in the PR.
• No orphaned background processes. Never leave detached load generators, dev servers, watchers, or busy-loops alive. Any synthetic load dies with the test that needed it (via trap/finally). Orphans starve every later gate on the machine — one stray pool of busy-loops once held an entire CI host hostage for hours.

3. Judgment

• Never block; decide, log, move. When the spec is ambiguous, take the most operational, simplest interpretation, record the decision via log-decision, and proceed. Your replacement for a human stakeholder is the set of canonical documents the roadmap.config.md names.
• Circuit-break flaky externals. If an external provider (a review model, an API) fails twice in a row, drop it for the session and continue without it rather than retrying into a wall.
• Distinguish environmental from real failures. Container-launch or "under load" gate failures are often environmental — re-run the single failing unit once before counting it as a real strike. But before blaming the environment, sweep for orphaned processes (ps aux | sort -rk3 | head): a dead sibling's leftovers, not the test, are often the cause.
• Treat digests and notifications as leads, not facts. A resume digest or a hand-off describes state at write time, and the writer may have died mid-action. Before acting on a claim ("branch pushed", "PR open"), verify it against the remote.

4. Craft and communication

• The output contract is strict. Emit one line per task to the chat (TASK-ID → PR #N merged or TASK-ID → parked: <reason, ≤5 words>). All prose lives in artifacts: specs, PR descriptions, tracker comments, memory. Do not narrate, plan aloud, or summarize what you are doing.
• The engine's mechanics are internal — never echo them to chat or into any artifact. Roadmap/overlay resolution, queue-vs-source drift reasoning, dependency-readiness analysis, and lane/wave grouping are how you decide what to work; they are not user-facing. Never emit blocks like "this is overlay mode, the picture is clear…", dependency breakdowns, or wave/parallel-pair groupings. "Overlay" in particular is our internal word for an initiative's roadmap file — it must never reach the consumer. Keep it out of commit messages, PR titles/descriptions, and branch names: say the initiative by id or as "the roadmap", never "the overlay" (e.g. chore(roadmap): scaffold <id>, not "scaffold roadmap overlay"). Keep that reasoning in your own head and in log-decision. The user sees only the contract lines above, the one-line drift report (§3 / the drift check), and the digest pointer — nothing about how the queue was resolved or sequenced.
• Post evidence before prose. Every review — especially the last one — is posted via comment-pr the instant its triage is done, before you write any sentence about it. Producing a review's text without posting it is the single most common way these agents die: the turn ends on the review text and someone else has to finish your job. If your last action generated a review, your turn is not over.
• Your final message is the report, never raw tool output. Before composing it, run the Before you send checklist below. The report is: PR reference, triage summary, decisions one line each, derived work, parked parts. If a review is the last thing you produced and is unposted, post it first.

Before you send

Run this every time, before you compose any final message. It is the single gate the rest of these standards converge on — most agent deaths are a missed line here:

1. Unposted evidence? If your last action produced a review or any evidence, it is posted via comment-pr and the URL came back. If not, post it now — your turn is not over.
2. Background gate? Nothing load-bearing is still running in the background. Gates ran in the foreground with output captured to a file, and you read the file (§1).
3. Claims observed, not assumed? Every "done" was seen, not hoped: push accepted (remote tip == local tip), verify green against committed state, merge confirmed to contain your work.
4. Bookkeeping done? complete, log-decision, derive, and any pending-human note are written to artifacts — not merely described in chat.
5. Then, and only then, the report. One line per item to chat (the output contract above); all prose lives in artifacts.

Failing any check means you are not done: fix it before sending, don't narrate it.

5. Working in a shared or parallel checkout

These apply whenever a fleet runs agents in parallel against one repository.

• Lock contention is real. branch/commit/checkout can fail when siblings hold the index lock — retry after a few seconds. Critically, verify the current branch (git branch --show-current) before any gate: a silently-failed checkout leaves you on the base branch, and the gate then "passes" on the base instead of your work.
• Commit early, push early. If you crash, recovery starts from the pushed branch. Work-in-progress commits are fine; they get squashed at merge.
• Worktrees change tool context. Directory-named tooling (compose projects, caches) resolves differently inside a worktree. Run such commands from the real repository root or pass an explicit project/path. The shell's working directory dies with a removed worktree — anchor every command with an absolute path.

6. The strictly-serial merge queue (fleet only)

This is what makes parallel execution safe. The orchestrator merges one PR at a time, in completion order, onto the roadmap's configured base — its integration branch when one is set (§11), mainline otherwise; two concurrent roadmaps each run their own queue on their own branch and never interact. For each ready PR:

1. Rebase onto the fresh remote base. Apply the project's conflict protocol: regenerate (never hand-merge) generated artifacts; resolve ordering collisions per the config; union additive data (e.g. translation keys); re-run the full verify after any source conflict. Anchor commands with an absolute path and verify the current branch before any gate.
2. verify with full log capture to a file — never trust a piped exit code. Perform any deferred manual QA now.
3. If the queue added fix commits: push and confirm acceptance (remote tip == local tip) before merge. A rejected push plus a squash-merge silently drops the fixes.
4. merge, then sync the base and confirm the merged commit actually contains what you think it does when fixes were involved. Only now remove the agent's worktree and local branch — never on a completion notification, which can fire while the agent is still reviving; removing a live agent's worktree kills it.
5. Bookkeeping: complete the task, post its decision lines via log-decision, derive any follow-up work, post pending-human notes.
6. Refill the lane: claim the next fitting task and spawn.

If steps 1–2 fail twice on the same PR for non-environmental reasons, park it and free the lane.

7. Crash recovery (fleet only)

Agents die ending their turn on a background gate or on review text.

• General case: a "completed" notification whose final message is mid-flight means the agent died. Inspect its worktree, commit+push any state as WIP, and spawn a finisher scoped to the remaining steps (verify → reviews-posted-on-PR → open-pr → report). Never reimplement; never let two agents drive one branch — the finisher owns it, and later ghost revivals of the dead agent are read-only echoes.
• Most common death — died on the review text: the final message is a finished review instead of the report. The PR is almost always complete (branch pushed, earlier reviews posted) — only this review comment and the report are missing. Do not spawn a finisher: the orchestrator posts the review from the agent's result via comment-pr (with a one-line attribution note), confirms remote tip == worktree tip, and runs the normal queue pass. Diagnose by reading the PR's comments and the worktree before assuming anything is missing.

8. Cost policy (fleet only)

• Implementation agents and any triage of judgment inherit the session's default model — they need full judgment.
• Spawn mechanical verification agents on a cheaper model (e.g. sonnet). Mechanical = the outcome is extractive or binary, not a judgment call: evidence extraction ("did review X run? quote the verdict"), data cross-checks (key-completeness, id↔enum parity), "does X exist" sweeps, false-positive filtering against an explicit exclusion list.
• When unsure whether a check is mechanical, it isn't — use the default. Triage decisions are never delegated to the cheap model.

9. Stop conditions (loop guards)

Autopilot runs to completion, then stops — it is not a daemon.

• Mission complete — the only remaining ready work is blocked by an external wall (missing credentials/infra) or reserved for a human. Write the final digest and end. If launched on a loop, do not reschedule; this is the intended terminal state.
• Session boundary — a context summarization happened or context is degrading. Finish the current task cleanly, write a resume digest, and stop. On a loop you resume next firing; the queue state lives in the roadmap source, not in your memory.
• Safety — two consecutive failed gates on the same task: park it and take the next. Two consecutive parked tasks in a row: likely systemic — write a digest and stop rather than burning the queue.

10. The session marker (one run per roadmap)

Autopilot runs at most one solo/fleet per roadmap at a time — two runs on one roadmap would share its queue and trample each other. Two agents driving different roadmaps may run concurrently; the marker is per-roadmap, never a repo-wide lock.

• The marker is a small open/closed signal the roadmap's source binding provides, anchored to that roadmap's own source (a comment or label on the epic / tracking issue, a line in the checklist — see examples/bindings/).
• Check it before starting; if open, stop and report (another run owns this roadmap). Post it open on start; close it in the end-of-run digest.
• A crashed run can leave it open — a human clears a stale marker. The engine never force-steals an open roadmap.

11. Integration branches and reconciliation

A roadmap that runs alongside another targets its own integration branch instead of mainline (its effective ## Code-host binding points branch/open-pr/merge at integration/<ID>). This makes concurrency safe by construction: each roadmap's serial merge queue (§6) lives on its own branch, so two concurrent runs never share a queue and cannot collide — no cross-roadmap lane-surface coordination is needed.

• Keep the branch fresh. Merge mainline forward into the integration branch periodically (the fleet whenever a lane drains, solo at the start of each run), re-running verify after any conflict, so the final merge stays small.
• Reconcile once, at mission-complete. reconcile merges the integration branch into mainline behind the full verify gate and the conflict protocol — a single deliberate merge, naturally serialized with any other roadmap's reconcile because they all target mainline. If it conflicts irreducibly, park the reconcile with a note and report; never force it.
• Never reconcile at a session boundary — the roadmap is unfinished; leave the integration branch open for the next run.
• A roadmap that runs alone skips all of this: it targets mainline directly and has no reconcile.