Engineering agents pilot#
The reusable controller lives in engineering-agents. EDI is its first target. It uses approved specs, isolated worktrees and containers, PostgreSQL coordination and memory, independently executed review assertions, and human-controlled merging.
Light mode without new infrastructure#
Use the controller’s Light mode guide to work with your existing coding assistant, local Git worktrees and GitHub Actions. No PostgreSQL server, Docker, worker host, signing key, new model API key or cross-repository read token is required. A local SQLite file coordinates up to three worktrees; review and approved-memory records travel with the PR in Git.
Branches named engineering-lite/RUN_ID use the trusted, vendored
scripts/verify_engineering_lite.py checker. It reads the live PR’s Git objects
through GitHub’s built-in token, validates scope and scientific fields, and binds
two declared reviewer sessions to the spec and source-tree fingerprint. Any code
change invalidates those reviews. The existing tests, changed-code coverage,
packaging and documentation/gallery checks still apply; a human decides to merge.
Lite records are declarations, not signed evidence of reviewer identity or proof of scientific correctness. Use separate reviewer sessions and inspect their reports. Lite does not execute generated code on the controller, launch agents, or coordinate separate machines. It is intended for routine low/medium-risk work. Human branch protection settings are still needed to make checks mandatory on GitHub.
Full-mode engineering/ branches retain signature verification.
ENGINEERING_ENFORCE_ALL=true continues to require full signed evidence even for
Lite branches; choosing a branch prefix cannot downgrade that enforcement.
Repository checks#
The existing Ruff, typing, citation, test, wheel and documentation/gallery checks remain active. The test workflow now reports coverage JSON and requires at least 80 percent coverage of changed executable lines in the three published packages. Comments, blank lines and deleted lines do not inflate that denominator. A changed package file without coverage evidence fails. This threshold does not assert that the entire existing repository has 80 percent coverage.
The Engineering evidence gate verifies a controller-signed receipt for the
current repository and exact PR base/head commits. The receipt includes five
executable gates, separate implementation/code/scientific sessions, both independent
reviews and completed human memory decisions. Its Ed25519 public key is stored in
ENGINEERING_ATTESTATION_PUBLIC_KEY; the private key stays on the publisher.
The workflow reads live PR metadata and executes only the verifier from the trusted
default-branch commit. It does not execute PR code in pull_request_target.
Because that event runs in default-branch context, the workflow explicitly creates
the required check on the live PR head SHA and completes it only after verification.
Its token can read contents/PR metadata and write checks; it cannot push code or
merge PRs. See GitHub’s event semantics
and Check Runs API.
Rollout and enforcement#
Initially, signed evidence is required for engineering/ branches. Other branches
are reported as outside the pilot; their CI is not evidence of independent agent
review. Once the worker and publisher are qualified, set repository variable
ENGINEERING_ENFORCE_ALL=true to require the evidence for every PR.
A workflow file alone cannot prevent merging. An administrator must make these
checks required on main with strict up-to-date enforcement:
Ruff, ty, tests (Python 3.12)Ruff, ty, tests (Python 3.13)Build documentation and execute examplesEngineering evidence gate
The reviewed protection payload and worker deployment instructions are maintained in engineering-agents. The pilot remains disabled until a dedicated worker host, PostgreSQL identities, qualified pinned sandbox image, model credentials, signing key and protected branch are available. No automatic merge is implemented.
Scientific review#
Specs must identify primary evidence, observed/modeled/synthetic inputs, units,
reference calculations, tolerances, uncertainty, leakage controls and validity
limits. A separate reviewer reconstructs expected behavior and supplies a reference
program that runs in isolation. Missing evidence or not_verified blocks delivery.
An assertion executing successfully does not by itself prove that its scientific
assumptions are correct; the report and human acceptance must assess those assumptions.