Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 4 additions & 14 deletions .github/workflows/engine.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,23 +5,13 @@ on:
# build, vet, unit tests and the fast helper suites on both supported engine
# platforms. Core race tests and real service scenarios stay on manual
# dispatch and on the tag-driven release workflow.
# The pull request is the only automatic trigger: `main` accepts pull
# requests only, so a push cannot skip this check, and the merge commit
# carries the tree that just passed. Nightly and release tags run the full
# gate instead of a second copy on every merge.
# No path filter here: a skipped path-filtered workflow leaves a required
# check pending and blocks the PR.
pull_request:
push:
branches: [main]
paths:
- 'engine/**'
- 'docs/cli.md'
- 'docs/cli.zh.md'
- 'magefiles/**'
- 'scripts/**'
- 'install.sh'
- 'install.ps1'
- 'uninstall.sh'
- 'uninstall.ps1'
- '.github/workflows/engine.yml'
- '.github/workflows/release.yml'
workflow_dispatch:

permissions:
Expand Down
9 changes: 2 additions & 7 deletions .github/workflows/examples.yml
Original file line number Diff line number Diff line change
@@ -1,15 +1,10 @@
name: Checked-in examples
on:
# The pull request is the only automatic trigger: `main` accepts pull
# requests only, so a push cannot skip this check.
# No path filter on pull_request: a skipped required workflow leaves its
# check pending and blocks the PR.
pull_request:
push:
branches: [main]
paths:
- 'examples/**'
- 'engine/**'
- 'scripts/smoke.py'
- '.github/workflows/examples.yml'
workflow_dispatch:
permissions:
contents: read
Expand Down
11 changes: 2 additions & 9 deletions .github/workflows/git-read.yml
Original file line number Diff line number Diff line change
@@ -1,18 +1,11 @@
name: Git read verification

on:
# The pull request is the only automatic trigger: `main` accepts pull
# requests only, so a push cannot skip this check.
# No path filter on pull_request: a skipped required workflow leaves its
# check pending and blocks the PR.
pull_request:
push:
branches: [main]
paths:
- 'engine/internal/git/**'
- 'engine/internal/groups/**'
- 'engine/internal/scanner/**'
- 'engine/go.mod'
- 'engine/go.sum'
- '.github/workflows/git-read.yml'
workflow_dispatch:

permissions:
Expand Down
8 changes: 2 additions & 6 deletions .github/workflows/readiness.yml
Original file line number Diff line number Diff line change
@@ -1,14 +1,10 @@
name: Reused service readiness
on:
# The pull request is the only automatic trigger: `main` accepts pull
# requests only, so a push cannot skip this check.
# No path filter on pull_request: a skipped required workflow leaves its
# check pending and blocks the PR.
pull_request:
push:
branches: [main]
paths:
- 'engine/**'
- 'scripts/verify-reused-readiness.py'
- '.github/workflows/readiness.yml'
workflow_dispatch:
permissions:
contents: read
Expand Down
14 changes: 5 additions & 9 deletions .github/workflows/windows.yml
Original file line number Diff line number Diff line change
@@ -1,17 +1,13 @@
name: Windows build verification
on:
# The PR gate must run the native Windows path, not only the PowerShell
# parse job in the engine workflow. No path filter on pull_request: a
# skipped required workflow leaves its check pending and blocks the PR.
# parse job in the engine workflow. The pull request is the only automatic
# trigger: `main` accepts pull requests only, so a push cannot skip this
# check. Release tags call this workflow and run it again.
# No path filter on pull_request: a skipped required workflow leaves its
# check pending and blocks the PR.
workflow_call:
pull_request:
push:
branches: [main]
paths:
- 'engine/**'
- 'install.ps1'
- 'uninstall.ps1'
- '.github/workflows/windows.yml'
workflow_dispatch:
permissions:
contents: read
Expand Down
6 changes: 3 additions & 3 deletions docs/agent/develop.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,9 +54,9 @@ go vet ./...
go test -count=1 -timeout=8m ./...
```

PRs and pushes to `main` run these three on macOS/Linux automatically, along with the Mage and Python
helper tests, plus a native build and script parsing on Windows; the Linux job also cross-builds six
release targets with `CGO_ENABLED=0`. The full gates — core race tests, real service scenarios — still
PRs run these three on macOS/Linux automatically, along with the Mage and Python helper tests, plus
a native build and script parsing on Windows; the Linux job also cross-builds six release targets
with `CGO_ENABLED=0`. The full gates — core race tests, real service scenarios — still
run per [validation.md](validation.md) on the daily, manual or release paths. CI-configuration changes
also run actionlint and the required-checks consistency check; the list is in
`.github/quality-gate-checks.json`.
Expand Down
4 changes: 2 additions & 2 deletions docs/agent/releasing.md
Original file line number Diff line number Diff line change
Expand Up @@ -183,8 +183,8 @@ scenario, or native execution on Windows arm64.
## Preflight before tagging

The automated release CI runs `Verified release` (verify, package, publish) only when a **`v*` annotated
tag** matching `VERSION` is pushed; the automatic gates on PRs and `main` pushes cover build, vet, unit
tests and helper-script tests, as described in [validation.md](validation.md). The daily
tag** matching `VERSION` is pushed; the automatic gates on pull requests cover build, vet, unit tests
and helper-script tests, as described in [validation.md](validation.md). The daily
`Nightly full verification` runs the release-equivalent full gate set on the default branch; confirm it
passes before tagging so problems that only surface there are not left for after the release. To rerun
locally, use `python3 scripts/release.py --verify-only`; it reads only the currently checked-out commit.
Expand Down
33 changes: 17 additions & 16 deletions docs/agent/validation.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,28 +2,29 @@

All current workflows record the actual source identity; a check's conclusion applies only to the
commit that was run, and never reuses historical results from an old repository or this machine.
The automated gates have two layers. `Engine verification` runs on macOS / Ubuntu on PRs and pushes
to `main`: native build, vet, full engine unit tests, Mage workflow regression, and the Python
The automated gates have two layers. `Engine verification` runs on macOS / Ubuntu on every pull
request: native build, vet, full engine unit tests, Mage workflow regression, and the Python
helper tests, and parses `install.ps1` / `uninstall.ps1` on Windows with Windows PowerShell 5.1.
`Windows build verification` runs on PRs and engine-related pushes to `main`: Windows x64 native
build, CLI smoke, script parsing, service lifecycle, and fact/persistence checks, plus a Windows
arm64 cross build on Ubuntu. Core race and real-service scenarios run only under a manual
`workflow_dispatch`, in the daily `Nightly full verification`, and in `Verified release` when an
annotated `v*` tag is pushed. Site changes are verified by `.github/workflows/site.yml` on PRs and
pushes to `main`. To run one check on its own, manually `workflow_dispatch` the corresponding
workflow in Actions; to re-run locally before a release, use `python3 scripts/release.py
--verify-only`.
`Windows build verification` runs on every pull request: Windows x64 native build, CLI smoke,
script parsing, service lifecycle, and fact/persistence checks, plus a Windows arm64 cross build on
Ubuntu. `main` accepts pull requests only, so a push cannot skip these checks, and the merge commit
carries the tree that just passed; the gates do not run a second time on the merge. Core race and
real-service scenarios run only under a manual `workflow_dispatch`, in the daily `Nightly full
verification`, and in `Verified release` when an annotated `v*` tag is pushed. Site changes are
verified by `.github/workflows/site.yml` on PRs and pushes to `main`. To run one check on its own,
manually `workflow_dispatch` the corresponding workflow in Actions; to re-run locally before a
release, use `python3 scripts/release.py --verify-only`.

| Workflow | Trigger | Platforms and contents |
|---|---|---|
| Engine verification | PRs, engine-related pushes to `main`, manual | Automated: macOS / Ubuntu native build, vet, full engine unit tests, Mage workflow regression, Python helper tests, cross builds for the six release targets on Ubuntu, a checkout of `option-berth-skill` on Linux to verify agent contract coverage, and parsing of the install/uninstall scripts with Windows PowerShell 5.1. Manual runs additionally execute core race and real-service scenarios. |
| Engine verification | PRs, manual | Automated: macOS / Ubuntu native build, vet, full engine unit tests, Mage workflow regression, Python helper tests, cross builds for the six release targets on Ubuntu, a checkout of `option-berth-skill` on Linux to verify agent contract coverage, and parsing of the install/uninstall scripts with Windows PowerShell 5.1. Manual runs additionally execute core race and real-service scenarios. |
| Nightly full verification | Daily 18:23 UTC, manual | macOS / Ubuntu: the same full gate as `scripts/release.py --verify-only`, including core race and real-service scenarios. |
| Git read verification | PRs, related pushes to `main`, manual | macOS / Ubuntu: repeated tests and race for Git, worktree, attribution, and observation. |
| Checked-in examples | PRs, engine-related pushes to `main`, manual | macOS / Ubuntu: the minimal sample `hello-worktree` across two worktrees (distinct ports, a portless worker, stopping one side). No Docker, no benchmark. The complex sample `stack-workshop` is not part of this check; it is the input of the manual benchmark, which runs on Linux with Docker. |
| Reused service readiness | PRs, engine-related pushes to `main`, manual | macOS / Ubuntu: reuse checks against real healthy and unhealthy services. |
| Windows build verification | PRs, engine-related pushes to `main`, release tags, manual | Windows x64: native build, vet, CLI/Jev build, version JSON/help page, facts/persistence, and start, repeated start, collector recovery, and scoped stop for an isolated API / portless worker; Ubuntu: Windows arm64 cross build. |
| Git read verification | PRs, manual | macOS / Ubuntu: repeated tests and race for Git, worktree, attribution, and observation. |
| Checked-in examples | PRs, manual | macOS / Ubuntu: the minimal sample `hello-worktree` across two worktrees (distinct ports, a portless worker, stopping one side). No Docker, no benchmark. The complex sample `stack-workshop` is not part of this check; it is the input of the manual benchmark, which runs on Linux with Docker. |
| Reused service readiness | PRs, manual | macOS / Ubuntu: reuse checks against real healthy and unhealthy services. |
| Windows build verification | PRs, release tags, manual | Windows x64: native build, vet, CLI/Jev build, version JSON/help page, facts/persistence, and start, repeated start, collector recovery, and scoped stop for an isolated API / portless worker; Ubuntu: Windows arm64 cross build. |
| Gate integrity | PR (`pull_request_target`) | Requires the PR author to be a repository maintainer when `.github/workflows/`, CODEOWNERS, the race list, release scripts, or quality-gate check scripts are modified. |
| CI configuration | PRs, CI-related pushes to `main`, manual | Ubuntu: actionlint checks every workflow and verifies that the required checks match the workflow job names. |
| CI configuration | PRs, CI-related pushes to `main`, manual | Ubuntu: actionlint checks every workflow and verifies that the required checks match the workflow job names. The push trigger stays because this check also compares the live ruleset after a settings change outside a pull request. |
| Bounded ancestry comparison | Manual (evidence) | Ubuntu: compare a branch against a specified baseline with a bounded benchmark on the same runner; not a merge gate. |

The single list of required checks is `.github/quality-gate-checks.json`; workflow job names are
Expand Down
Loading