Skip to content

Commit 526416b

Browse files
luisleo526claude
andauthored
Document the current CI job graph (#838)
Align AGENTS.md and CLAUDE.md with the current PR native build, post-merge shards and aggregate dependencies, and release runner labels. Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent e163980 commit 526416b

2 files changed

Lines changed: 20 additions & 12 deletions

File tree

‎AGENTS.md‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ While developing, run only the tests that touch your change. The whole suite run
4646
### What CI runs, per trigger
4747

4848
**Required to merge:** the commit statuses `pineforge/verify` (full `ci_verify.py` profiles on the PR head's exact tree) and `pineforge/parity` (no parity regression, or no engine behaviour change), ruleset `PineForge strict CI base`. No workflow in this repo posts them: the maintainers' private verification tooling does, and an outside contributor cannot; `release.yml` and `promote-baseline.yml` only read them. Every GitHub Actions job below is advisory for merging; `release.yml` also needs a fully green `CI post-merge` run on the release commit (`scripts/ci_release_gate.py`).
49-
GitHub Actions PR jobs give faster advisory feedback (a documentation-only change runs `admit`, `preflight` and the docs build, no proof legs); push-to-main and manual
49+
GitHub Actions PR jobs give faster advisory feedback (a documentation-only change runs `admit`, `preflight`, `build-x86-gcc133`, `result` and the docs build); push-to-main and manual
5050
dispatch run the full CI profiles. A campaign PASS verdict still binds the
5151
exact engine and codegen HEADs for baseline promotion.
5252

@@ -55,18 +55,22 @@ exact engine and codegen HEADs for baseline promotion.
5555
| Pull request | `ci.yml`: `authz` | admission only: our own non-fork PRs |
5656
| Pull request | `gke-pr.yml` (`pull_request_target`): `admit` | refuses forks, drafts and non-`main` bases; classifies the diff (docs-only, `.github/`-only, `arm_relevant`); `ci_preflight.py --rules-only` |
5757
| Pull request | `gke-pr.yml`: `preflight` | `python3 scripts/ci_preflight.py --tier fast`; `--tier github-only` (workflow checks only) when the diff is docs-only or `.github/`-only |
58+
| Pull request | `gke-pr.yml`: `build-x86-gcc133` | native x86 GNU 13.3.0 Release build via `scripts/ci_native_x86_release.py` on `ubuntu-24.04`; needs `admit`, runs for every admitted PR, including docs-only and `.github/`-only |
5859
| Pull request | `gke-pr.yml`: `build`, `build-debug` | Release / Debug: build target `pineforge_pr_smoke`, then `ctest -L '^fast$'` = the 11 executables of `PINEFORGE_PR_FAST_TESTS` in `tests/CMakeLists.txt` |
59-
| Pull request | `gke-pr.yml`: `build-arm`, `corpus-parity-subset`, `legs`, `result` | `build-arm`: `ci_verify.py debug` on arm64, only when `arm_relevant` (at least one changed path is neither documentation nor under `.github/`; `scripts/ci_docs_only.py`); `corpus-parity-subset`: `./scripts/check_corpus_parity.sh --subset` (54 probes); `legs`, `result` aggregate. Docs-only and `.github/`-only diffs skip `build`, `build-debug`, `build-arm`, `corpus-parity-subset` |
60+
| Pull request | `gke-pr.yml`: `build-arm`, `corpus-parity-subset`, `legs`, `result` | `build-arm`: `ci_verify.py debug` on `ubuntu-24.04-arm`, only when `arm_relevant` (at least one changed path is neither documentation nor under `.github/`; `scripts/ci_docs_only.py`); `corpus-parity-subset`: `./scripts/check_corpus_parity.sh --subset` (54 probes). `legs` needs `admit`, `build`, `build-debug`, `build-arm`, `build-x86-gcc133`, `corpus-parity-subset`; `result` needs `admit`, `preflight`, `build-x86-gcc133`, `legs` (both aggregates on `ubuntu-24.04`). Docs-only and `.github/`-only diffs skip `build`, `build-debug`, `build-arm`, `corpus-parity-subset`, `legs` |
6061
| Pull request | `docs.yml`: `authz`, `build` | Doxygen site build (`docs/build.sh`); not triggered by `.github/**`-only PRs |
6162
| Pull request | `prebuilt-hosted-diagnostic.yml`: `observe` | same-repository non-fork PR head only; records host identity, Docker versions and storage driver (no auth, pull, build or tests) |
62-
| Push to `main` | `ci-post.yml` ("CI post-merge"): `preflight`, `preflight-slow` | `ci_preflight.py --tier fast` and `--tier slow`; both also run on docs-only pushes |
63-
| Push to `main` | `ci-post.yml`: `build-shard (ubuntu-24.04, Release, N/4)`, `build-shard (ubuntu-24.04, Debug, N/2)`, `build (ubuntu-24.04-arm, Release)`, `build (ubuntu-24.04-arm, Debug)` | `ci_verify.py release --ctest-shard N/4`, `ci_verify.py debug --ctest-shard N/2`, and both profiles on arm64; gates `build (ubuntu-24.04, Release)`, `build (ubuntu-24.04, Debug)` |
63+
| Push to `main` | `ci-post.yml` ("CI post-merge"): `authz`, `changes`, `build-x86-gcc133` | all on `ubuntu-24.04`; `authz` admits events before checkout; `changes` and `build-x86-gcc133` each need `authz`. `changes` classifies docs-only and verifier self-test paths; `build-x86-gcc133` runs the native x86 GNU 13.3.0 Release build via `scripts/ci_native_x86_release.py`, including on docs-only pushes |
64+
| Push to `main` | `ci-post.yml`: `preflight`, `preflight-slow` | `ci_preflight.py --tier fast` and `--tier slow` on `ubuntu-24.04`; both need `authz`, `changes` and also run on docs-only pushes |
65+
| Push to `main` | `ci-post.yml`: `build`, `build-debug` (checks `build-shard (ubuntu-24.04, Release, N/4)`, `build-shard (ubuntu-24.04, Debug, N/2)`) | `ci_verify.py release --ctest-shard N/4`, `ci_verify.py debug --ctest-shard N/2` on `ubuntu-24.04`; both need `authz`, `changes`. Gates `build-release-gate` and `build-debug-gate` display `build (ubuntu-24.04, Release)` and `build (ubuntu-24.04, Debug)` |
66+
| Push to `main` | `ci-post.yml`: `build-arm` (checks `build-shard (ubuntu-24.04-arm, Release, N/4)`, `build-shard (ubuntu-24.04-arm, Debug, N/4)`) | `ci_verify.py release` and `debug`, each with `--ctest-shard N/4` on `ubuntu-24.04-arm`; Release also uses `--exclude-label ci-script`; needs `authz`, `changes` |
6467
| Push to `main` | `ci-post.yml`: `sanitizers-shard (N/8)`, `kernel-only-shard (N/2)` | `ci_verify.py sanitizers --ctest-shard N/8` (ASan + UBSan, **eight** shards, gate `sanitizers`); `ci_verify.py kernel --ctest-shard N/2` (Pine source layer OFF, gate `kernel-only`) |
65-
| Push to `main` | `ci-post.yml` calls `native-live.yml` and `corpus-parity.yml`; `build-gate` (check `build`) | `ci_verify.py native` in 4 shards, `live-sanitizers`, `live-tsan`; parity subset and the full 312-probe sweep (`corpus-parity-subset`, `corpus-parity`); `build-gate` aggregates every job above |
68+
| Push to `main` | `ci-post.yml` calls `native-live.yml` and `corpus-parity.yml` | `ci_verify.py native` in 4 shards, `live-sanitizers`, `live-tsan`; parity subset and the full 312-probe sweep (`corpus-parity-subset`, `corpus-parity`); each caller needs `authz`, `changes` |
69+
| Push to `main` | `ci-post.yml`: `build-gate` (check `build`, runner `ubuntu-24.04`) | aggregate needs `authz`, `changes`, `preflight`, `build`, `build-debug`, `build-release-gate`, `build-debug-gate`, `build-arm`, `build-x86-gcc133`, `sanitizers`, `sanitizers-gate`, `native-live`, `kernel-only`, `kernel-only-gate`, `corpus-parity-subset`, `preflight-slow`, `corpus-parity` |
6670
| Push to `main` | `docs-post.yml`, `promote-baseline.yml`, `rerun-preempted.yml` | docs build and deploy; baseline promotion (runs no tests); retry (attempt < 3) of runner-loss failures of a failed push or nightly `CI post-merge` run |
6771
| Nightly 01:30 UTC | `ci-post.yml`, `corpus-parity.yml` (cron `30 1 * * *`) | every `ci-post.yml` job, plus the `corpus-parity.yml` full sweep; the full sweep never runs on a PR |
6872
| Manual dispatch | `ci-post.yml` (`cold_native_cache`), `native-live.yml`, `corpus-parity.yml`, `docs-post.yml`, `promote-baseline.yml`, `release-ruleset-probe.yml` | the same jobs as push / nightly; `promote-baseline.yml` re-fires one promotion (five required inputs); the probe reads the branch rulesets |
69-
| Release | `release.yml` (dispatch only, no tag trigger): `release`, `prebuilt-x86`, `prebuilt-arm`, `upload`, `notify-hub` | `release` refuses unless both required statuses are green and the release commit's `CI post-merge` run is fully green (`scripts/ci_release_gate.py`), bumps `VERSION`, tags; hosted builds check staged versions and every library against v1.10.0 (no ctest), x86 alone authenticates the private toolchain and consumes its packed archive; `upload` re-hashes both artifacts against build outputs before publishing, then notify runs |
73+
| Release | `release.yml` (dispatch only, no tag trigger): `release`, `prebuilt-x86`, `prebuilt-arm`, `upload`, `notify-hub` | `prebuilt-arm` runs on `ubuntu-22.04-arm`, the other jobs on `ubuntu-24.04`. `release` refuses unless both required statuses are green and the release commit's `CI post-merge` run is fully green (`scripts/ci_release_gate.py`), bumps `VERSION`, tags; hosted builds check staged versions and every library against v1.10.0 (no ctest), x86 alone authenticates the private toolchain and consumes its packed archive; `upload` re-hashes both artifacts against build outputs before publishing, then notify runs |
7074

7175
### Local-only tests (no CI job runs them)
7276

‎CLAUDE.md‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ While developing, run only the tests that touch your change. The whole suite run
4646
### What CI runs, per trigger
4747

4848
**Required to merge:** the commit statuses `pineforge/verify` (full `ci_verify.py` profiles on the PR head's exact tree) and `pineforge/parity` (no parity regression, or no engine behaviour change), ruleset `PineForge strict CI base`. No workflow in this repo posts them: the maintainers' private verification tooling does, and an outside contributor cannot; `release.yml` and `promote-baseline.yml` only read them. Every GitHub Actions job below is advisory for merging; `release.yml` also needs a fully green `CI post-merge` run on the release commit (`scripts/ci_release_gate.py`).
49-
GitHub Actions PR jobs give faster advisory feedback (a documentation-only change runs `admit`, `preflight` and the docs build, no proof legs); push-to-main and manual
49+
GitHub Actions PR jobs give faster advisory feedback (a documentation-only change runs `admit`, `preflight`, `build-x86-gcc133`, `result` and the docs build); push-to-main and manual
5050
dispatch run the full CI profiles. A campaign PASS verdict still binds the
5151
exact engine and codegen HEADs for baseline promotion.
5252

@@ -55,18 +55,22 @@ exact engine and codegen HEADs for baseline promotion.
5555
| Pull request | `ci.yml`: `authz` | admission only: our own non-fork PRs |
5656
| Pull request | `gke-pr.yml` (`pull_request_target`): `admit` | refuses forks, drafts and non-`main` bases; classifies the diff (docs-only, `.github/`-only, `arm_relevant`); `ci_preflight.py --rules-only` |
5757
| Pull request | `gke-pr.yml`: `preflight` | `python3 scripts/ci_preflight.py --tier fast`; `--tier github-only` (workflow checks only) when the diff is docs-only or `.github/`-only |
58+
| Pull request | `gke-pr.yml`: `build-x86-gcc133` | native x86 GNU 13.3.0 Release build via `scripts/ci_native_x86_release.py` on `ubuntu-24.04`; needs `admit`, runs for every admitted PR, including docs-only and `.github/`-only |
5859
| Pull request | `gke-pr.yml`: `build`, `build-debug` | Release / Debug: build target `pineforge_pr_smoke`, then `ctest -L '^fast$'` = the 11 executables of `PINEFORGE_PR_FAST_TESTS` in `tests/CMakeLists.txt` |
59-
| Pull request | `gke-pr.yml`: `build-arm`, `corpus-parity-subset`, `legs`, `result` | `build-arm`: `ci_verify.py debug` on arm64, only when `arm_relevant` (at least one changed path is neither documentation nor under `.github/`; `scripts/ci_docs_only.py`); `corpus-parity-subset`: `./scripts/check_corpus_parity.sh --subset` (54 probes); `legs`, `result` aggregate. Docs-only and `.github/`-only diffs skip `build`, `build-debug`, `build-arm`, `corpus-parity-subset` |
60+
| Pull request | `gke-pr.yml`: `build-arm`, `corpus-parity-subset`, `legs`, `result` | `build-arm`: `ci_verify.py debug` on `ubuntu-24.04-arm`, only when `arm_relevant` (at least one changed path is neither documentation nor under `.github/`; `scripts/ci_docs_only.py`); `corpus-parity-subset`: `./scripts/check_corpus_parity.sh --subset` (54 probes). `legs` needs `admit`, `build`, `build-debug`, `build-arm`, `build-x86-gcc133`, `corpus-parity-subset`; `result` needs `admit`, `preflight`, `build-x86-gcc133`, `legs` (both aggregates on `ubuntu-24.04`). Docs-only and `.github/`-only diffs skip `build`, `build-debug`, `build-arm`, `corpus-parity-subset`, `legs` |
6061
| Pull request | `docs.yml`: `authz`, `build` | Doxygen site build (`docs/build.sh`); not triggered by `.github/**`-only PRs |
6162
| Pull request | `prebuilt-hosted-diagnostic.yml`: `observe` | same-repository non-fork PR head only; records host identity, Docker versions and storage driver (no auth, pull, build or tests) |
62-
| Push to `main` | `ci-post.yml` ("CI post-merge"): `preflight`, `preflight-slow` | `ci_preflight.py --tier fast` and `--tier slow`; both also run on docs-only pushes |
63-
| Push to `main` | `ci-post.yml`: `build-shard (ubuntu-24.04, Release, N/4)`, `build-shard (ubuntu-24.04, Debug, N/2)`, `build (ubuntu-24.04-arm, Release)`, `build (ubuntu-24.04-arm, Debug)` | `ci_verify.py release --ctest-shard N/4`, `ci_verify.py debug --ctest-shard N/2`, and both profiles on arm64; gates `build (ubuntu-24.04, Release)`, `build (ubuntu-24.04, Debug)` |
63+
| Push to `main` | `ci-post.yml` ("CI post-merge"): `authz`, `changes`, `build-x86-gcc133` | all on `ubuntu-24.04`; `authz` admits events before checkout; `changes` and `build-x86-gcc133` each need `authz`. `changes` classifies docs-only and verifier self-test paths; `build-x86-gcc133` runs the native x86 GNU 13.3.0 Release build via `scripts/ci_native_x86_release.py`, including on docs-only pushes |
64+
| Push to `main` | `ci-post.yml`: `preflight`, `preflight-slow` | `ci_preflight.py --tier fast` and `--tier slow` on `ubuntu-24.04`; both need `authz`, `changes` and also run on docs-only pushes |
65+
| Push to `main` | `ci-post.yml`: `build`, `build-debug` (checks `build-shard (ubuntu-24.04, Release, N/4)`, `build-shard (ubuntu-24.04, Debug, N/2)`) | `ci_verify.py release --ctest-shard N/4`, `ci_verify.py debug --ctest-shard N/2` on `ubuntu-24.04`; both need `authz`, `changes`. Gates `build-release-gate` and `build-debug-gate` display `build (ubuntu-24.04, Release)` and `build (ubuntu-24.04, Debug)` |
66+
| Push to `main` | `ci-post.yml`: `build-arm` (checks `build-shard (ubuntu-24.04-arm, Release, N/4)`, `build-shard (ubuntu-24.04-arm, Debug, N/4)`) | `ci_verify.py release` and `debug`, each with `--ctest-shard N/4` on `ubuntu-24.04-arm`; Release also uses `--exclude-label ci-script`; needs `authz`, `changes` |
6467
| Push to `main` | `ci-post.yml`: `sanitizers-shard (N/8)`, `kernel-only-shard (N/2)` | `ci_verify.py sanitizers --ctest-shard N/8` (ASan + UBSan, **eight** shards, gate `sanitizers`); `ci_verify.py kernel --ctest-shard N/2` (Pine source layer OFF, gate `kernel-only`) |
65-
| Push to `main` | `ci-post.yml` calls `native-live.yml` and `corpus-parity.yml`; `build-gate` (check `build`) | `ci_verify.py native` in 4 shards, `live-sanitizers`, `live-tsan`; parity subset and the full 312-probe sweep (`corpus-parity-subset`, `corpus-parity`); `build-gate` aggregates every job above |
68+
| Push to `main` | `ci-post.yml` calls `native-live.yml` and `corpus-parity.yml` | `ci_verify.py native` in 4 shards, `live-sanitizers`, `live-tsan`; parity subset and the full 312-probe sweep (`corpus-parity-subset`, `corpus-parity`); each caller needs `authz`, `changes` |
69+
| Push to `main` | `ci-post.yml`: `build-gate` (check `build`, runner `ubuntu-24.04`) | aggregate needs `authz`, `changes`, `preflight`, `build`, `build-debug`, `build-release-gate`, `build-debug-gate`, `build-arm`, `build-x86-gcc133`, `sanitizers`, `sanitizers-gate`, `native-live`, `kernel-only`, `kernel-only-gate`, `corpus-parity-subset`, `preflight-slow`, `corpus-parity` |
6670
| Push to `main` | `docs-post.yml`, `promote-baseline.yml`, `rerun-preempted.yml` | docs build and deploy; baseline promotion (runs no tests); retry (attempt < 3) of runner-loss failures of a failed push or nightly `CI post-merge` run |
6771
| Nightly 01:30 UTC | `ci-post.yml`, `corpus-parity.yml` (cron `30 1 * * *`) | every `ci-post.yml` job, plus the `corpus-parity.yml` full sweep; the full sweep never runs on a PR |
6872
| Manual dispatch | `ci-post.yml` (`cold_native_cache`), `native-live.yml`, `corpus-parity.yml`, `docs-post.yml`, `promote-baseline.yml`, `release-ruleset-probe.yml` | the same jobs as push / nightly; `promote-baseline.yml` re-fires one promotion (five required inputs); the probe reads the branch rulesets |
69-
| Release | `release.yml` (dispatch only, no tag trigger): `release`, `prebuilt-x86`, `prebuilt-arm`, `upload`, `notify-hub` | `release` refuses unless both required statuses are green and the release commit's `CI post-merge` run is fully green (`scripts/ci_release_gate.py`), bumps `VERSION`, tags; hosted builds check staged versions and every library against v1.10.0 (no ctest), x86 alone authenticates the private toolchain and consumes its packed archive; `upload` re-hashes both artifacts against build outputs before publishing, then notify runs |
73+
| Release | `release.yml` (dispatch only, no tag trigger): `release`, `prebuilt-x86`, `prebuilt-arm`, `upload`, `notify-hub` | `prebuilt-arm` runs on `ubuntu-22.04-arm`, the other jobs on `ubuntu-24.04`. `release` refuses unless both required statuses are green and the release commit's `CI post-merge` run is fully green (`scripts/ci_release_gate.py`), bumps `VERSION`, tags; hosted builds check staged versions and every library against v1.10.0 (no ctest), x86 alone authenticates the private toolchain and consumes its packed archive; `upload` re-hashes both artifacts against build outputs before publishing, then notify runs |
7074

7175
### Local-only tests (no CI job runs them)
7276

0 commit comments

Comments
 (0)