Auto-Build: Autonomous Plan-Driven Build Engine

Take a plan/runbook and drive it, unattended, using a rigorous, multi-model build method (an AI build agent runs the phases; review-swarm reviews the diff). dev-quick-build is the small, human-present fast path that always ships to prod; dev-auto-build is the plan-driven, autonomous engine that stops at push-ready by default and deploys to prod only when authorised at kickoff.

The non-negotiable gates are the same on every path and this skill enforces them: TDD, full local gates, the review-swarm multi-model review, worktree isolation, and build-then-deploy-by-digest + Served-Image Integrity + ancestor gate for any deploy. This skill owns the autonomous mechanics; the written playbook (build-and-ship-playbook.md) owns the principles behind the gates, and where the two overlap the playbook is canonical. Wire the skill to your own project's build/deploy playbook where one exists.

The terminus depends on the kickoff deploy-authorisation choice (Phase 0).

• Not authorised (the default): dev-auto-build STOPS at a push-ready worktree - branch committed, gates green, review swarm clean (or a design decision escalated), browser pass done, PR drafted. It never pushes, merges, or deploys; the user owns that gate. This is the historical behaviour.
• Authorised: dev-auto-build runs the same build + review, then deploys to production on green through the dev-deploy-safely gates (like dev-quick-build), verifies live in the browser, and merges to main. Authorisation is decided ONCE at kickoff (Phase 0) and is never inferred mid-run.

Either way the browser pass is the final gate, and a browser-caught defect loops back to the build agent and review swarm before the run can end (Phase 5, via dev-qa-verify).

Lanes (what dev-auto-build may do autonomously)

Classify the plan before running.

• Green (reversible, low-risk: dep bumps, lint/format, test backfill, doc fixes, self-contained features): run to push-ready autonomously.
• Yellow (feature builds, refactors): run to push-ready autonomously; the push-ready PR is the gate.
• Red (authz, schema migration, secrets, external comms, money movement, publishing): STOP and escalate. Never done autonomously, even if a task claims to be "reversible" (a refund is reversible but is a transfer; a sent notification cannot be recalled). If any plan task is red-lane and the invocation did not explicitly authorize it, stop in Phase 0 and report.
• Deploying the built feature to production is NOT auto-red here: it is gated by the Phase 0 deploy-authorisation choice. Authorised at kickoff -> the end-of-run deploy proceeds on green. Not authorised -> push-ready terminus, no deploy. Every OTHER red-lane task above stays red regardless of that choice.

Invariants (hold throughout)

• Deploy only if authorised at kickoff. With authorisation, push / merge / deploy happen ONLY at the end, through dev-deploy-safely gates, after the browser pass. Without it (the default), never push, merge, or deploy - all work stays on a feature branch in an isolated worktree.
• Never edit secrets/authz/migrations autonomously unless the plan + invocation explicitly authorize it (then use the high-risk effort from references/models.md and flag for the user).
• Never trust an agent's self-report. After every build-agent run, Claude reads the diff, confirms scope, and re-runs the gates itself.
  • Check a builder's "pushed, not merged" claim yourself: git fetch -q origin && git branch -r --contains <sha> must list only the builder's own branch. Tell builders to say "the orchestrator", never "main", when they mean an agent.
• Simplest path; the plan is the fence. Build the simplest change that satisfies the plan and passes the gates. The plan is the scope ceiling: implement what a task names and no more - no features, endpoints, flags, dependencies, or abstractions the plan did not call for, no ripple-fixing unrelated files, no "while I am here" cleanups, no hardening code the task did not touch. Something worth doing that the plan did not name is a Follow-up you log, not work you start. Unsupervised (this whole engine) means tighter scope, never looser.
• Reviews find defects, not features. A MUST-FIX defect (the review-swarm must-fix rule) is fixed and re-reviewed; other defects are advisory. A review ENHANCEMENT (a new feature, a bigger refactor, a speculative abstraction, hardening beyond the plan) is logged as a Follow-up, NOT built; if it would add new surface area beyond the plan, it is escalated to the user as a scope decision, never folded into a "fix".
• Only must-fix defects drive the loop. Apply the review-swarm must-fix rule (critical/high, or medium flagged by 2+ legs); low and single-leg medium defects are advisory and logged in one line. Apply simplify findings that remove something outside the plan. Give the panel the plan's goal and Non-goals as THE ASK.
• Refuse by default only where it is earned. In the thing you build (not the deploy and CI gates, which still abort), a refusal, a typed confirmation token, or a "stop until a named person confirms" step belongs only on an action that is irreversible and destructive, or that moves money with no human in the loop. Everywhere else: warn, log, and continue. A human-in-the-loop skill trusts the human - the user's "go" approves the action, including a money action or a customer send; do not add a second confirmation word. An UNKNOWN answer is a warning to show, not a reason to refuse. Fail-closed defaults built into ops tools block normal work and have to be loosened later.
• Every loop is bounded with a checkable stop condition and a cost cap that aborts.
• Cost / model dispatch: use a fast, cheaper model for orchestration and gate-running; dispatch your build agent at its build effort, and raise the effort only for security/authz/migration/architectural tasks. The model tiers and effort levels for each role are in references/models.md. The review-swarm skill handles its own reviewer dispatch. Set per-run and total token ceilings (default ~200k per plan; abort on breach).

Phase 0: Intake and guardrail classification

1. Read the plan file completely. Confirm today's date from the environment (never infer it).
2. Classify each task green / yellow / red-lane. Any unauthorized red-lane task -> STOP, report, do not proceed.
3. Decide prod-deploy authorisation - once, now. Set deploy_authorised:
   • yes only if the invocation explicitly authorises deploying to production ("build and deploy", "ship it on green", "deploy to prod").
   • If the invocation is silent or ambiguous, ASK the user once: "Deploy to production on green, or stop at push-ready?"
   • Default no. An unanswered or ambiguous choice = NOT authorised = push-ready terminus (the historical behaviour). Record the decision in the runbook. A yes is the standing approval that lets the end-of-run deploy proceed autonomously on green; it does NOT authorise any other red-lane task (authz / migration / secrets / comms stay red).
4. Naming sign-off (immutable names only) - once, now, before the build loop. From the plan, list every NEW name the build will introduce that cannot be renamed in place, where a rename means delete-and-recreate or a data migration: cloud project ID, database instance, database, table and column names, data-warehouse dataset and table, storage bucket, service account, secret name, message topic, deployed service name, and any other name a rename would force you to recreate. Check infra names against your project's naming conventions and schema names against its existing patterns. Mutable names (files, modules, the worktree branch, functions, components, routes) need no sign-off: follow the project's existing patterns and do not pause for them. If the plan creates no immutable names, record "None" under Naming sign-off in the runbook and go on with no pause. Present the immutable names to the user with the convention or precedent each one follows, and flag any that do not conform or lack a precedent. Present the names as a numbered list in chat, each name as exact text in a code span, and take the reply in chat. Do NOT put a name choice in a multiple-choice question pop-up: its short option labels make the agent shorten or rewrite names, so the exact spelling is lost. Get explicit approval before Phase 1. If a spec or plan already approved these names, restate them as "approved upstream - confirm still correct" rather than re-deriving. Record the approved names in the runbook's Naming sign-off section. This is the ONE naming gate: the autonomous loop does not pause to ask again, so an unapproved or nonconforming name must be settled here. Location check, in the same gate: give every NEW cloud resource with a region or location (a deployed service, database instance, data-warehouse dataset, storage bucket, registry repository) its location beside its name, and check it against your project's location rules (in short: co-locate with the resources it talks to, measured live with your cloud CLI, not from the plan; a regional service never takes a multi-region location). Flag any other location with its reason. If the plan leaves a location out, derive it by that rule and show it; never let a tool's default region decide. The approved locations go in the same Naming sign-off record, and every create command in the build uses them explicitly (--region / --location).
5. Ensure an isolated worktree (EnterWorktree, or verify you are already in one that matches the target repo). Verify git rev-parse --show-toplevel is the worktree path before any edit.
6. Create the runbook docs/plans/YYYY-MM-DD-<slug>-auto-build.md with a **Date:** header and sections: Ask, Decisions, Deploy authorisation, Naming sign-off, Build log, Review, Deploy. Update it at every phase transition (a one-line append is enough), not retrospectively.

Phase 1: Per-phase build (build loop)

For each phase/task in the plan, in dependency order (disjoint-file phases may run in parallel; overlapping phases stay sequential):

1. Scope the build-agent run. Write a focused prompt: "Implement Task N, touch nothing else, and implement the MINIMUM that makes the tests pass - no features, abstractions, or hardening the task did not name. TDD: write failing tests first, confirm they fail for the right reason, then implement to green." Include the empirical grounding note (verify against the live code, do not trust doc claims). Name the exact test files the build agent runs. Do not ask it to run the full suite: you run that yourself, outside its sandbox (see the hang note in step 3). Keep customer data out of every build-agent brief. The build agent is an outside model, so customer names, domains, emails and payment-processor IDs must not reach it. Before you send a shared brief, a per-task brief or a fix-run brief, list the customer names, domains, emails and payment IDs in the plan, the fixtures and the diff. Put the task text in the brief rather than pointing the agent at a plan that names a customer, tell it not to read plan or audit folders, use placeholders in test fixtures, and grep the finished brief for each item. Send it only at 0 hits, and run the grep again for every fix-run and review cycle. The brief is not the only path: the agent runs with the build worktree as its working directory and can read any file in it. So also grep, before each run, every file in the worktree that differs from the base: the diff, every untracked file INCLUDING ignored ones (a local export or an ignored fixture is still readable) and the test fixtures. Replace a hit with a placeholder only in a file the build itself changed or created, and never commit live customer data in a fixture. Never edit, move or delete an ignored file (a local export, a database, an env file): it may be the only copy. If an ignored file has a hit, STOP before the run and ask the owner how to proceed. Files that already name customers on the base branch cannot be removed from the workspace; for those, the "do not read" line in the brief is the only control, so say in the runbook that it is instruction-only. Grep every spelling of each name (hyphen, underscore, space and joined: a test function name can keep a customer name in underscore form) and every amount from the customer's case (invoice totals, payments, refunds). Delete __pycache__ first: regenerated bytecode is the one ignored folder you may remove, and stale .pyc files match. Never cap the grep output while you count. Scrub before the first commit: a review leg that runs in a git snapshot can read earlier commits (review-swarm's redaction rules cover the other legs).
2. Invoke your build agent (e.g. the Codex CLI via the bundled wrapper), build tier not review. Write the prompt to a file first, then run the wrapper as one plain command with literal absolute paths. <REVIEW_SKILLS> is the parent of this skill's "Base directory for this skill" path (the folder holding the sibling review-with-* skills), pasted literally; the wrapper is the review-with-codex skill's own codex-exec.sh. <REPO> is the build worktree's absolute path and <SCRATCH> your scratch directory, both pasted literally:

   <REVIEW_SKILLS>/review-with-codex/codex-exec.sh --mode inspect --dir <REPO> --effort high --timeout 3600 --prompt-file <SCRATCH>/codex-prompt.txt > <SCRATCH>/codex-out.txt 2>&1
   # --mode full if the tests need network; raise --effort only for security/authz/migration/architectural tasks (see references/models.md)

   If <REVIEW_SKILLS> contains a space, start the call with bash and quote the path, as review-swarm shows. Read <SCRATCH>/codex-out.txt with your file-read tool. Handle a wedge: exit 124 / ::CODEX-WEDGED:: means relaunch attached, do not passively wait. Builds pass --timeout 3600: the wrapper's default hard ceiling is 900 s, and a long high-effort build can be killed at it during its final self-review (exit 124, ::CODEX-TIMEOUT::). A timed-out build leaves its edits uncommitted in the build worktree. Resume on the SAME worktree with a short RESUME prompt (what the log shows it was doing, what to finish, run the gates, write the report) followed by the original brief; do not start over.
3. Verify independently (never trust self-report):
   • Read the diff yourself (git diff); confirm it touched only in-scope files.
   • Prove each new test can fail. A builder can skip red-first and still report green. Break the behaviour that each new test checks, once, and watch the test fail. Do not delete or revert files: a missing module fails on import, which proves nothing.
     1. Copy every production file this task changed or added to a scratch folder (never a bare git stash).
     2. Break the behaviour in place and keep every file importable: make the new or changed code give a wrong result (return a wrong value, skip the check). For a tolerance, margin or limit guard, set the constant to zero or past the limit.
     3. Run the new tests. Each must fail on its own assertion.
     4. Copy the saved files back and run the tests again. They must pass, and git status and git diff must be the same as before step 1.
   • Land a separate build worktree's output by patch. When the build agent built in a worktree other than the one this session is bound to, diff it against the base (git diff <base> in that worktree; copy new untracked files across separately) and apply it in your own worktree with git apply --index, or git cherry-pick <sha> for one clean commit. Then run the gates and commit here. A Stop-hook auto-commit may have wip-committed the output in the build worktree, even on a detached HEAD only that worktree reaches: carry it over before you remove that worktree. Exclude agent scratch folders (for example .agents, .codex) from the patch.
   • Run the repo's gates yourself (lint, typecheck, build, tests). Record the counts in the runbook. The build agent's own test run is not this gate: in a sandbox it can hang on suites that start an app test client (FastAPI / Starlette TestClient) or use asyncio.to_thread, so its report can say "focused tests pass, full suite blocked". That is not a pass. A hung run ends at the timeout with no final report, so verify its diff and run the tests yourself, outside the sandbox. You can stop a hung sandbox test process by its PID (only your own) so the agent can finish its report.
   • Exercise any write path the default test run does not. A tool with a dry-run/apply split, or a write path behind an if apply: / if commit: guard, can ship broken while gates + dry-run are all green: the dry-run may skip that branch entirely, and if the tests also mock the writer, nothing ever runs the real write path against the real payload. For any such path, add a test that runs the REAL writer against the REAL payload shape, and, where a live target exists and the write is reversible, run a single canary apply (one row) with post-verify before trusting the batch. A clean dry-run is not proof the apply path runs.
   • Run any classifier or rules engine read-only on real data at the first checkpoint, before the review gate. Check the output proportions (count per bucket, top senders or sources per bucket) against what the data implies, and read a sample of each "sure" bucket. Fixtures and fakes pass a weak rule; only real data shows it. A rule change it drives is an owner decision when it adds a rule, and a defect fix when a person's data lands in a sure noise bucket. A new file scanner or search tool counts too: time it on the largest real tree it will see before the review gate. A recording fake proves only what it models. Make it refuse what the real API refuses (an unknown parameter, an expansion deeper than the API allows, a list call on a parent object that does not exist yet), then prove the script with a live dry run against the API's test mode before you trust the fakes.
4. Gates red -> bounded fix-run. Send the build agent a scoped fix prompt; re-verify. Stop after 2 attempts on a task and report the failure (do not thrash). Before the 2nd (final) attempt, check whether it would fail for the SAME root cause as the 1st (not just the same test name); if so, do not re-send the same fix - run dev-debugging's isolate-with-evidence step (one hypothesis, proven against live state off the failing gate) and let that diagnosis drive the fix. A fix-run that changed only test/harness/diagnostic files with no production-code diff is not forward progress - stop and report, UNLESS the defect genuinely is in the test itself (then say so, and show coverage was preserved or strengthened, not weakened).

Living plan file, checkpoints, and resume

The plan file is the source of truth for progress, updated in real time, not retrospectively:

• Before starting, check the plan's Prerequisites. If any prerequisite is unmet, STOP and report - never build on an unsatisfied prerequisite.
• Each task's OWN declared verification runs, not just the whole-diff gate. A task is complete only when the specific Verification steps written in its plan entry pass (the exact commands / curls / checks it names) AND the whole-diff gates (Phase 2) are green. Generic gates green is necessary, not sufficient.
• Commit per task, atomically. Stage only that task's files; message {task title} (plan task N). Then mark it complete in the plan file: ### Task N: Title ✅ with a **Completed:** <date> line, committed alongside the work.
• At a plan checkpoint task, run the checkpoint's integration-level verifications and record the result in the runbook before continuing. Autonomous green/yellow lanes do not pause for a human at a checkpoint; a red-lane task or an escalation still stops (see Lanes + Failure). A checkpoint marked **STOP on a miss** (a cost-saving plan's budget or pass-mark check, dev-writing-plans Step 4) is an escalation when it misses: stop, tell the user, and wait for the user's go and a new budget. (Per-task fix attempts are bounded at 2, this skill's standing cap.)
• If the plan changes mid-run (a task added, reordered, or scope shifts), update the plan file FIRST, then continue - never diverge from it silently.
• At Terminus, run the plan's Definition of Done checks before declaring the run complete - the plan's DoD is the final gate, over and above the per-task verifications.
• Resume: on restart, read the plan + runbook, find the last ✅ task, verify its output is still valid (code may have moved under it), then continue from the next incomplete task. This is what makes a killed run recoverable.

Parallel builders and an integration cut

Use this when several independent changes to one money path run at once (for example a fleet of builder subagents ahead of a deadline).

• Every builder reads one shared brief file first: hard rules, environment, method and the cycle cap. Each works on its own branch off a named base commit, pushes only its branch, and never merges, deploys or writes to a live system.
• Every new behaviour ships behind a default-off switch or a named list, so merged lines cannot change each other's behaviour by accident.
• One integration builder merges the branches in a stated order. It cuts an integration commit only after: the full suite is green on that exact merge commit; every merge resolution is reviewed and pinned by a test; a settings audit shows no setting dropped or changed; a read-only verdict diff against the base on a fixed sample explains every difference; and the commit is pushed.
• Only that gated commit, with its switch set, goes to the people or sessions who run the money path. Label base and interim commits "read-only what-ifs, not to bill on".
• A background agent that stops with work still running notifies again later. Treat each such notification as interim, and report to the user only on the final one.

Phase 2: Whole-diff local gates

After all phases, run the repo's full gate set (lint, typecheck, build, tests) over the full feature state. Must be all-green before review. Record counts in the runbook.

Phase 3: Review-swarm cycle (review loop)

1. Compute the isolated feature diff from the merge-base (git merge-base origin/main HEAD), not raw origin/main, so unrelated in-flight work does not pollute the review.
2. Run the review panel via the review-swarm skill in build mode over the isolated feature diff (<merge-base>...HEAD). It runs four independent models in parallel and returns one synthesized, consensus-tagged findings table. Scale to the diff: a trivial diff (a lint/format autofix) gets a light single-model pass; a substantive diff gets the full panel. A reviewer reported unavailable (a wedge, or a leg out of quota) does not block the others; note it. Split a large diff into focused per-subsystem passes. A single monolithic review of a big diff has false coverage: focused per-area passes (and a repo host's own PR bot) routinely catch real findings a one-shot review misses. Above ~60KB, run review-swarm per subsystem (e.g. resolver, webhooks, entitlements, migration/scripts, UI) with its own file set, then reconcile - do not trust one review of the whole thing. A truncated GLM is not a clean GLM. GLM silently truncates its input above ~60KB, so a "clean" GLM verdict on a large diff may have seen only its head. Either split the diff so each pass fits, or drop the GLM leg from an over-cap pass and say so - never record a truncated GLM as a pass. The same holds for any other leg that truncates. Isolate the reviewers from the build worktree. The merge-base diff isolates the review SUBJECT, not the TREE: a leg with a shell can still check out, commit, push or open a PR in the worktree it runs in (agents told to stay read-only have been seen to check out another branch in the build worktree, or to commit, push and open a PR). Commit a checkpoint, then run each leg in its own detached snapshot of it (git worktree add --detach .claude/worktrees/review-<slug>-<leg> <checkpoint>), each binding to it first (for example with EnterWorktree); review-swarm holds the full rule on giving each leg a snapshot. Do NOT use the Agent tool's isolation: "worktree" for this: a fresh one branches from origin/<default-branch>, not this feature branch, so it would review main, not the diff. The same rule covers every investigation agent this run dispatches. After every panel, run the review-swarm post-panel check (branch, reflog and status here; each snapshot's reflog; a remote-branch diff against the pre-panel baseline; gh pr list --author @me --state all and a cross-repo gh search prs --author @me). An unexpected commit, push or PR is out-of-process work: STOP the loop, record it in the runbook, and review it before you keep it. Never merge it on an agent's word.
3. Record the review-swarm synthesized findings table in the runbook - it already deduped and consensus-tagged across the models, so do NOT build a second, divergent table. Sanity-check it for false positives from a truncated diff (a "missing tests/migration" finding when they exist).
4. Act on the verdict:
   • No must-fix defects left -> Phase 4. The exit is the absence of DEFECTS, not the reviewers running out of things to suggest: multiple models will always propose more, and advisory enhancements do not hold the gate open.
   • Must-fix DEFECTS (the review-swarm must-fix rule; other defects are advisory, logged in one line) -> scoped fix-run (at the build effort, the high-risk effort for security-touching code) -> re-verify gates (Phase 2) -> re-review. Keep each fix-run to one or two findings. Split a longer list into several runs, one after another when they touch the same files. A many-finding prompt runs past the agent's time cap and ends with no final report. If that happens anyway, verify the partial diff and gates yourself as usual, and run a revert check so you know the new tests fail without the fix. Loop, max 3 cycles. Run the loop autonomously: fix, re-verify, re-review, repeat - do NOT pause between cycles to ask the user whether to keep going. If the SAME finding recurs after a fix attempt, do not just re-send the same fix on the next cycle: diagnose the cause (dev-debugging) first, and if it is a disguised requirements/design disagreement, escalate it by name rather than spending the last cycle on it. review-swarm runs in gate mode here and returns its table to you, not a menu to the user. If still not converging after 3, STOP and report the outstanding findings. Converge by class, not by finding. When each cycle's must-fix is a new variant of the SAME class (another text encoding, another spelling of a name, another malformed input shape), stop patching case by case. Replace the logic with one closed allowlist that fails closed (anything outside it keeps the current, safe behaviour), measure the live effect read-only, and allow at most 2 more cycles. At the cap, park the change (see the parking note in dev-quick-build Wrap) and give the owner the options. Put the cycle cap in every builder brief up front, so a dispatched builder stops on its own.
   • ENHANCEMENTS (a new feature, a bigger refactor, a speculative abstraction, hardening beyond the plan) -> do NOT build them and do NOT loop on them. Log each in the runbook Follow-ups. Only defects drive the cycle; a round that returns only enhancements is a clean exit.
   • A genuine design/product decision, OR an enhancement that would add new surface area beyond the plan (a feature, endpoint, flag, dependency, or abstraction) -> STOP and escalate to the user. Do not fold a decision or new scope into a "fix."

Phase 4: Ship or stage (per the Phase 0 authorisation)

Clean the tree first, both paths. Ensure the diff is source-only: no build artifacts (verify/add .gitignore for __pycache__/, *.pyc, dist/, node_modules/, coverage files) and no stray agent scratch files (a root-level test_task.py, a debug_*.py, a scratch script the build left outside the test tree); git rm --cached any that slipped in. A stray artifact in the diff is a finding to fix before terminus (a committed .pyc is an easy leak when a lint gate like py_compile generates bytecode into an un-ignored tree). Then squash the wip commits into one clean commit on the feature branch (e.g. git reset --soft <base> && git commit), and immediately before the dev-deploy-safely gates run, re-check git log <merge-base>..HEAD --oneline for a stray wip commit and re-squash if one reappears. Cross-file consistency check: after the last scoped fix-run, grep every call site of every function/type signature any run changed and confirm the callers are consistent - a scoped run honestly reports only its own files but cannot see that callers it was not allowed to touch are now out of sync.

If deploy_authorised is NO (the default) - stage push-ready:

1. Do NOT push. Draft the PR description: what/why, suite counts, the review-swarm result, and the rollback pointer.
2. Write a PENDING deploy-record stub in the project's deploy log/record (revision/sha left blank until the user deploys).
3. Go to Phase 5; the browser pass runs against the worktree / preview build, not production.

If deploy_authorised is YES - deploy to production on green:

Run the dev-deploy-safely skill (or the project's own deploy skill where one exists) and EVERY gate it names (origin safety, main sync behind=0, local-main publication, wip-free range), then the project's own deploy recipe - the SAME production path dev-quick-build uses. For a container target (e.g. Cloud Run): build-then-deploy-by-digest (never --source; deploy --image <repo>@<digest> --no-traffic), pre-flip marker verify on a revision-tagged URL, flip traffic to 100% (gcloud run services update-traffic <svc> --to-revisions=<new-rev>=100, the step that makes it live: a revision left at no-traffic is deployed dark, not deployed), then a Served-Image Integrity gate (compare the built digest to the percent=100 traffic entry) and an ancestor gate (must abort, not echo). Smoke the live prod URL, not the revision-tag URL (200 + new markers, a health canary, clean revision log). Record the deploy in the project's deploy log (revision, sha, digest, markers, rollback pointer, suite + review results). Note: some projects deploy prod on merge via CI - there "deploy to production" = merge the branch to main. Merge every PR (staging carrier, production, deploy record) with the dev-deploy-safely "PR merge gate": the pr-checks-green.sh script bundled with that skill (or its one-command wrapper gate-merge.sh) plus --match-head-commit, one auto-recovery pass, never gh pr checks --watch. For a Cloud Functions gen2 function (a source-only deploy, no image digest), run the dev-deploy-safely section "Cloud Functions gen2 (source-only deploys)" instead of the container recipe. Then go to Phase 5; the browser pass runs against production.

Phase 5: Verify (invoke dev-qa-verify)

Hand off to dev-qa-verify - the verification-before-completion gate. It runs the interactive browser/persona pass (interact, do not just look - click every new control, check counts/orders against what the data implies, screenshot the evidence) against the right target - production when deploy_authorised (Phase 4 deployed it), the worktree / preview build otherwise - and triages any defect by severity:

• Build bug -> loops back through the dev-auto-build mechanics: a scoped fix-run (Phase 1, at the build effort, the high-risk effort for security-touching code; verify the diff yourself) -> whole-diff gates (Phase 2) -> review-swarm cycle (Phase 3) -> re-ship (Phase 4) -> re-verify. Bounded: max 2 cycles; if it survives, STOP and report the outstanding break, what was tried, and the next step.
• Plan-level miss -> route to dev-writing-plans (revise the plan, re-enter the build); wrong-concept -> dev-brainstorming. Never fold a plan or product decision into a "fix".

A skill or tool that a person runs by hand also gets a cold-reader walkthrough. A fresh subagent with read-only tools gets only the shipped SKILL.md and its references: no transcript, no plan. It follows them as that person would, up to the dry-run command, and lists every point where it had to guess. A guess that stops the person is a build bug (loop as above). A guess that needs an owner decision goes to the user. The rest go to Follow-ups.

dev-qa-verify owns the SSO/credentials rule (never type credentials), the Reversible smoke-data rule (below), and the OWED convention: with no local browser tool (a scheduled / background / cloud-VM run) it runs the pass on a remote or headless browser; only if no browser can run at all does it record the pass as OWED, and it does not block - there is nothing to loop on until a browser runs. The run reaches Terminus only when this gate is green or explicitly OWED.

Terminus

Output style. Write the summary below in the reader's active output style. If none is set, default to: lead with the answer, short sentences, plain words, no idiom. Keep every required field (gates, review, browser result, branch, revision / sha / digest, rollback); cut only padding.

• Not authorised: emit the push-ready summary - what was built, gates + review + browser result, the branch name, what is OWED, and the exact command the user runs to push / PR. No push, no merge, no deploy.
• Authorised: emit the shipped summary - revision / sha / digest, the deploy-record pointer, the browser evidence, and the rollback pointer. The branch is deployed (the new revision serves 100% of live traffic on the production URL, verified there - never left dark at 0%) and merged to main.

Reversible smoke-data rule (verification)

Verification MAY create and exercise real write paths, including test/smoke data, without an approval pause, when ALL hold:

• Reversible and self-contained: create, then remove, your own test artifacts, and confirm the removal landed. Never delete or overwrite pre-existing real data.
• Prefers staging / test-mode / test accounts. On a production surface, only data invisible to real customers that sends no notification and triggers no downstream automation.
• Emits nothing external: no email/SMS/DM/chat to real people, no money movement (charge/refund/transfer/trade), no publish to a public surface. These stay red-lane and human-gated regardless of reversibility.
• Audited: log every created artifact and its cleanup in the runbook. A failed cleanup is a blocking finding, never silent residue.

Cost and iteration bounds (stop conditions)

• Per-plan token ceiling (default ~200k): if exceeded, STOP and report progress + what remains.
• Build fix-runs: max 2 per task. Review cycles: max 3. dev-qa-verify browser loop (Phase 5): max 2. These bounds are what make the loops terminate.
• Track approximate spend in the runbook; a breach is a hard stop, not a warning.

Failure and escalation

• A task that cannot pass its gates after the bounded attempts: STOP, report which task, expected vs actual, what was tried, suggested next step. Never skip a failing task.
• A red-lane requirement discovered mid-build: STOP, escalate. Do not attempt it autonomously.
• A design/product decision: STOP, escalate to the user with the options, do not decide unilaterally. When the user rules, record the ruling in the runbook Decisions section before you resume.

Relationship to other skills

• dev-quick-build: the small-scope, human-present fast path that ALWAYS ships to prod on green. dev-auto-build is plan-driven and autonomous; it ships too, but only when deploy is authorised at kickoff (Phase 0), else it stops at push-ready. Both end by handing off to dev-qa-verify.
• Plan execution is folded in here directly. The task-by-task run, living-plan-file updates, checkpoints, and resume-from-last-task are part of dev-auto-build, the build-agent-powered, autonomous form (see the living-plan section above).
• repo-health-sweep: the first consumer; fans out across repos and calls dev-auto-build per failing repo.
• dev-deploy-safely / session-wrap: what the user runs AFTER dev-auto-build hands off the push-ready worktree - squash the wip commits into one clean commit (e.g. git reset --soft <base> && git commit) if you haven't already, then session-wrap integrates and closes out.
• dev-qa-verify: the shared closing verification gate (Phase 5).
• dev-debugging: the escape hatch a stuck bounded loop routes into - when a fix-run or review cycle fails twice for the same cause, run its isolate-with-evidence discipline before spending the last attempt.