🤖 fix: clarify mandatory PR readiness criteria

[ThomasK33]

Summary

Clarifies PR workflow language so readiness requirements are unambiguous and mandatory for agents.

Background

The previous guidance allowed interpretation gaps around what "ready" means and when it is valid to stop iterating.

Implementation

• Added strict MUST-level readiness criteria in AGENTS.md.
• Updated .mux/skills/pull-requests/SKILL.md to require waiting for required checks before completion.
• Defined completion as Codex explicit approval + resolved Codex review threads + passing required CI checks.

Validation

• git diff --check
• make verify-vendor
• make test
• make build

---

📋 Implementation Plan

Plan: Make PR-ready waiting requirements unambiguous in agent guidance

Context / Why

The goal is to make both AGENTS.md and .mux/skills/pull-requests/SKILL.md explicitly MUST-level about waiting for PR readiness before declaring work complete. "Ready" must be concretely defined so agents cannot interpret it loosely.

Evidence

• AGENTS.md (## PR Workflow (Codex), lines 95–107): says "stay in this loop until ready" and lists steps, but does not define "ready" or use explicit "MUST NOT finish early" language.
• .mux/skills/pull-requests/SKILL.md:
  • ## CI & Validation (line 34) uses permissive wording: "you may use wait_pr_checks".
  • ### Required Loop Discipline (lines 83–91) says "stay in a review loop until completion" but does not define completion as Codex approval + required CI checks passing.

These are sufficient to justify tightening wording and adding explicit completion gates.

Implementation details

1. Edit AGENTS.md ## PR Workflow (Codex) to define readiness with hard requirements.

   • Add a short "PR readiness is mandatory" block immediately before the loop.
   • Define "ready" as all of the following:
     • Codex has explicitly approved.
     • No unresolved Codex review threads remain.
     • Required CI checks are passing.
   • Add a prohibition: do not claim completion / stop the loop before all conditions are true.

   > PR readiness is mandatory. You MUST keep iterating until the PR is fully ready.
   > A PR is fully ready only when: (1) Codex explicitly approves, (2) all Codex threads are resolved,
   > and (3) all required CI checks pass.
   > You MUST NOT report success or stop the loop before these conditions are met.

2. Edit AGENTS.md loop text to be imperative and unambiguous.

   • Change "stay in this loop until ready" to "you MUST remain in this loop until PR-ready conditions are met".
   • Keep the existing step order; optionally point to ./scripts/wait_pr_ready.sh <pr_number> as the default blocking command when done coding.

   When a PR exists, you MUST remain in this loop until the PR is fully ready:
   ...
   6. After explicit Codex approval, run `./scripts/wait_pr_checks.sh <pr_number>` and wait for required checks to pass.

3. Edit .mux/skills/pull-requests/SKILL.md in ## CI & Validation to distinguish optional vs required waits clearly.

   • Keep guidance that local validation should happen first.
   • Add explicit MUST for final readiness wait:

   - During active iteration, `wait_pr_checks` is optional.
   - Before declaring the PR complete, you MUST wait until required checks pass
     (prefer `./scripts/wait_pr_ready.sh <pr_number>` for Codex+CI end-to-end waiting).

4. Edit .mux/skills/pull-requests/SKILL.md ### Required Loop Discipline to define completion and forbid early stop.

   • Add one normative sentence before the numbered loop that completion is impossible until both Codex approval and required CI pass.
   • Add explicit "MUST NOT" language about responding as done before those conditions.

   Completion criteria are strict: you MUST continue the loop until Codex explicitly approves
   and all required CI checks pass. You MUST NOT mark work complete earlier.

5. Keep the existing narrow early-stop exception, but scope it as an exception to the MUST rule.

   • Retain the misunderstanding clause, but phrase as "only exception" and require pausing for human direction.

Validation approach

• Re-read the edited sections in both files and verify:
  • "MUST" language is present for waiting requirements.
  • "PR-ready" / completion is explicitly defined as Codex approval + CI pass (and thread resolution if included).
  • No contradictory permissive wording remains in those sections.

---

Generated with mux • Model: openai:gpt-5.3-codex • Thinking: xhigh • Cost: $0.12

[ThomasK33]

@codex review

Please review this docs-only update to PR readiness requirements.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 🎉

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ThomasK33]

https://mux.md/jtQfv#dcGagoposXyO-Q