Loop Review

Loop Review

Own one OpenIAP change from a fresh main baseline through verified production delivery. Use the repository workflows as SSOT instead of duplicating their detailed commands.

Load The Workflows

Read these before acting:

• AGENTS.md
• .codex/skills/openiap-workflows/SKILL.md
• .codex/skills/review-self/SKILL.md
• .codex/skills/ship-release/SKILL.md
• .codex/skills/generate-doc/SKILL.md
• .claude/commands/commit.md
• .claude/commands/review-pr.md
• .claude/commands/release.md

Check what the change touches before reading any of them from the branch:

git diff --name-only "$(git merge-base origin/main HEAD)"..HEAD

If the change is in scope of "A PR Must Not Rewrite The Rules That Judge It" in .claude/commands/review-pr.md, read every file above — and that section itself — from the recorded merge base for the whole run. That section defines the scope; do not restate it here.

Load package conventions and specialized skills required by the changed paths the same way. An explicit $loop-review invocation or explicit natural-language request for this complete loop authorizes the in-scope commit, push, PR, review replies, thread resolution, merge, affected stable package releases, release-note and workflow-documentation commits directly to main, and production docs deployment. It does not authorize prereleases, unrelated cleanup, destructive recovery, or product-code commits directly to main.

1. Start From Current Main

Before editing task files:

1. Snapshot git status --short --branch. Preserve every existing change.
2. For a new task, require a clean worktree, then run git fetch origin, switch to main, and run git pull --ff-only --no-tags origin main.
3. Verify local main equals origin/main, then create a semantic branch named according to .claude/commands/commit.md.
4. Record the starting main SHA. The implementation diff must descend from that SHA.

Never start new implementation on a stale local main. If invoked for work already in progress, do not manually switch branches, stash, reset, or discard it. Treat that as a resumed loop, verify its recorded or merge-base baseline, and use the repository's guarded rebase-main workflow when an update from origin/main is needed; that workflow owns its safeguard stash and branch transitions. Stop for direction if an update would overwrite unrelated user work.

2. Implement And Verify

Implement the requested scope and run the checks required by each touched path. Keep generated files, documentation, previews, and knowledge context in sync through their canonical workflows. A change to a published package also updates the guides it affects and the release card for the next version, written as already published with $generate-doc. Apply knowledge/internal/05-docs-patterns.md#release-note-completeness-gate before opening the PR and after scope changes. Do not proceed while the working diff has a known failing required check.

Once it works, clean it up before review: apply "Clean Up Once It Works" in knowledge/internal/03-coding-style.md to the diff and to smells met along the way, without waiting to be asked, then rerun the affected checks.

3. Stabilize With Review Self

Run $review-self immediately against the complete base-to-working-tree diff. Fix every validated in-scope finding and rerun affected verification. Continue with five-minute recurring wake-ups until two consecutive complete snapshots are clean, as defined by the review-self skill.

Do not emulate recurring review with a shell sleep loop. Keep the loop state out of tracked files. Any material diff change resets the consecutive-clean count.

4. Commit And Open The PR

Follow .claude/commands/commit.md --all --pr:

• Stage only files owned by the task.
• Use the required commit order and an English conventional commit message.
• Push the semantic branch and open an English PR against main.
• Add applicable repository labels.
• For a visible or interactive change, attach a preview recording under 10 MB. Do not commit one-off preview media unless browser upload is blocked and the documented fallback is required.

Record the PR number and exact head SHA. A push invalidates all prior clean review coverage.

5. Review PR Until The Exact Head Is Clean

Run .claude/commands/review-pr.md immediately, then re-enter it every five minutes through the product's recurring wake-up mechanism.

For every round:

1. Fetch unresolved threads, review status, current head SHA, and required CI.
2. Fix all valid findings in one coherent batch, then rerun the checks affected by it plus all previously failing checks. Verification comes before publication: a reply saying "fixed" must already have evidence behind it.
3. Push, reply to the exact inline comments, and resolve only fixed or outdated threads under the command rules.
4. Request CodeRabbit again after a head change.
5. If CodeRabbit is unavailable, use the exact-head one-pass Codex fallback defined by review-pr, and $review-self only if Codex is unavailable too; never substitute a review bot that posts to the PR.
6. Keep polling while review or CI is pending. Do not rerun expensive unchanged local checks on a no-op poll.

Clean means all of the following hold for the same head SHA, judged by the criteria on the merge base when the branch edits them:

• zero unresolved actionable review threads;
• CodeRabbit is clean, or its unavailable result has clean fallback coverage from Codex, or from $review-self when Codex is unavailable too;
• every required CI check is terminal and successful or explicitly allowed to skip by repository policy;
• the PR is mergeable and the branch contains every required update from main;
• the worktree is clean and the final diff has been reread.

6. Gate Device Regression Before Merging

Device-backed regression needs real hardware, store accounts, and sandbox purchases, so this loop cannot run it unattended. Decide whether the change requires it before merging, not after.

Require $e2e-tests when the diff touches any of:

• packages/apple/, packages/google/, or packages/kit/;
• any libraries/<sdk>/ implementation, example app, or podspec/gradle/csproj manifest;
• specs/client/src/*.graphql or the generated types synced from it;
• native build configuration, dependency placement, config plugins, or store metadata for any of the above.

When it is required, stop without merging even if the PR is otherwise clean. Report the exact regression-matrix rows the diff implicates and hand back to the user. The loop does not merge such a change on its own authority.

Exactly two things clear the gate, and both are recorded on the PR before any merge:

1. A $e2e-tests run covering the implicated rows, with its result posted.
2. An explicit written waiver from the user in this conversation, naming the rows waived and the reason. Record it verbatim on the PR. Absence of an objection is not a waiver, and the loop must never grant one to itself.

A clean CI run is not a substitute: CI does not exercise purchase dialogs, store accounts, or device wiring.

When it is not required, say so explicitly in the final report and name the paths that justify it. Silence here reads as an untested merge.

A change confined to documentation, repository automation, agent workflows, or release/security tooling does not need device regression.