PR Delivery Loop

PR Delivery Loop

This file contains the operating rules. Rationale and examples are optional reading for understanding a failure or the reasons behind a rule; do not load them routinely. They introduce no additional delivery gates.

Ownership and distribution

• The current user-started session is the orchestrator. A delegated lane's orchestrator is its dispatching session/callback target. Authority is user > orchestrator > this standard. Never delegate final review, orchestration, or merge approval to a newly spawned agent.
• The orchestrator decides clear, reversible, contract-preserving scope changes. Ask the user only for a major trade-off, irreversible risk, or genuinely ambiguous direction. A lane reports cross-scope gaps instead of editing peers.
• Avibe's .agents/skills/pr-delivery-loop/ is canonical; the project-level entry links to it. After canonical review passes, sync the whole maintained package, including references, byte-for-byte to each repository mirror. Inspect companion guidance and preserve unrelated files and edits.
• background-watch-hook owns managed waits, waiter scripts, cursor mechanics, retry/settle/filter behavior, and delivery acknowledgement. Load that skill before a managed wait. If unavailable, report the environment blocker; do not vendor or reimplement it in a repository. This skill owns delivery policy.

1. Scope, contracts, and implementation

• Continue an assigned branch/worktree after checking its head and authorship; unexplained new commits may belong to a live peer. Otherwise fetch origin and branch from GitHub's current default branch in a separate task worktree (.worktrees/avibe/<branch> in the multi-repo workspace). Preserve dirty work.
• Stay within assigned scope. No stacked PRs: declare dependencies on unmerged PRs and use default-branch contracts until those dependencies land.
• Before parallel lanes fork, commit shared interface and behavior contracts to the base branch. Specify exact fields and their producer, consumer, signer, and supplier as applicable, including what each signature covers. Audit the complete boundary flow before dispatch and after integration failures; isolated peer-mocked tests are not end-to-end evidence. Include real data and non-ASCII boundary cases.
• Contract deviations need orchestrator approval. At final rebase, refresh any externally owned spec from its authoritative current source, not an old copy. Do not leave a required contract as an untracked draft in the primary checkout.
• Treat allocated IDs as shared contracts. Before final integration, compare new migration revisions/chains and other allocated namespaces against the latest default branch; reconcile collisions even if Git reports no conflict.
• Cancellation is asynchronous. Before rerouting a lane, confirm the original stopped or explicitly notify both sessions of the handover. Do not create competing owners by treating a cancel request as completed termination.
• State acceptance criteria as invariants. Test all existing relevant shapes, including unchanged state; migrations need upgrade and downgrade checks. When a failure class is identifiable, cover the class, not only the example.
• Run focused tests and changed-file lint, plus required repository gates (npm run build for UI work). Self-review git diff origin/<default>...HEAD for scope drift, missing contracts, secrets, and temporary artifacts.
• CI owns the repository-wide required gates; never rerun the whole unit suite locally as a pre-push gate. Push and let the Watch observe CI. Flows CI does not cover (for example E2E, integration, or manual checks) still need their applicable verification. For a CI-only failure, first reproduce the failing CI command or file, then narrow. Remove temporary test directories you create.
• Claims about another lane's code name the SHA actually read from its current remote branch. Findings belong to their reviewed head; reconcile them against the current head before making another edit.

2. Open the PR and establish observation

• Open a non-draft PR with a type(scope): summary title and explicit --base <GitHub-default-branch>. Read back the title, body, and base. Use --body-file for multiline Markdown, not shell-interpolated backticks.
• Include capability/scope, applicable scenario IDs, validation layers, residual manual/E2E checks, dependencies, and a Known-by-design ledger for intentional non-changes. Reply to repeated intentional findings with that ledger entry.
• Use one durable combined PR + CI Watch per owner/concern through background-watch-hook: wait_pr.py, --forever, required --workflow names, optional --branch, and no fixed --sha during a normal delivery loop. Set --timeout 0 on both supervisor and waiter; do not impose a lifetime cap.
• Seed one complete owner-specific baseline and arm the Watch before the first watched push or review trigger. For a new PR, create it first, then immediately seed/arm before any subsequent push or explicit trigger. Never reseed, rotate, or replace the cursor between rounds. Recovery from an actual Watch failure is separate from routine delivery; retain evidence and follow the dependency.
• Keep that Watch live while pushing, replying, and resolving. During review, use management commands at each round's end to verify exactly one live Watch for this owner, PR, and concern, not merely a remembered ID. An independent orchestrator gate Watch is required for delegated work and has its own state; it is not a duplicate lane Watch. Verify the lane's observation is live too.
• Match every distinct Actions run ID for each required workflow at the current head and branch. Another matching run still pending or failed blocks CI, even if one run succeeded. Verify workflow names against actual runs. DIRTY plus absent CI calls for conflict diagnosis, not queue waiting.

3. Review, findings, and circuit breaking

Bind review evidence to the current head

• After each push, confirm current-head review pickup within a few minutes; otherwise post @codex review. While awaiting review, never pause without a pending review or a new trigger. Do not push another head during a pending review. Use wait time for acceptance, integration, and final-report preparation.
• Act on auto-review findings as inline reviews. A clean auto-review may pass only through the PR-body reaction; trigger review when a SHA-bearing pass comment is needed, rather than waiting for one to appear automatically.
• Save the trigger comment ID returned by your own write and read it back. Check that exact comment for the Codex bot's eyes reaction within about two minutes. Never select the last comment or search bodies for the trigger text. The reaction disappears after completion; its later absence is not failed pickup. PR-body eyes or a current-head verdict also provides live evidence.
• Accept only Codex-authored evidence (chatgpt-codex-connector, often rendered with [bot]). A comment-shaped pass must say Codex Review: Didn't find any major issues and name the current reviewed SHA. Reviewed commit alone is not a pass; findings reviews use it too.
• A Codex +1 on the PR body is a pass only when the original durable Watch captured it as new after the current head epoch began, the prior-head review was already terminal, and the head is unchanged. Never manufacture this boundary by reseeding. If the timeline cannot bind it, trigger review on the unchanged head and require a SHA-bearing verdict. A summary marked completed, another author's reaction, or an empty owner-authored review is not a pass.

Handle the full inventory before editing

• Fetch the current head, all paginated review threads/comments and verdicts, and all exact-head CI runs. Count distinct findings-bearing reviewed heads; classify by root cause, not by comment count. Include outdated threads.
• The orchestrator independently verifies that inventory and spot-checks a claimed root-cause fix in the diff and a consuming test each round. A lane's report or green tests cannot substitute for this check.
• Stop before another edit/push if a class appears on two reviewed heads. After an architecture/data-model rewrite, three findings-bearing heads without a clean pass also stop the loop, even for unrelated findings.
• A lane delivers the full inventory and waits for its orchestrator's decision. The orchestrator diagnoses the whole class, records the scope decision, and continues with the smallest complete fix that is clear, reversible, and contract-preserving; otherwise it escalates under the ownership rules above. The breaker stops blind patching, not the work: it does not prove a rewrite necessary, and no turn ends tripped without a next action or a delivered report.
• Fix actionable findings, reply, then resolve each addressed thread. If another person's pending review prevents a reply, never delete/dismiss it: preserve their drafts, report the blocker, keep observation live, and continue safe work. Retry the reply after they submit/discard it; do not hide the open thread.
• Internal round reports identify PR/head, findings addressed, and remaining gates in one or two lines. Do not add redundant round-summary PR comments.