feat(review): the local review leaves its findings for an agent and reviews again what changed

.github/workflows/pull-request.yml

@@ -54,6 +54,28 @@ jobs:
       - run: bash scripts/local-review.sh --test
       - run: python3 scripts/policy.py --test
 
+  # The scripts a contributor runs on their own machine, on a stock macOS:
+  # its bash is 3.2 and its tools are BSD's, so what only works with GNU
+  # tools (sha256sum, sed -i without a suffix, …) fails here, not on a
+  # contributor's laptop.
+  scripts-macos:
+    name: Scripts on macOS (the contributor's tools)
+    runs-on: macos-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      # Every `bash` the scripts call is the stock one too, not Homebrew's.
+      - run: |
+          mkdir -p "$RUNNER_TEMP/stock" && ln -sf /bin/bash "$RUNNER_TEMP/stock/bash"
+          echo "$RUNNER_TEMP/stock" >> "$GITHUB_PATH"
+      - run: bash --version | head -1
+      - run: /bin/bash scripts/conventions.sh --test
+      - run: /bin/bash scripts/review-brief.sh --test
+      - run: /bin/bash scripts/local-review.sh --test
+      - run: python3 scripts/policy.py --test
+
   review:
     needs: [conventions, actionlint, scripts]
     permissions:

AGENTS.md

@@ -21,7 +21,9 @@ Rules for any coding agent working in `DiluxOne/.github`.
   `🤖 AI-generated · Claude Opus 5.5 (Anthropic)`. Never "Generated with …".
 - Never push to `main`, create or move tags, or change organisation settings.
 - Before a pull request exists, run `scripts/local-review.sh` (CONTRIBUTING.md,
-  "Review before the pull request") and fix what it finds. Do not push, open a
+  "Review before the pull request"), fix every blocker and major listed in
+  `.git/dx-review/findings.md` (and the minors that are cheap), commit, and
+  run it again until it says "Ready for a pull request". Do not push, open a
   pull request or re-run a workflow unless the maintainer asked for it: every
   push to an open pull request is a paid review.
 - A problem a review finds (local or on GitHub) that a test could have

CONTRIBUTING.md

@@ -54,13 +54,13 @@ CI fails a pull request whose "What changes" or "Why" is empty (bots' are exempt
 
 ## Review before the pull request
 
-[`scripts/local-review.sh`](scripts/local-review.sh) runs, on your machine, what the pull request will be checked on: the conventions ([`scripts/conventions.sh`](scripts/conventions.sh), the same script CI runs), the risk floor ([`scripts/policy.py`](scripts/policy.py)), and the Claude review on the same brief ([`scripts/review-brief.sh`](scripts/review-brief.sh): the review profiles, the repository's `AGENTS.md` and `docs/architecture.md`, the description and the diff), through the Claude Code CLI on your own account. From the repository, with a checkout of this one:
+[`scripts/local-review.sh`](scripts/local-review.sh) runs, on your machine, what the pull request will be checked on: the conventions ([`scripts/conventions.sh`](scripts/conventions.sh), the same script CI runs), the risk floor ([`scripts/policy.py`](scripts/policy.py)), and the Claude review on the same brief ([`scripts/review-brief.sh`](scripts/review-brief.sh): the review profiles, the repository's `AGENTS.md` and `docs/architecture.md`, the description and the diff), through the Claude Code CLI on your own account. It needs git, bash (the 3.2 of macOS will do), jq, python3 with yq or PyYAML (`brew install jq yq` on macOS) and, for the review itself, the Claude Code CLI. From the repository, with a checkout of this one:
 
 ```bash
 bash ../.github/scripts/local-review.sh --body-file pr.md   # the description you will paste
 ```
 
-The docs check CI also runs (relative links resolve, no retired product name) is not part of it. It reviews the branch against `origin/main`; the title is the branch's only commit, or `--title`. It ends with "Ready for a pull request" or with what to fix; `--no-claude` stops at the brief, for another reviewer or agent to read. A repository may wrap it in its own target (for a plugin, `make pre-pr`, which also runs the test suites). CI still reviews the pull request: a branch that came out clean here should pass there in one round.
+The docs check CI also runs (relative links resolve, no retired product name) is not part of it. It reviews the branch against `origin/main`; the title is the branch's only commit, or `--title`. It ends with "Ready for a pull request" or "Not ready" for what would stop the pull request on GitHub: a broken convention, a blocker or a major, a description the review says does not match the code, a title of another type than the change (on GitHub the review would retitle it). The findings go to `.git/dx-review/findings.md` (never committed), a list to fix; commit the fixes and run it again: like the review on a pull request, the next run reads only what changed since, sees the earlier findings and says which are fixed (`--full` reviews everything again; a run with nothing new since (same commit, title, description, model, profile and base) answers from the file without spending a review; `--model <id>` asks another model than the policy's). `--no-claude` stops at the brief, for another reviewer or agent to read. A repository may wrap it in its own target (for a plugin, `make pre-pr`, which also runs the test suites). CI still reviews the pull request: a branch that came out clean here should pass there in one round.
 
 ## What CI checks
 

README.md

@@ -157,7 +157,7 @@ Call them pinned to `@v2`; a breaking change ships as `v2`. A stack suffix
 | [`auto-merge.yml`](.github/workflows/auto-merge.yml) | Turns GitHub's auto-merge on or off from the review's outputs and commits the description verbatim. `pull-request-edited.yml` runs it on `edited` too. | the five review outputs |
 | [`scripts/conventions.sh`](scripts/conventions.sh) | Not a workflow: the conventions a pull request is held to (branch, title, every commit header, no session trailer, description sections, no "Generated with" footer). `conventions.yml` runs it on a pull request, `local-review.sh` before one; `--test` for its own tests. | env: `BRANCH`, `TITLE`, `BODY`, `BASE`, `HEAD_REF`, `MAX_HEADER`, `SECTIONS`, `LABELS`, `AUTHOR_TYPE` |
 | [`scripts/review-brief.sh`](scripts/review-brief.sh) | Not a workflow: the review brief, the one file the Claude review reads (profiles, `AGENTS.md`, `docs/architecture.md`, policy floor, description, diff). `claude-review.yml` and `local-review.sh` build it with the same script; `--test` for its own tests. | env: see the script's header |
-| [`scripts/local-review.sh`](scripts/local-review.sh) | Not a workflow: the pull request's checks before it exists, on a contributor's machine: conventions, policy floor, brief, and the review through the local Claude Code CLI. See CONTRIBUTING.md, "Review before the pull request"; `--test` for its own tests (never runs the review). | `--base`, `--title`, `--body-file`, `--profile`, `--no-claude` |
+| [`scripts/local-review.sh`](scripts/local-review.sh) | Not a workflow: the pull request's checks before it exists, on a contributor's machine: conventions, policy floor, brief, and the review through the local Claude Code CLI; the findings go to `.git/dx-review/findings.md` and the next run is incremental. See CONTRIBUTING.md, "Review before the pull request"; `--test` for its own tests (never runs the review). | `--base`, `--title`, `--body-file`, `--profile`, `--no-claude`, `--full`, `--model` |
 | [`scripts/release-ready.sh`](scripts/release-ready.sh) | Not a workflow: whether a readme's newest changelog entry is ready (exit 0) or held by a first line `Unreleased.` (exit 1); `--test` for its own tests. The release job's hold. | the readme |
 | [`scripts/release-markers.sh`](scripts/release-markers.sh) | Not a workflow: `check` holds the three version markers to a real version (the last one released, or the next one in the pull request that releases it and on `main` after it merged; the checks' readme job and the release job run it); `prepare` turns a tree into its release pull request (removes the `Unreleased.` line, stamps the markers); `--test` for its own tests. | `check <dir> <main-file> <constant> <last> <next> <pending>`, `prepare <dir> <version> <main-file> [<constant>]` |
 | [`scripts/stamp-version.sh`](scripts/stamp-version.sh) | Not a workflow: stamps a plugin tree with a version (the `Version:` header, the constant, `Stable tag:`, a `= Unreleased =` heading; with a build, a `Build:` header line) and fails when a marker did not take it. The release and the development build stamp with it; `--test` for its own tests. | `<dir> <version> <main-file> [<constant>] [<build>]` |

policy/review-policy.default.yml

@@ -63,8 +63,9 @@ low-risk-eligible:
   - "composer.lock"
   - ".wordpress-org/**"
   - "languages/*.po"
-  - "languages/*.mo"
   - "languages/*.pot"
+  # Not languages/*.mo: compiled, it ships in the plugin, and the reviewer
+  # cannot read it (it is left out of the brief), so a person approves it.
 
 # What counts as code: a pull request that changes none of these runs only
 # the fast checks and the review; the slow suites (integration, end-to-end,