Document pull request workflow and ownership

[ebhills]

What changed

• establishes GitHub as the PR-status system of record for ownership, review state, and next action
• defines one human delivery owner, recorded in the PR Assignees field, and one primary reviewer when the PR is ready
• documents Draft, Ready, changes-requested, re-review, resolution, approval, merge, branch cleanup, and daily/twice-weekly queue triage
• limits the active Ready-for-review queue to five PRs while allowing additional work to remain Draft
• makes Re-request review the explicit handoff after requested changes
• adds a Mermaid lifecycle diagram and locally stored screenshots of the relevant GitHub controls
• adds a repository PR template with ownership, readiness, validation, risk, scope, and description-freshness checks
• adds model-neutral AGENTS.md rules requiring explicit review dispositions and one to three actor-labeled next steps
• requires AI authors to keep the existing PR description synchronized with material branch changes
• defines main as the only integration branch for new work and documents clean recovery of wanted legacy dev changes
• distinguishes the DEV deployment environment from a Git integration branch
• aligns the release-lifecycle stub and Copilot instructions with the workflows introduced by Restructure CI/CD into ci, deploy-dev, and deploy-prod #1115: ci.yml, deploy-dev.yml, and publish-tagged.yml
• labels the remaining dev triggers and mutable-tag behavior as transitional work tracked by Complete and harden the main-based PR, dev deployment, and release lifecycle #1117

Why

The code-production bottleneck has moved to review, refinement, conflict resolution, and queue cleanup. The team needs GitHub to show ownership and who acts next across the Ukraine/Austin handoff. The documentation must also reflect the main-based integration decision without pretending that every transitional #1115 workflow behavior has already been removed.

Impact

New work branches from current main and targets main directly. The legacy dev branch is frozen for clean, one-change-at-a-time recovery rather than merged wholesale. Each open PR has one human owner, and owners use GitHub's native Draft, review-request, thread-resolution, and re-review signals to make the handoff explicit.

This PR changes documentation, templates, and agent behavior only. It does not modify runtime code or workflow implementation.

Validation

• merged current origin/main, including Restructure CI/CD into ci, deploy-dev, and deploy-prod #1115, without conflicts
• confirmed the branch is zero commits behind main
• verified the PR diff against main contains only the intended lifecycle documentation, template, agent instructions, and image assets
• replaced the hard-coded v1.20 saved search with a current-milestone placeholder and update instruction
• replaced the PR-template relative documentation link with an absolute repository link that resolves from PR bodies
• verified all referenced workflow and documentation paths exist
• verified balanced Markdown fences and ran git diff --check
• retained the existing release-lifecycle stub while linking the remaining implementation work to Complete and harden the main-based PR, dev deployment, and release lifecycle #1117

Documentation/instruction-only change; no runtime tests were required.

[ebhills]

The limit of five is not a GitHub rule. It’s an initial team-wide WIP limit based on your capacity:
2 Austin reviewers × roughly 1–1.5 review decisions per day × 2-day maximum wait ≈ 4–6 PRs

Five is the midpoint: approximately two PRs per reviewer plus one urgent or overflow slot.
The purpose is to:

• Keep “Ready” meaningful: a reviewer can act immediately.
• Prevent review requests from accumulating faster than Austin can process them.
• Reduce branch staleness and merge conflicts while PRs wait.
• Encourage finishing and merging before starting additional work.
• Make the five visible PRs the team’s immediate priorities.
• It does not mean Mariia can only have five PRs open. Additional work can remain Draft without demanding reviewer attention. And a PR with Changes Requested is author-action work, not part of the active review queue until the fixes are pushed and review is re-requested.

After two weeks, adjust based on evidence:
If five are consistently reviewed within one business day, try six.
If PRs wait multiple days or become stale, reduce it to three or four.
If PRs vary greatly in size, count a large architectural PR as two review slots.
The actual objective is not “five.” It is keeping the review queue small enough that every Ready PR receives a timely decision.

[Copilot]

Pull request overview

Adds repository-wide pull request workflow and AI-agent guardrails to make GitHub the single source of truth for PR state/ownership, and to standardize review outputs and PR descriptions for smoother Ukraine/Austin handoffs.

Changes:

• Add docs/pull-request-workflow.md defining PR states, ownership, queue limits, and triage routines.
• Add AGENTS.md requiring Codex reviews to state a disposition plus 1–3 actor-labeled next steps, and to keep PR descriptions current.
• Add a PR template and align .github/copilot-instructions.md with the new workflow/review policy language.

Recommended disposition: Request changes

Next steps

1. PR author: Update docs/pull-request-workflow.md to avoid hard-coding milestone:"v1.20" and update .github/pull_request_template.md to use a repo-relative link that works when rendered in PR bodies.
2. Reviewer: Verify the updated template link works in an actual PR body preview and that the “Release PRs” search is future-proof, then re-review and approve.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
docs/pull-request-workflow.md	New documented PR state/ownership workflow, queue limits, and triage/search routines.
AGENTS.md	New agent rules for dispositions/next-steps blocks and PR-description freshness.
.github/pull_request_template.md	New PR template prompting for linkage, validation, risk, and readiness checklist.
.github/copilot-instructions.md	Updates/extends Copilot guidance to match the documented workflow and review policy.