🤖 fix: clarify mandatory PR readiness criteria (#9)

## 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`

---

<details>
<summary>📋 Implementation Plan</summary>

# 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.

   ```md
> 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.

   ```md
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:

   ```md
   - 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.

   ```md
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.

</details>

---
_Generated with `mux` • Model: `openai:gpt-5.3-codex` • Thinking:
`xhigh` • Cost: `$0.12`_

<!-- mux-attribution: model=openai:gpt-5.3-codex thinking=xhigh
costs=0.12 -->

Author: ThomasK33

.mux/skills/pull-requests/SKILL.md

@@ -31,10 +31,11 @@ Always check `$MUX_MODEL_STRING`, `$MUX_THINKING_LEVEL`, and `$MUX_COSTS_USD` vi
 
 ## CI & Validation
 
-- After pushing, you may use `./scripts/wait_pr_checks.sh <pr_number>` to wait for CI to pass.
-- Use `wait_pr_checks` only when there's no more useful work to do.
+- During active iteration, using `./scripts/wait_pr_checks.sh <pr_number>` is optional.
+- Before declaring a PR complete, you MUST wait until all required checks pass.
+- When you are done coding and want end-to-end readiness waiting, prefer `./scripts/wait_pr_ready.sh <pr_number>` (Codex wait first, CI checks second).
 - Waiting for PR checks can take 10+ minutes, so prefer local validation first (for this repo: `make verify-vendor`, `make test`, `make build`) to catch issues early.
-- If asked to fix an issue in CI, first replicate it locally, get it to pass locally, then use `wait_pr_checks` to wait for CI to pass.
+- If asked to fix an issue in CI, first replicate it locally, get it to pass locally, then wait for required CI checks to pass.
 
 ## Status Decoding
 
@@ -80,15 +81,17 @@ When Codex leaves review comments, you **must** address them before the PR can m
 
 ### Required Loop Discipline
 
-After a PR is open, stay in a review loop until completion:
+Completion criteria are strict: you MUST continue this loop until Codex explicitly approves, all Codex review threads are resolved, and all required CI checks pass. You MUST NOT mark work complete earlier.
+
+After a PR is open, you MUST stay in a review loop until those completion criteria are met:
 
 1. Run local validation and push fixes.
 2. Request review with `@codex review`.
 3. Run `./scripts/wait_pr_codex.sh <pr_number>` and wait for Codex to respond.
 4. If Codex leaves comments, address them, resolve each thread, push, and repeat from step 2.
-5. Once Codex explicitly approves, run `./scripts/wait_pr_checks.sh <pr_number>` and wait for required checks.
+5. Once Codex explicitly approves, run `./scripts/wait_pr_checks.sh <pr_number>` and wait for required checks to pass.
 
-Only stop the loop early if a reviewer is clearly misunderstanding the change intent and further edits would be counterproductive. In that case, leave a clarifying PR comment and pause for human direction.
+The only early-stop exception is when a reviewer is clearly misunderstanding the change intent and further edits would be counterproductive. In that case, leave a clarifying PR comment and pause for human direction.
 
 ## PR Title Conventions
 

AGENTS.md

@@ -96,12 +96,16 @@ Run from repository root.
 - Use `./scripts/wait_pr_ready.sh <pr_number>` for a one-command wait flow after requesting review.
 - Prefer `gh` CLI for GitHub interactions over manual web/curl flows.
 
-When a PR exists, stay in this loop until ready:
+> 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 review threads are resolved, and (3) all required CI checks pass.
+> You MUST NOT report success or stop the loop before these conditions are met.
+
+When a PR exists, you MUST remain in this loop until the PR is fully ready:
 1. Push your latest fixes.
 2. Run local validation (`make verify-vendor`, `make test`, `make build`).
 3. Request review with `@codex review`.
 4. Run `./scripts/wait_pr_codex.sh <pr_number>` and wait for Codex.
 5. If Codex leaves comments, address them, resolve threads with `./scripts/resolve_pr_comment.sh <thread_id>`, push, and repeat.
-6. After explicit Codex approval, run `./scripts/wait_pr_checks.sh <pr_number>`.
+6. After explicit Codex approval, run `./scripts/wait_pr_checks.sh <pr_number>` and wait for required checks to pass.
 
-Only stop the loop early if the reviewer is clearly misunderstanding the intended change and further churn would be counterproductive. In that case, leave a clarifying PR comment and wait for human direction.
+The only early-stop exception is when the reviewer is clearly misunderstanding the intended change and further churn would be counterproductive. In that case, leave a clarifying PR comment and pause for human direction.