ADR Enforcement¶
Architecture rules in this repo are enforced by tooling, not just prose.
What Exists¶
The model-access design for #681 adds proposed ADR-059 through ADR-061 and documentation coverage for the planned feature. Registry/import validation applies now. Runtime enforcement of broker authorization, atomic budgets, revocation and provider isolation must land with the owning implementation issues and their behavioral/cloud tests; a passing documentation check is not evidence of those guarantees. ADR-060-R3 also requires independently configurable sharing, explicit overlap and membership rules, deduplicated pool accounting and separately revocable range grants. The sharing contract is consumed by #2139/#2140 and the downstream implementation/evidence issues; it adds no waiver or claim of existing runtime enforcement.
The current enforcement stack has six parts:
-
docs/adr/index.yamlMachine-readable ADR registry. Each accepted ADR lists the rules and the checks that enforce them. -
docs/adr/exceptions.yamlExplicit exceptions. If a rule needs a temporary waiver, record it here with an owner and expiry instead of leaving the exception implicit. -
scripts/adr_guard/(theadr_guardtool) Repo-native policy runner and the entrypoint for ADR conformance checks.adr_guard.pyis the executable CLI entry point and compatibility facade; it bootstrapssys.pathonce and re-exports the internal_guardpackage. The check logic lives in one module per concern family under_guard/checks/(for example_guard/checks/k8s_security.py,_guard/checks/secret_hygiene.py,_guard/checks/deploy_workflow.py;_guard/checks/cloud_identifiers.pyholds the AWS-shapedno-live-cloud-identifiersscan and_guard/checks/gcp_deploy_identity.pyits GCP chart-values complement,no-live-gcp-deploy-identity) on top of the shared kernels_guard/_common.py(theViolationmodel, repo/git helpers, exception filtering) and_guard/_workflow_model.py(the_dw_*workflow-as-data model), with_guard/_registry.pyholding the deterministicCHECKS/CHECK_LEVELSregistry and_guard/_cli.pythe argument parsing. The deploy-environment evaluator does not execute workflow shell. It removes comments, requires the exact reviewed router program, and models its outputs as data. Its branch-reference inputs remain compatibility-only parameters. The_guardpackage uses package-relative imports internally, so it is importable on its own; the facade re-exports its full public surface, sopython3 scripts/adr_guard/adr_guard.pyand tests that load it by path keep working unchanged. The package is in the SonarCloud analysis scope (sonar.sourcesinsonar-project.properties); theadr-guard-testsCI job runs the suite undercoverageand uploadsscripts/adr_guard/coverage.xmlfor the SonarCloud new-code coverage gate. -
.pre-commit-config.yamlFast local hygiene and secrets checks. Full architecture checks run in CI; changed-file cloud identifier checks remain local. Thesonar-rules-changed-lineshook runs pinned Ruff rules throughdiff-qualityfor Python lines changed againstorigin/dev. It reports complexity, argument/return counts, documentation, type annotations and line length within the configured production source paths. It does not run tests or measure coverage, and does not replace the blocking SonarCloud gate. Its repository wrapper reads committed, staged and unstaged Git paths with NUL delimiters and supplies escaped literal paths todiff-quality. Source roots, exclusions and the 100% threshold remain unchanged. This avoids the tool's repeated recursive include expansion through ignorednode_modulestrees; those directories are not application quality inputs. The source roots, exclusions, Ruff rules and 100% threshold are one fixed policy inscripts/adr_guard/changed_python_quality.py. The wrapper accepts no external arguments: attempts to change refs, linter flags or scope fail before any subprocess. Its Git and quality commands use the literalorigin/devreference and argument vectors, with explicit Git option/path boundaries; no CLI text is forwarded into either command. The wrapper's regression tests use standard-libraryunittest, as required by the Python 3.11 ADR test lane; they need no pytest dependency. -
.github/workflows/_quality.ymlCI enforcement. ADR conformance runs as its own architecture gate. -
Existing ecosystem tooling
import-linterfor Python package contractsactionlintfor GitHub Actions workflowsTFLintfor Terraform linting (including thetflint-ruleset-googleplugin for GCP resources) The CI initialization step supplies the job-scopedgithub.tokenasGITHUB_TOKEN, so provider-plugin release lookups use the authenticated GitHub API allowance instead of the shared runner IP's unauthenticated rate limit.gitleaksfor new secret leakage detectionhelm lintfor Helm chart validation where files are templates rather than plain YAMLkubeconformfor Kubernetes manifest schema validationkube-linterfor Kubernetes security and best-practice enforcementCheckovfor IaC security scanning (Terraform and Kubernetes)
There is also agent-specific wiring:
.claude/hooks/adr_guard_hook.pyruns the ADR guard after Claude edits files..claude/skills/adr-check/SKILL.mdprovides a default workflow for ADR conformance work..claude/skills/architecture-review/SKILL.mdprovides a repo-specific architecture review checklist.AGENTS.mdgives Codex a repo-local policy file, including Ground Control project context for the/implementworkflow. The GC project pointer (and matching.ground-control.yamlproject:field) names theshifterproject (iddf4e718f-1f67-46f8-a375-3ba53fabc9c4) withCTF-*,PLAT-*,GEN-*UID prefixes by subsystem; an earlier draft incorrectly pointed both ataphelion(a separate, unrelated project)..ground-control.yamlis validated as a whole by the Ground Control context reader, so an unrecognized key fails the entire file closed rather than being ignored: the reader returnsinvalid_ground_control_yaml, and/implementloses the project, SonarCloud, and plan-rules context along with the offending block. Therouting:block accepts onlyenabled,default_provider, andstages. Routing is advisory under ADR-036, annotating a stage's capability tier for telemetry without selecting an executor, so a stale routing key is worth deleting rather than reinterpreting.
Review controls:
The #2555 quality repair uses the existing path contract and workflow model. Ruff enables security rules for the guard, ownership tooling and smoke helpers. The integration branch's Bandit jobs also cover these tools and the three inspection scripts. ShellCheck covers smoke and container scripts. MCP lint jobs reject security warnings, and the shared package has a test-matrix entry. The existing kube-linter job supplies blocking Kubernetes security policy. Checkov's separate Kubernetes checks are a blocking gate under ADR-004-R11 (#2558). Helm lint and rendered kube-linter checks run together, including when optional tests are skipped. BuildKit and Trivy validate container build inputs. The hosted guacd job proves non-root execution, drive permissions and listener readiness. The unused root branding assets have been removed after a consumer search. The user also retired the two unused vendor CloudFormation installers. Their quality owner and identifier exception have been removed.
The provisioner-locks hook and provisioner CI job check that the image's Python
requirements match uv.lock. The default export must match the frozen uv export;
GCP packages present in uv.lock must have the same versions. The image keeps
its existing pip-based install from these hash-pinned exports. Use the documented
uv export command when
regenerating them. The Guacamole image job also tests direct and nested jar
replacement, including rejection when an expected archive or dependency is absent.
Bootstrap regression tests use process boundaries for the affected CLI and GDC flows. Their legacy mock allowance decreases from 256 to 175. No new allowance or exception renewal is part of this repair.
The BigRAE rename (#2555) preserves the existing gates. After the same-owner
repository cutover, the Sonar condition permitted only Brad-Edwards/bigrae with
the same immutable repository and owner IDs. The repository then moved to
OpenRAE/bigrae (#2660). The repository ID stayed, and the condition now
permits the OpenRAE owner ID. Its expression-model tests deny the
old slug, a recreated slug, another owner and fork-origin PRs. Future GCP deployments use
one exact configured repository identity with the same purpose, Environment,
ref and workflow restrictions. Under the user's no-deployments decision,
no cloud-trust overlap or live migration is required. No cloud resource name
or state location is derived from branding.
GitHub's rename changes the default OIDC subject to include immutable owner and
repository IDs. AWS and GCP templates and AWS bootstrap must construct that
format from their explicit identity inputs. Canonical defaults use the observed
IDs. Other repositories supply their own IDs. The explicit legacy format selects
only the old subject shape; a policy never accepts both shapes as a fallback.
Existing audience, purpose, branch and Environment restrictions retain their scope.
The image-role guard requires exactly the dev and main subjects. It checks
the selected prefix expression when the policy uses a shared prefix, and rejects
wildcards, extra subjects and changes to the owner or repository ID fields.
The pinned Checkov action loads a version-bound compatibility adapter for the
immutable repository subject syntax. The adapter changes only the repository
parser; CKV_GCP_125 and the native WIF guard remain blocking. CI parity checks
require the adapter path, and tests reject unsupported versions and parser changes.
Plugin admission accepts exactly one invocation key, BIGRAE_PLUGIN_INPUT or
its legacy alias, through a matching Secret key reference. The static and Helm
policies share the same restriction and behavioral admission tests. Settings,
installation and MCP policy aliases reject conflicting inputs at their owning
parsers; package aliases re-export existing contract types. Both compatibility
distribution roots remain owned by Dependabot. Local source validation does not
prove a live repository, publisher or workload-identity cutover.
.github/CODEOWNERSrequires review on guardrail files and shared/public architecture seams..github/pull_request_template.mdrequires an ADR impact section on PRs..github/copilot-instructions.mdnow points GitHub Copilot toward the same ADR enforcement model..ground-control.yamlbinds synchronized/implementruns to the rootmake testcompletion boundary. The companionmake policytarget runs the full ADR guard, import-linter contracts, diff whitespace validation, and Vale against Markdown changed fromorigin/dev;tools/install-vale.shsupplies the pinned local Vale binary when it is not already installed.- Local commits run file hygiene, secret scanning, changed-file cloud identifier
checks, commit-message policy, Ruff, ShellCheck, actionlint, and Terraform
formatting, plus the changed-line Ruff/Sonar rule check above. Full tests and
coverage, type checks, Django checks, import and ADR
checks, package-wide JavaScript/CSS lint, Checkov, Bandit, Terraform validation
and TFLint, and Kubernetes/chart validation run in CI. These checks are removed
from the commit hook, not moved to push hooks. This supersedes older references
to local hooks for those checks; their policies and CI gates remain in force.
workflow.precommit_commandremainspre-commit runfor staged-file hygiene. Run targeted tests directly during development.pre-commit run --all-fileschecks the hygiene baseline only. - CI's quality-path-ownership contract (
.github/quality-path-filters.yaml) remains the authoritative lint, security, and test matrix. Checkov's invocation guard requires the blocking CI scan with the canonical config and external module loading. A local Checkov hook is optional; if reintroduced, it must match the CI policy. Missing CI coverage or soft-fail still fails the guard. - The
shifter_platformpytest worker cap (--maxprocessesinshifter/shifter_platform/pyproject.tomladdopts) is 8. Because-n autoalready limits workers to the host core count, this cap only takes effect on hosts with more cores than the cap: CI runners (ubuntu-latest, ≤4 cores) are unaffected and keep running at core-count workers, while multi-core dev/CI machines get the added parallelism for explicitly invoked local test runs. The cap also bounds peak memory (each worker loads the Django app), so it is raised only with headroom in mind given the suite's documented OOM history at high worker counts. - CI runs the broad platform suite once against PostgreSQL, split into six
shifter-platform-testsshards. Each shard publishes coverage data and its PostgreSQL marker evidence.shifter-platform-coveragerequires all shards, rejects missing or duplicate shard evidence and skipped PostgreSQL-marked tests, and requires at least one PostgreSQL-marked test to have run across the shards. It combines the data, enforces the unchanged 87% package floor, and publishescoverage.xmlfor SonarCloud. Redis integration and adapter SDK packaging retain their own blocking jobs. Released OpenFGA/PostgreSQL tests still run in the dedicated mandatory job and contributecoverage-openfga.xml; native browser and built-image smoke gates retain their real service and image entrypoints. Sharding changes execution cost, not the required evidence or coverage thresholds. Full suites and image smoke run in CI; local development uses focused regressions. .github/workflows/_gcp-dev.ymlis a thin wrapper over the GCP deploy commands (ADR-070). The deploy renders each image by its exact digest from the release manifest, so a mutable tag never selects a running image.
Deploy-time enforcement (ADR-035):
scripts/bootstrap/preflight.pyis a shared, fail-safe deploy preflight. It is the single source of truth for deployment prerequisites (tools, secrets, config) and runs the same checks locally (the deploy CLI runs it at the start ofbootstrap/terraform/full, anddeploy.py preflightruns it on demand) and in CI (each reusable deploy workflow runspython -m preflightbefore any Terraform apply). It reports every missing prerequisite up front instead of failing lazily mid-run, and skips are always explicit and logged (SHIFTER_SKIP_OPERATOR_BOOTSTRAP), never a silent conditional step skip. This is a runtime gate rather than anadr_guardstatic check;docs/dev/deploy-secrets.mdand the spec are kept in step by the parity test inscripts/bootstrap/tests/test_preflight.py. For GCP,deploy.py preflight --cloud gcpvalidates the deployment input bundle (--storeor--inputs) with the same loader thatdeploy.py gcp-deployuses (ADR-070).
Documentation site (ADR-038):
- Documentation is authored as Markdown under top-level
docs/and published as a single public mkdocs (Material) site on GitHub Pages by.github/workflows/docs.yml(mkdocs build --strictgates PRs; pushes to the default branch publish). Internal design notes, machine registries, and scratch dirs stay in-repo but are excluded from the published site viamkdocs.ymlexclude_docs. The in-app Django documentation app is retired. This is a runtime/build gate, not anadr_guardstatic check.
Migration state (CI gate):
- Django models and their committed migrations must stay in parity. The
shifter-platform-lintjob in.github/workflows/_quality.ymlrunsmanage.py makemigrations --check --dry-run(withTESTING=1,TEST_DB_BACKEND=sqlite,DJANGO_DEBUG=true, and a synthetic CI-onlyDJANGO_SECRET_KEY) as a blocking step. The command runs globally with no app-name arguments, soINSTALLED_APPSis the coverage seam and new Django apps are gated automatically.--dry-runwrites nothing and needs no database, so a model change that is not captured by a committed migration (including database-neutral drift such ashelp_textor model manager changes) fails the job. This is a CI gate, not anadr_guardstatic check, and it mirrors theapi_contract --checkdrift gate in the same workflow. Added by issue #1061.
Current Checks¶
The first slice intentionally stays small:
adr-registryValidates the ADR registry and exception files. It also validates the closed typed interface contracts required by ADR-032, ADR-039, ADR-051, ADR-054, and ADR-055. Theraes-plan-accessor-boundary/v1contract pins the RAES-free standalone consumer, ownership and validation boundaries, reject-before- mutation posture, full canonical address fallback, exact-pin compatibility evidence, and decision-only scope of #1937. Thededicated-customer-authority/v1contract makes removal or weakening of ADR-054's customer boundary, authority separation, event-migration gate, infrastructure ownership, outage behavior, or evidence classes fail locally and in CI. Theaccessibility-enforcement/v1contract likewise pins the WCAG target, one axe/Playwright toolchain, every-PR/nightly/deployed cadence, fail-closed surface inventory, exact finding ratchet, manual-audit evidence, central waiver policy, and security boundary. This is structural enforcement of accepted decisions, not a substitute for their runtime, migration, IAM, network, browser, or manual-audit tests.
ADR-055's exact section values live in ACCESSIBILITY_FIXED_SECTIONS, with
closed string collections in ACCESSIBILITY_STRING_SET_SECTIONS. Extend the
contract table, registry entry, and mutation test together; do not add a new
branch of repeated per-section validation.
The registry check keeps contract support, specialized ADR contracts, and dispatch in separate modules. This preserves the closed contract surface while keeping each validator independently reviewable and within the static analysis limits enforced for guardrail code. Validator helpers carry concise docstrings, and the documentation check remains below the enforced file-size limit so SonarCloud can keep analyzing guardrail changes on every pull request.
-
layer-importsEnforces the existing cross-layer import policy fromscripts/check_layer_imports/layer_imports.yaml. Every first-party Django app is classified there (ADR-001-R3, #1523) as a domain (engine,cms,management,ctf,workspaces), presentation (mission_control), support/contracts (shared), or support/composition (config) layer.workspacesis the organization/workspace tenancy domain added by ADR-046 (#1325); other layers reach it only throughworkspaces.servicesand carry a scalarworkspace_idrather than a cross-layer ForeignKey. Service-package imports may use only the public facade (for examplecms.services); private split-package submodules such ascms.services._range_pauseare not cross-layer seams. This covers both the dotted form (import cms.services._range_pause) and thefrom cms.services import _range_pauseform, the latter detected via an AST pass since the regex scan only sees the facade module path. The rule is mirrored inscripts/adr_guard/adr_guard.py, the standalonescripts/check_layer_imports/check_layer_imports.py, andmanagement check_model_fks; the hard-coded package lists are held to set-equality with the canonical classification by tests, and.importlinteradds a coarser package-level net.sharedremains the freely importable contracts layer. -
installed-apps-classifiedFails closed when a first-party Django app is added toINSTALLED_APPSwithout a classification inlayer_imports.yaml, when a classification entry is stale (no localAppConfig), or when anINSTALLED_APPSentry is a dynamic expression the checker cannot statically resolve (ADR-001-R3, #1523). The retireddocumentationpackage (ADR-038) has noAppConfigand is not classified. -
guardrail-docsRequires guardrail changes to update ADR or developer docs in the same change. This is a changeset-level check (needs to see multiple files) so it runs in pre-commit and--level fast, but NOT in the per-edit Claude hook. -
no-agent-attributionRejects AI/agent attribution markers in tracked text (agentCo-authored-bytrailers, Cursor marketing footers, Claude Code branding strings, etc.). Acommit-msgpre-commit hook blocks the same markers in commit messages. When a commit is rejected for attribution markers, disable Cursor commit/PR attribution in~/.cursor/cli-config.jsononly; project.cursor/cli.jsoncannot set attribution (permissions-only per Cursor CLI docs). -
cross-layer-model-importsFails on direct cross-layer model imports inside service layers. The current tree already satisfies this rule, so it is part of the default guard. -
python-complexity-gateEnforces ADR-012-R1: every canonical Python packagepyproject.tomlmust enable Ruff'sC901rule in[tool.ruff.lint].select, set[tool.ruff.lint.mccabe].max-complexityto the repo-wide threshold (PYTHON_COMPLEXITY_THRESHOLDinscripts/adr_guard/_guard/checks/complexity.py, currently15, matching SonarCloud's default cognitive-complexity threshold), AND must not silently disable the rule by listing it inignore,extend-ignore, orper-file-ignores. The check also cross-verifies thatPYTHON_COMPLEXITY_GATE_PYPROJECTSmatches theid: ruffhook working directories in.pre-commit-config.yaml, so a new lint surface cannot be added in one place without the other. Standalone verifier scripts underscripts/that ship their ownpyproject.toml(for example the post-apply deploy checks such asscripts/assert_portal_inspection, added for issue #932) are gated surfaces too: registering one means adding its directory to both.pre-commit-config.yamlandPYTHON_COMPLEXITY_GATE_PYPROJECTSin the same change. The complexity computation itself is Ruff's job; this check is the config-shape backstop against silent gate removal. Existing high-complexity functions carry per-function# noqa: C901exemptions; the function-level backlog (one row per exemption with current complexity) lives atdocs/adr/complexity-backlog.md. The threshold ratchets down as that backlog shrinks; a ratchet edit updatesPYTHON_COMPLEXITY_THRESHOLD, every canonicalpyproject.toml, and the backlog rows in a single PR. Runs in bothfastandcilevels. Test coverage inscripts/adr_guard/tests/test_adr_guard.pydrives the silent-bypass and prefix-selector cases throughsubTest()loops so adding a new bypass shape (for example,extend-select-side variants) is one row in the cases tuple, not a new test method. Theuat/event-load-harnessUAT load harness (#926) is a registered package under this gate, with matchingLint/SAST/Tests (event-load-harness)jobs in.github/workflows/_quality.yml. -
boundary-mock-policyEnforces ADR-019-R1: new Python tests may patch real process, network, cloud, and framework transport boundaries, but must not add new first-party internal callable patch targets. The check statically parses tracked test files forpatch()/ mock.patch()string targets and statically resolvablepatch.object(imported_module_or_class, ...)calls, then compares(test file, target)counts againstscripts/adr_guard/boundary_mock_baseline.json. The baseline records current legacy topology-coupled tests so adoption does not require rewriting the whole suite in one PR; the allowed counts may shrink but must not grow. The check also compares the baseline file against the branch reference so raising an allowance is a policy violation unless it has a dated ADR exception. Prefer behavioral assertions, in-memory fakes at service boundaries, or real framework test clients over patching first-party service functions, views, render/logging/transaction aliases, or model helpers. Issue #202 removed the expired bootstrap exception by adding explicit CLI, Terraform, and GDC operation ports and reducing the repository baseline from 618 to 465 internal patches; no replacement exception was recorded. -
documentation-coverageEnforces ADR-022-R1 (GEN-001): every major platform feature listed indocs/adr/documentation-coverage.yamlmust declare at least one user doc and at least one technical doc. The check validates the whole manifest on every run (it ignores the changed-file list, likeadr-registry): each referenced doc must exist under the in-app docs tree (docs_root), must not live under a_deprecated/hidden path, and must be reachable from anindex.md. This keeps the GEN-001 contract from silently regressing (for example, when a feature's doc is removed but its index link is left dangling). Adding a major feature means adding a manifest entry pointing at its user and technical docs. -
published-contract-snapshots-immutableEnforces ADR-011-R8: the published backend-bundle contract's per-version snapshots (shifter/installation/published_contract/backend-bundle-contract.v<N>.json) are append-only. Each snapshot records the frozen shape of a published contract version; a contract change ships a new version snapshot instead of editing an existing one. The check compares every snapshot present at the base-branch merge base against the working tree and fails when one was modified or deleted, so the breaking-change gate's compatibility oracle cannot be silently rebased. Likeboundary-mock-policyit resolves the base ref fromGITHUB_BASE_REF/ADR_GUARD_BASE_REF(falling back toorigin/dev/origin/main). It fails open locally (a shallow clone with no base history cannot compare, so dev is not blocked) and fails closed whenADR_GUARD_SNAPSHOT_ENFORCEis set: theadr-conformanceCI job checks out withfetch-depth: 0and sets that variable, so an inability to resolve or read the base becomes an enforcement failure rather than a silent pass. A genuinely absent directory at the base (a real first publication) is distinguished from an unreadable tree and still passes. -
accessibility-baselineEnforces ADR-055-R4/R6: the browser-accessibility exact-finding baseline (shifter/shifter_platform/frontend/e2e/a11y/baseline.json) may only shrink. The committed fingerprint set must be a subset of the trusted base-branch baseline; new fingerprints (baseline growth) fail unless covered by an exact-fingerprint waiver indocs/adr/exceptions.yamlnaming ADR-055 (an optionalfingerprints:list on the exception, validated by the central exception schema, never overloadingpaths/checks). Each fingerprint is the pipe-joinedsurface|project|rule|wcag|targetkey emitted by the a11y spec (project ischromium:<viewport>:<theme>), so a waiver must quote that exact string. Resolved findings (removed entries) always pass. Likepublished-contract-snapshots-immutableit resolves the base ref fromGITHUB_BASE_REF/ADR_GUARD_BASE_REF(falling back toorigin/dev/origin/main), fails open locally and closed underADR_GUARD_SNAPSHOT_ENFORCE, and treats an absent base baseline as a valid first enrollment. A committed baseline that is not a JSON array of fingerprint strings is rejected outright, and a base baseline that cannot be parsed is treated as unverifiable (failing open or closed as above). The per-surface exact-set comparison against the live scan and the fail-closed surface reconciliation are enforced in the Playwright a11y specs (frontend/e2e/a11y/), not this check. -
import-linterAdds package-level forbidden-import contracts across the main Django app layers. -
makemigrations --check --dry-runFails when a model or field-choices change ships without its migration. Runs as themissing-migrations-shifter-platformpre-commit hook as well as in the Quality workflow. Adding aTextChoicesmember alters the field, so enum additions need a migration too. The hook exists because the CI check sits behind the test gate, which is skipped when an earlier job fails -- so a missing migration could reach review unnoticed (#680). -
actionlintLints GitHub Actions workflows beyond plain YAML validation. This includes the GCP deploy workflow's Terraform state-backend hardening (_gcp-dev.yml) so retention and IAM policy bootstrap logic remains valid. -
Django i18n/static artifact tests Enforce ADR-016-R3 in
shifter/shifter_platform/tests/config/test_i18n_configuration.pyandshifter/shifter_platform/tests/platform/test_portal_dockerfile.pyby requiring portal image builds to runcompilemessagesbeforecollectstatic, and requiringentrypoint.shto stay free of runtime static-artifact rebuilds. -
deploy-workflow-plan-scopeEnforces ADR-003-R2 for the AWS deploy workflows. Theshifter_platformchange filter in.github/workflows/deploy.ymlmust stay scoped to Terraform-consumed platform files. Quality routing is separate and runs by exclusion:.github/workflows/deploy.ymlmust expose aquality_relevantoutput that runs Quality unless the diff is ordinary docs-only. That output also fails closed on an empty or undetermined changed-file set: anany_changedclassifier is false when the GitHub PR-files API returns zero files (its eventual consistency can do this for a freshly created PR), andquality_relevantORs inany_changed != 'true'so an unclassifiable diff runs Quality instead of silently bypassing it (#2024). Guardrail docs, including.github/pull_request_template.md,.github/copilot-instructions.md,docs/adr/**, and this ADR enforcement page, are explicitly quality-relevant so ADR guard validates them. PR Gate must reject a skipped Quality job unlessquality_relevantis false. Commit-message or label-based test skips are not accepted. Portal application changes must also keep reaching the portal image build/deploy path (#913): the check requires aportal_imagefilter coveringshifter/shifter_platform/**, exposed as achanges-job output, included in theshifter_platformjob's trigger condition, and consumed by the platformbuildjob through theportal_image_changesinput so an app-only deploy dispatch builds and converges the portal image without running Terraform. The check also requires.github/workflows/deploy.ymlto passskip_tests: falseliterally into_quality.yml(no commit-message parsing or dynamic outputs) and requires lint, architecture, and security jobs in_quality.ymlto stay independent ofinputs.skip_testsso the flag can only skip unit-test jobs when a caller opts in; the deploy router never opts in (#760). Negative fixtures inscripts/adr_guard/tests/test_adr_guard.pyinclude a minimal_quality.ymlstub so plan-scope tests isolate one violation at a time. The check requires deploy concurrency to queue dispatch deploys (keyed per environment) rather than cancel in-flight applies; PR cancellation may remain enabled. It also requires every core, range, and platformterraform plan/ saved-planterraform applycommand to include-lock-timeout=5m, and requires each apply job to create and execute a local savedtfplaninstead of uploading raw binary plans as artifacts or running a fresh unplanned apply. The platform Service Discovery replacement check must inspect that same saved plan. Non-deploy support/test surfaces that are not undershifter/**ormcp/**must use thequality_onlyfilter/output rather than being hidden in a deploy bucket:scripts/stack-smoke/**is a required entry so the orphaned support suites run Quality without launching Terraform plans, image builds, or environment deploys. Environment packs undershifter/environment-packs/are routed one pack at a time (#2550): each pack thatshifter/shifter_platform/Dockerfilecopies explicitly must be inportal_imageand not inquality_only. Each other pack directory must be inquality_onlyand not inportal_image. Neither filter may route the whole collection. Theguardrail_docsfilter must includeshifter/environment-packs/**, because pack Markdown is digest-covered content. On apply workflows,_shifter-platform.ymlstill pushes the Guacamole ECR images before the platform Terraform plan because the Guacamole module resolves current image digests withaws_ecr_imagedata sources during plan. This ordering is required for fresh AWS accounts where the repositories exist but the tags have not been published yet.
The deploy workflow model tests in
scripts/adr_guard/tests/test_deploy_workflow.py also assert the engine
reusable workflow carries its own hosted provisioner pytest gate and that
_shifter-engine.yml image validation, image build, and deploy jobs all need
that gate. This keeps a deploy dispatch's Quality skip from bypassing
provisioner tests on the image that is pushed and deployed. The same suite pins the engine
validate image-shape job's runner placement (#1474): it runs on the trusted
self-hosted deploy runner class rather than ubuntu-latest, so a
GitHub-hosted runner-acquisition stall can no longer cancel it before steps
start and skip the whole Platform stage. Because it is self-hosted it is
fail-closed on pull_request under the deploy-workflow-runner-exposure
(ADR-003-R5) invariant, keeps contents: read only, and carries a
timeout-minutes backstop (#1220).
TestGcpPrivateControlPlaneAccess keeps GCP deploy credentials on fleet
Connect Gateway. Since #2571 the deploy command fetches them in
scripts/bootstrap/gcp_kube.py. The test requires the fleet
memberships get-credentials call there. It rejects the direct
get-gke-credentials action and clusters get-credentials. The runner
has no route to the private RFC1918 GKE control-plane endpoint. Direct
credentials would make the workload apply time out after successful
Terraform and image-build stages (#1850).
The manual-deploy invariant (TestManualDeployDispatch, #730) asserts that
environment deploys are a workflow_dispatch naming the environment input
(a closed choice that has only aws-dev after #2668), that the Set
environment step keys on that input rather than a branch-name case router,
and that push / pull_request run validation only (no run/apply flags).
The optional gcp_reconcile_foundation_image_network dispatch input is
forwarded only to the selected tenant's reusable GCP deploy workflow. Its
foundation stage runs on that tenant's protected runner and Environment,
authenticates with the existing deploy identity, and checks a saved
cicd-oidc plan with scripts/gcp/check_image_network_plan.py before apply.
The checker permits only the six image-network address moves and the exact
IAP TCP port-2222 addition. Other resource or output changes fail the run;
ordinary deployments skip the foundation stage.
The GCP deployment-input guardrail
(test_gcp_workflows_keep_sensitive_tfvars_out_of_the_checkout) requires the
deployment inputs of _gcp-dev.yml in a private directory under
RUNNER_TEMP, which the job removes. The CI adapter must create exclusive
0600 files in a 0700 directory. No GitHub workflow tears down a GCP
deployment after #2668; an operator runs deploy.py gcp-destroy (ADR-070).
The destroy command renders cloud_sql_deletion_protection = false, which
the shared GCP root declares (default true), so teardown lifts deletion
protection.
The GCE guest image guardrail
(test_gcp_base_image_publish_uses_gce_native_contract_and_protected_ref_gate)
asserts that packer-gcp.yml publishes the minimum base set (kali, ubuntu,
and DC through dc-prebaked) as GCE-native disk tarballs to
ghcr.io/<owner>/<repository>/gce-<role>. The artifact type is
application/vnd.shifter.gce-image.v1, the layer media type is
application/vnd.shifter.gce-image.tar.gz, and annotations record the build
revision. The publish job checks that the validated image ID equals
BUILT_IMAGE_ID, and the export object name uses BUILT_IMAGE_ID. The
retired GDC qcow2 shifter-vm-* publish contract is gone.
test_gcp_guest_publication_needs_the_validation_of_the_same_run asserts
that the publish job needs the build and validate jobs, that the validate job
calls the local validation workflow without secrets, and that no promotion
workflow exists (#2668). gcp-deploy and deploy.py gcp-images import the
guest images of the release manifest as native GCE images after they verify
their build provenance (scripts/bootstrap/gcp_base_images.py, issues #2309,
#2571, #2679, and #2668).
-
portal-deploy-mode-source-of-truthEnforces ADR-003-R4 for the AWS portal deploy path._shifter-platform.ymlmust callscripts/portal_deploy/portal_deploy.py resolve-topologyinstead of readingAWS_PORTAL_ENABLE_AUTOSCALING; both AWS portal roots must exportenable_autoscaling; the helper must reject single-instance deploys unless exactly one running tagged instance matches Terraform state; and the ASG path must callverify-asg-imageafter instance refresh so every in-service instance is checked for the new portal image tag. -
deploy-verification-fail-loudEnforces ADR-003-R3: required verification failures fail deployment. AWS application workloads use EKS, Kubernetes rollout/readiness checks and the shared Helm chart. The retained range-image path keeps its explicit bootstrap input and existing failure behavior. GCP verifies the selected environment's rendered workloads and authenticated application endpoints. Older ECS portal rollout checks do not describe the current application path. -
workflow-action-sha-pinningEnforces ADR-037-R1: every non-localuses:action in a cloud-credentialed workflow must pin a full 40-hex commit SHA. A workflow is classified credentialed when it requestsid-token: write, runs on a self-hosted runner, invokes a cloud-auth action (aws-actions/configure-aws-credentials,google-github-actions/auth), or passes aworkload_identity_provider. The check parses workflows as data via the_dw_*model and fails closed: an unparseable workflow, an unclassifiable ref, or a mutable ref (tag or branch) is a violation.actions/*is in scope. Keep the# <version>comment next to each SHA for Dependabot. Refresh guidance:docs/architecture/rev1-build-deployment-provenance.md. -
release-workflow-provenanceEnforces ADR-070-R1 with ADR-004-R23, ADR-003-R5, and ADR-037-R1, R5, and R7 on.github/workflows/release-gcp.yml. It reads the workflow as data and fails closed when the workflow is missing or cannot be parsed. Onlyworkflow_dispatchandworkflow_callmay start the workflow (#2660). The only caller is therelease-gcpjob ofrelease-please.yml. That workflow must start only on a push tomain. The job must run only when a release tag points at the pushed commit, and it must not inherit secrets. That fact, the version, and the commit must come from an unconditionalrelease-commitstep after the Release Please action. The caller rules are inscripts/adr_guard/_guard/checks/_release_workflow_caller.py. Each job that publishes (it logs in to a registry, authenticates to a cloud, or pushes an image) must bind thegcp-releaseEnvironment and run on a GitHub-hosted runner. In that job, a step before the first publishing step must reject every ref exceptrefs/heads/main,refs/heads/dev, andrefs/heads/deploy-test. Every non-local action must pin a full commit SHA. Every pushed image build must produce an SBOM and maximum provenance. Anactions/attest-build-provenancestep in the same job must sign that exact digest withpush-to-registry: true. A deployment verifies this registry copy of the attestation without GitHub. Before the deployer image attestation, an unconditional step must scan the deployer digest with the blocking Trivy gate (--severity HIGH,CRITICAL --ignore-unfixed --exit-code 1). The step must useplatform/deployer/gcp/trivyignore.yaml, which holds only time-boxed vendor-binary exposures.
The check also covers the guest image workflows (#2668, ADR-037-R8 and R9) in
scripts/adr_guard/_guard/checks/_release_workflow_guests.py. A missing or
unparseable guest workflow is a violation:
packer-gcp.ymlstarts only fromworkflow_dispatchand has noenvironmentorpublish_targetinput.packer-gcp-validate.ymlstarts only fromworkflow_call. The build workflow calls it with a local reference. It passes onlyGCP_WORKLOAD_IDENTITY_PROVIDER,GCP_PACKER_VALIDATE_SERVICE_ACCOUNT, andGCP_PROJECT_ID, each from the secret of the same name. A called workflow reads an Environment secret only when the caller passes its name.- Each job that publishes binds its fixed Environment (
gcp-image-buildorgcp-image-validate) and runs on a GitHub-hosted runner. Before its first publishing step, it rejects every ref exceptrefs/heads/devandrefs/heads/main. - The job that pushes the guest image needs the validation job. An
actions/attest-build-provenancestep in that job signs the pushed digest withpush-to-registry: true.
The check runs at the fast and ci levels;
scripts/adr_guard/tests/test_release_workflow.py covers it.
-
TFLintAdds Terraform linting on top ofterraform fmtandterraform validate. The initial profile is intentionally narrow: it leaves existing repo-wide debt rules disabled so the new gate enforces signal instead of legacy noise. -
gitleaksScans newly introduced commits for likely secrets, with a small repo config for approved false positives. -
cloud-factory-seamEnforces ADR-005-R1: every cloud adapter module incloud/aws/must have a counterpart incloud/gcp/and vice versa. Catches provider parity drift when one side adds a new adapter without the other. Runs in both fast and ci levels. -
kubeconformValidates the rendered Helm chart for every supported values file against the official schemas (k8s-schemajob). The GKE custom resources use a CRD catalog pinned to one commit. Catches misspelled fields, invalid resource types, and schema violations before they reach a cluster. Pinned to the target GKE Kubernetes version. -
helm lintValidates the Helm chart, the only Kubernetes renderer (ADR-007). This is the correct validation boundary for raw chart templates, which are not parseable by generic YAML tooling before render time. -
kube-linterEnforces Kubernetes security and best practices: non-root containers, read-only root filesystems, resource limits, privilege escalation prevention, and more. Configured via.kube-linter.yaml. Thechart-lint-securityjob runs it on the rendered chart for every supported values file. -
checkov-k8sCIS Kubernetes benchmark and container security checks on the rendered Helm chart for every supported values file (security-k8sjob, #2571). A blocking gate under ADR-004-R11 since #2558 (soft_fail: false, nocontinue-on-error). This posture is separate from Terraform Checkov policy and from the Trivy configuration scan. Accepted-risk waivers use resourcecheckov.io/skipNannotations plus a matchingdocs/adr/exceptions.yamlentry (rule_id: ADR-004-R11, owner, reason with the Checkov policy ID,expires_on,paths).
Making the Trivy configuration scan blocking is tracked separately in #2566; the #2558 architecture preflight records the cross-repository contracts for that follow-up.
ADR-008-R5's #2564 CMEK design
puts every Terraform-owned GCS bucket on a customer-managed key. A
trivy config scan of platform/terraform/gcp reports no GCP-0066 finding,
with no exception. #2566 makes that scan a CI gate. The terraform test contracts of modules/gcs-cmek,
modules/portal/gcs, modules/image-export-storage,
modules/raes-package-storage, and global/cicd-oidc enforce the keys and
the lifecycle KMS roles.
-
checkov-terraformIaC security scan over first-party Terraform inplatform/terraform/. A blocking gate under ADR-004-R11. Pre-commit (.pre-commit-config.yamlcheckov) and the GitHub Actionssecurity-iacjob both consume the same config atplatform/terraform/.checkov.yaml;--soft-failis not set on either surface. Accepted-risk waivers (Checkovskip-checkentries in.checkov.yamlor inline# checkov:skip=CKV_X:…comments on individual resources) MUST have a matching entry indocs/adr/exceptions.yamlwithrule_id: ADR-004-R11, owner, reason (containing the Checkov policy ID),expires_on, and affectedpaths.adr_guard.pyrejects expired exceptions, forcing owner re-review. Do not create a separate Checkov waiver registry; the ADR exceptions registry is the audit trail. -
k8s-image-registryVerifies that the image roots in the chart's GCP values files (platform/charts/shifter/values-gcp-*.yaml) point at Artifact Registry (pkg.dev), preventing accidental use of public or untrusted registries. -
k8s-pss-labelsArchitecture check ensuring each Namespace template in the chart carries the Pod Security Standardspod-security.kubernetes.io/enforcelabels. The deploy commands create the platform and jobs namespaces with the same labels. Enforces ADR-006-R1. -
k8s-deployment-security-contextEnforces ADR-006-R2 against the rendered output ofhelm template platform/charts/shifter -f <values>for each entry inHELM_VALUES_FILES(values-aws-dev.yaml,values-aws-prod.yaml,values-gcp-dev.yaml,values-gcp-prod.yaml). The chart is the only Kubernetes renderer (ADR-007, #2571), so the check reads exactly what a deploy applies. Kind-based filtering, not filename-based, means a Deployment rendered from any template is scanned. Multi-document files (---separator) and indentless YAML sequences are supported. Per pod template:securityContext.seccompProfile.typemust beRuntimeDefault. Per container AND init container: the effective context (after pod-level inheritance forrunAsNonRoot,runAsUser,runAsGroup) must satisfyallowPrivilegeEscalation: false,capabilities.drop: [ALL]with nocapabilities.add,readOnlyRootFilesystem: true,runAsNonRoot: true,securityContext.privilegednottrue, an optional container-levelseccompProfile.type(when set) equal toRuntimeDefault, andrunAsUser/runAsGroupset to positive integers (booleans are rejected since Python treatsboolas a subclass ofint). Runs in thecilevel (--all --level ci, including CI) and in a dedicated pre-commit hookadr-guard-k8s(separate fromadr-guard-fast) that triggers onplatform/charts/shifter/changes. Not in thefastlevel, so unrelated--level fastinvocations and the system-Pythonadr-guard-fasthook do not pull in the YAML or helm dependencies. Runtime dependencies: PyYAML (pyyaml>=6.0) and Helm (v3.15.4). Theadr-conformancejob in.github/workflows/_quality.ymlbootstraps pip via the stdlibensurepipmodule (the self-hosted Amazon Linux runner's system Python ships without pip;actions/setup-pythoncannot fetch Python 3.12 for the runner's architecture), then installs PyYAML viapython3 -m pip install --no-deps --target ${RUNNER_TEMP}/py-depswithPYTHONPATH=${RUNNER_TEMP}/py-depson the run step, and Helm via the officialget.helm.shrelease tarball extracted to${RUNNER_TEMP}/helm-bin/and added to$GITHUB_PATH. The--usersite PyPI install of pip itself is job-scoped on the self-hosted runner; PyYAML lands under${RUNNER_TEMP}/py-depswhich is ephemeral. Theadr-guard-testsjob uses the same ensurepip + PyYAML pattern; the chart-rendering test uses a fake helm shim, so CI tests don't need real helm. Theadr-guard-k8spre-commit hook useslanguage: pythonwithadditional_dependencies: pyyaml>=6.0so PyYAML is provisioned in an isolated pre-commit virtualenv; helm is a developer prerequisite shared with the existinghelm-lint-shifter-charthook. Complements existing kube-linter checks (run-as-non-root,no-read-only-root-fs,privilege-escalation-container) which cover the subset PSS-restricted enforces directly; this check fills the gaps forseccompProfile,capabilities.drop/add, container-level seccomp overrides,privileged: true, pod-level inheritance, and initContainer coverage. Implementation note: the validator is decomposed into focused helpers (_check_container_basic_fields,_check_container_capabilities,_check_container_seccomp,_check_container_identity,_resolve_pod_spec,_resolve_pod_sc,_validate_containers_list,_chart_scan_requested,_validate_chart_renders) so each piece stays under SonarCloud's cognitive-complexity threshold and tests can target each clause independently. -
k8s-network-policy-coverageEnforces ADR-006-R3 against the rendered Helm chart output for each supported values file. Every BigRAE namespace discovered in that output must have a default-denyNetworkPolicywith an empty pod selector and bothIngressandEgresspolicy types. The check also rejects broad egressipBlockCIDRs (0.0.0.0/0and::/0) in BigRAE NetworkPolicies, forcing policies to use explicit GCLB, Google API, private service, and in-cluster service ranges. The one exception (#2090) is the boundary policy of a designated egress proxy (content-egress,model-provider-egress). It must select only that component, admit ingress only from named pods, allow only TCP 443, and exclude every private, shared, loopback, link-local, multicast, and reserved IPv4 range (REQUIRED_PUBLIC_EGRESS_EXCEPT). Runs in thecilevel and shares the Helm-rendered validation boundary withk8s-deployment-security-context. -
eks-cross-stack-sourcingEnforces ADR-044-R6 against the AWS EKS Terraform roots underplatform/terraform/environments/*/eks/. The EKS control plane composes over the existing portal and range data plane and must source cross-stack values (control-plane database, secrets KMS key, agent bucket, range VPC/subnets/AMIs/instance roles) through native AWS data sources and SSM Parameter Store. The check fails closed on anyterraform_remote_statedata source in those roots, which would couple the consumer to another stack's whole state file. Runs in both thefastandcilevels. The AWS/GCP provisioner-env contract parity that R6 also requires is proven by the platform test suite (tests/shared/cloud/test_aws_runtime_role_parity.py), not this structural guard. -
no-plaintext-secrets-in-tfvarsArchitecture check that scans*.tfvarsfiles committed underplatform/terraform/environments/andplatform/terraform/global/and flags any line that assigns a quoted string literal to a variable whose name ends in a secret-bearing term:password,passwords,secret,secrets,token,tokens,key,keys,credential,credentials,authcode,authcodes,pin_value, orpin_values. Bareauthcodeandpin_valuenames are also blocked. Heredoc string literals (name = <<EOF/<<-EOF) are flagged equivalently. Object/array assignments to a secret-bearing variable are walked forward to the matching brace/bracket and flagged when any string literal appears inside (sodb_credentials = { password = "..." }is caught whiledb_credentials = { password = var.x }is allowed). Function-wrapped string literals (db_password = trimspace("..."),api_token = sensitive("..."),db_credentials = jsonencode({ password = "..." })) are caught via a same-line RHS scan; multi-line wrapper expressions (jsonencode spanning lines, nested function calls across lines) are walked via balanced-delimiter matching of()/[]/{}until the expression closes, and any inner string literal flags the assignment. Var/local/data references and empty strings are allowed. Variables whose name ENDS WITH a public-material suffix (public_key,public_keys,public_cert,pub_key,pubkey,authorized_keys, etc.) are exempted because that material is share-only by design; the match is suffix-based so a name likepublic_key_password(which has the public-key fragment AND a secret suffix) stays flagged.*.tfvars.examplefiles are skipped. Both#and//line comments and/* ... */block comments are stripped before matching, matching Terraform's HCL grammar. A file that the check cannot read or decode as UTF-8 fails closed: the check reports it as a violation. Enforces ADR-004-R7. Complements gitleaks, which matches high-entropy random strings; this catches low-entropy committed credentials gitleaks ignores. Implementation note: the check is decomposed into focused helpers (_collect_tfvars_candidates,_scan_tfvars_file,_flagged_secret_var,_block_assignment_has_literal,_wrapped_rhs_has_literal,_lines_have_string_literal,_find_balanced_close_index,_find_block_close_index,_balance_scan,_block_depth_scan,_scrub_line) so each piece stays under SonarCloud's cognitive-complexity threshold and tests can target each clause independently. -
mcp-ops-tls-strictArchitecture check that fails the build when any file undermcp/ops/(.js,.mjs,.cjs, excludingnode_modules/) re-introducesrejectUnauthorized: false(or0/null) on a TLS configuration.mcp/opsconnects to RDS Postgres through an SSM port forward;mcp/ops/lib.js::buildPoolConfigis the single call site that builds the pool's TLS config and now preserves verification by settingssl.servernameto the captured RDS endpoint. Comments and string literals are flattened to whitespace before matching (mirroringmcp-no-shell-exec's approach) so a descriptive doc-string about the priorrejectUnauthorized: falseworkaround does not trip the check. Backstops thebuildPoolConfigunit-test invariant on every other JS file in the package. Enforces ADR-014-R7. -
no-tracked-generated-artifactsArchitecture check that fails the build when generated or pre-staging sensitive artifacts are tracked in source under narrow roots. Three artifact families are blocked, each scoped to its own root: Terraform plan outputs (tfplan,tfplan.binary,plan.out,*.tfplan,*.tfplan.binary) underplatform/terraform/environments/andplatform/terraform/gcp/environments/; environment-pack build output undershifter/environment-packs/<pack>/build/; and license / authcode bootstrap material (authcodes,*.authcodes) undertemp/bootstrap/. Enumeration usesgit ls-files(tracked + staged + untracked-but-not-ignored) so ignored ephemeral workspace artifacts are intentionally allowed; a synthetic-tree test-mode fallback walks the filesystem. The blocked path/name set is centralized inscripts/adr_guard/adr_guard.pyso adding another generated filename or environment root is one edit. The guardrail fails closed: violations name only the repo-relative path and a remediation hint, never echoing plan content, license material, or binary payloads. Backstops.gitignore, which does not retroactively un-track files that were already added (for example, throughgit add -f), and complementsno-plaintext-secrets-in-tfvars. Enforces ADR-004-R8. -
no-populated-secret-env-filesArchitecture check that fails the build when a tracked*-secrets.envfile underplatform/carries a real value on any assignment. Comments (lines whose first non-whitespace character is#), blank lines, empty assignments (KEY=), and a small fixed synthetic-placeholder allowlist (REPLACE_AT_DEPLOY,CHANGE_ME,PLACEHOLDER,EXAMPLE, plus the matching bracketed forms<replace-at-deploy>,<change-me>,<placeholder>,<example>) are allowed; anything else is flagged. The bracket allowlist is an explicit fixed set rather than a<...>pattern so a committer cannot hide a real credential inside angle brackets (for example,DB_PASSWORD=<attacker-known-password>). The parser splits on the first=so non-identifier key shapes (db.password=...,api-token=...,export DB_PASSWORD=...) are still subject to the value check; inline# ...is not honored as a comment (the env-file format treats#as a comment only when it is the first non-whitespace character on a line); non-comment, non-blank lines without=are flagged as malformed. Containment usesgit ls-filesso gitignored local-dev files (for example,platform-runtime-secrets.local.env) are intentionally not scanned; a synthetic-tree test-mode fallback walks the filesystem for unit tests. The roots and the synthetic-placeholder allowlist are centralized inscripts/adr_guard/_guard/checks/secret_hygiene.py. The root is the wholeplatform/tree, so a secret env file in any new location is in scope (#2571). Failure reporting names the repo-relative path and the variable name only; the rejected value is never echoed. Real runtime secrets must flow in at deploy time from GCP Secret Manager, a gitignored local env file, or a deploy-time Kubernetes Secret. Backstops gitleaks for low-entropy committed credentials it ignores and prevents reintroduction of the failure mode resolved by PR #1207 (issue #1195). Enforces ADR-004-R9. -
no-mission-control-flag-literalsArchitecture check that fails the build when Mission Control runtime code carries a hardcoded CTF challenge flag. It scans theshifter/shifter_platform/mission_control/package (all runtime; its tests live undershifter/shifter_platform/tests/mission_control/, outside scope) and theshifter/shifter_platform/templates/mission_control/template tree (including inline<script>JavaScript) for answer-shapedFLAG{...}literals (case-insensitive). Detection is by pattern, never by a denylist of real values. Format-hint placeholders that describe the answer shape rather than carry one are intentionally not flagged: an empty body (FLAG{}), the ellipsis form (FLAG{...}), and angle-bracket templates (FLAG{<16-hex>}). The path scope deliberately excludes tests, docs, the nativectfapp (whereFLAG{...}is a documented format hint), and environment packs undershifter/environment-packs/, where flags are legitimate challenge content. Failure reporting names the repo-relative path and line only; the matched value is never echoed. CTF flags are low-entropy and are not caught by gitleaks; this is the complementary repo-specific backstop. Challenge answers belong to the CTF/CTFd content domain, not the Mission Control application path. Closes the #560 regression gap (thebox_infoliteral-flag map removed during the mission_control views package split) and blocks reintroduction. Enforces ADR-004-R16. -
rds-pending-modificationsPost-terraform applygate in_shifter-platform.yml. Reads the portal Terraform outputs, then callsaws rds describe-db-instancesfor each*_db_instance_idoutput and fails the deploy job if any RDS instance still has non-emptyPendingModifiedValuesor non-in-sync/applyingDBParameterGroups[].ParameterApplyStatus. Catches the failure mode documented indev/terraform.md("RDS Change Application") where a successful apply silently queues class/parameter changes for the maintenance window. Implementation:scripts/check_rds_pending_modifications/, with its own uv-managed dev environment, dedicated CI lint+test jobs (check-rds-pending-modifications-lint/-testsin_quality.yml), and matching pre-commit hooks (ruff + pytest). Same pattern asscripts/check_layer_imports/. -
check-tf-kms-secrets-grantPre-commit hook AND CI step (.github/workflows/_quality.yml'sterraform-lintjob) that fails when an IAM role whose attachedaws_iam_role_policygrantssecretsmanager:GetSecretValue(or any wildcard covering it, such assecretsmanager:*,secretsmanager:Get*, or*) lacks an attached IAM Statement grantingkms:Decrypton the portal Secrets Manager CMK. The grant must satisfy all three predicates in the SAME Statement: Action coverskms:Decrypt(action wildcard matching is done withfnmatch, sokms:*andkms:De*also satisfy); Resource isvar.secrets_manager_kms_key_arnorvar.secrets_kms_key_arn(both module-input names refer to the same physical portal CMK in retained modules) or"*"/["*"](accepted when the same statement carries the service condition); ConditionStringEqualsorStringLikewith"kms:ViaService" = "secretsmanager.<region>.amazonaws.com". The per-statement coexistence check matters because IAM evaluates each Statement in isolation; spreading the predicates across separate statements does not satisfy a single Decrypt call. Independently, any IAM Statement grantingkms:DecryptonResource="*"(or["*"]) must carry akms:ViaServicecondition pinning to some service; unconditioned wildcardkms:Decryptis too broad. Existence is gated onsecretsmanager:GetSecretValue(not file layout) so unrelated roles that happen to live in the same file are not forced to acquire unnecessary KMS grants. Scoped via the matching CI invocation list. Retired module paths do not establish current coverage. The checker and tests below define the retained rule.
Because the role/grant pairing is evaluated within a single
file (cross-file aggregation is deliberately out of scope; see
the checker's module docstring), each role must stay in the same
file as its secretsmanager and kms:Decrypt policies. Splitting
them across siblings leaves the check passing while verifying
nothing. The
check is implemented in
scripts/check_tf_kms_secrets_grant/check_tf_kms_secrets_grant.py
and tested in
scripts/check_tf_kms_secrets_grant/test_check_tf_kms_secrets_grant.py
with stdlib unittest (mirrors check_tf_iam_ec2_scope). The
test suite itself is run by the check-tf-checker-tests pre-commit
hook and a matching CI step so a parser regression cannot land
merely because the current live .tf files remain in the
happy-path shape. Enforces ADR-004-R10. Backstops the failure mode
resolved by #52 where a fresh Secrets Manager CMK rotation left
several roles without kms:Decrypt and ECS task secrets injection
aborted at startup with AccessDeniedException: Access to KMS is
not allowed (which in turn was silently masked at the portal
entrypoint by an export VAR=$(fetch_runtime_secret …) pattern
that swallowed the fetch failure; see
shifter/shifter_platform/entrypoint-lib.sh and
shifter/shifter_platform/tests/test_entrypoint_lib.sh).
-
check-portal-target-sg-sourcesPre-commit hook AND CI step enforcing that portal target-service SG ingress (Django:8000, Guacamole client:8080) sources only from a security-group reference ormodule.vpc.alb_ingress_subnet_cidrs, never the whole public tier where standalone public workloads live. Scoped to the retaineddevandprodportal roots. Enforces ADR-004-R11. -
check-tf-iam-ec2-scopePre-commit hook AND CI step rejecting mutable EC2 instance lifecycle actions (TerminateInstances,StopInstances,StartInstances,ModifyInstanceAttribute,ModifyInstanceMetadataOptions) on a wildcard resource, and requiring the BigRAE ownership resource-tag conditions. Previously it ran in pre-commit and as a unit test in CI, but never against the live Terraform, unlike itscheck-tf-iam-elb-scopeandcheck-tf-iam-ssm-scopesiblings; a commit that bypassed pre-commit could land the regression (#1846). The live CI invocation was added to close that gap. -
global-iam-drift-checkADR guard check (fast + CI, registered in_registry.py) pinning the out-of-bandplatform/terraform/global/iamdrift-check workflow (.github/workflows/iam-drift-check.yml). global/iam owns the GitHub Actions OIDC deploy role and is applied out-of-band, so a mergedgithub-oidc.tfchange can go un-applied and the live role drifts behind committed config - the recurring "new resource, then next deploy fails with HTTP 403" churn (#247). The check binds the workflow's contract on one designated plan job: a push-only trigger (nopull_request/pull_request_target, per ADR-003-R5), a{dev, main}branch allowlist, aglobal/iampath filter, and a real, global/iam-scoped, non-swallowedterraform plan -detailed-exitcodeso a drift plan fails the build. The workflow runs-refresh=false(comparing committed config to the last-applied state) and is read-only, so it needs no IAM introspection the deploy role lacks. Enforces ADR-004-R26.
Local Usage¶
Run the fast profile on the full repo:
Run the CI profile:
Useful ecosystem checks:
cd shifter/shifter_platform && uv run lint-imports --config ../../.importlinter
TFLINT_CONFIG="$(pwd)/.tflint.hcl"; cd platform/terraform && tflint --recursive --config "$TFLINT_CONFIG"
actionlint
helm lint platform/charts/shifter -f platform/charts/shifter/values-gcp-dev.yaml
helm template quality-check platform/charts/shifter -f platform/charts/shifter/values-gcp-dev.yaml > /tmp/shifter-gcp-dev.yaml
kube-linter lint --config .kube-linter.yaml /tmp/shifter-gcp-dev.yaml
kubeconform -strict -summary -kubernetes-version 1.31.0 -schema-location default -schema-location 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/3eb90d47aba8d61919d4419dd38301536e32a94b/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' /tmp/shifter-gcp-dev.yaml
Run on specific files:
Run on staged or modified files:
Docs Prose (Vale)¶
Markdown prose is linted with Vale against the Google
developer documentation style. The config lives in .vale.ini; the synced
style package under .vale/styles/ is gitignored and fetched with vale sync.
The .github/workflows/vale.yml workflow runs on pull requests that touch
Markdown. It lints only the Markdown files the PR changes, at the config's
error level, so new and edited docs must be clean without forcing a one-shot
cleanup of the pre-existing backlog across the repo's Markdown corpus.
Run it locally the same way CI does:
vale sync # once, to fetch the Google style package
vale path/to/changed-doc.md # lint a specific file
git diff --name-only origin/dev...HEAD -- '*.md' | xargs -r vale
How To Add A Rule¶
- Add or update the ADR entry in
docs/adr/index.yaml. - Implement the
check_<name>(repo_root, files) -> list[Violation]function in the appropriatescripts/adr_guard/_guard/checks/<family>.pymodule (add a new family module if none fits), reusing the shared kernels in_guard/_common.py/_guard/_workflow_model.pyrather than duplicating helpers, and register it inscripts/adr_guard/_guard/_registry.py(CHECKSplus the relevantCHECK_LEVELSprofiles). - Decide where it belongs:
- fast local gate
- CI gate
- Claude post-edit hook
- agent policy docs
- If the rule cannot be enforced immediately, add a dated exception to
docs/adr/exceptions.yaml.
Exceptions¶
Use exceptions sparingly. They are for temporary, explicit waivers only.
Required fields:
rule_idownerreasonexpires_on
Optional narrowing fields:
checkspaths
Expired exceptions fail adr_guard, so they cannot linger unnoticed.
Production-Path Quality Ownership¶
.github/quality-path-filters.yaml is the single versioned contract that maps
every production path to the blocking lint, security, and test jobs in
.github/workflows/_quality.yml. scripts/quality_ownership/contract.py is the
one parser for it. The _quality.yml path-detection job runs
scripts/quality_ownership/classify_paths.py, which validates the contract and
rejects any unclassified changed path before it emits job selection (the
fail-closed boundary). The quality-path-ownership check (ADR-004-R24)
reconciles the contract against the whole repository for estate completeness,
per-path ownership completeness across lint, security, and test, and routing
reachability against the real workflow.
The repository-wide closure in #202 assigns blocking owners to the prior gap set: ADR tooling and stack-smoke helpers have Ruff/Bandit lanes (plus ShellCheck for shell harnesses), the three standalone deployment utilities share a blocking Bandit lane, MCP security rules are errors and the shared package has its own test matrix member, and Kubernetes and Helm inputs use kube-linter. Container inputs use BuildKit checks/ShellCheck/Trivy; the root Docker context is separately routed through the portal build and stack smoke. Unused root branding assets were removed after the consumer search in #2555. A new production input needs an explicit quality owner. The expired ADR-004-R24 exceptions were removed without renewal.
The unused CloudFormation connectors retired with their dedicated validation and security jobs. Their quality unit, template-specific tests and live-identifier exception retired in the same change. Maintained IaC keeps its existing gates.
To add a production path:
- Add a quality unit to
quality_unitswith itspathsand the real_quality.ymljobs underresponsibilities.lint,responsibilities.security, andresponsibilities.test. Use a{job, matrix}entry where one job serves several packages, and setpackagesto the matching first-party package identifiers so they reconcile againstscripts/check_layer_imports/layer_imports.yaml. - If the path is not production source, add a typed
exclusionsentry instead (docs,test,generated,vendor,metadata, orconfig) with a reason. Exclusions never route jobs. - If a unit genuinely has no blocking job for a responsibility, record a
time-bounded
docs/adr/exceptions.yamlentry for ruleADR-004-R24whosepathsnames the.github/quality-path-filters.yaml#<unit>:<responsibility>anchor. There is no in-contract escape hatch for an owned production path.
Repository identity (ADR-069)¶
docs/adr/repository-identity.json declares the upstream repository name,
owner, immutable repository and owner IDs, and former names. The
repository-identity-literals check (ADR-069-R6) reads it at the fast and
ci levels.
- The check fails on the declared or a former repository name, either ID, or
the
ghcr.io/<owner>/namespace in a tracked file. - These places are allowed: the declaration, Markdown,
docs/**,mkdocs.yml, committed Terraform.tfvars(deployment configuration), and the pack provenance records. - In
.github/workflows/*.yml, the only allowed form is the upstream-only guard comparisongithub.repository_id == '<id>'orgithub.repository_owner_id == '<id>'. - The check also fails when
.ground-control.yamlgithub_repodiffers from the declaration.
The workflow expression model reads the same declaration for its canonical
scenario. A rename changes the declaration, .ground-control.yaml, and the
deployment configuration only.
The check is split for reuse: scripts/adr_guard/_guard/_repository_identity.py
loads and validates the declaration, and
scripts/adr_guard/_guard/checks/repository_identity.py runs the scan. The
GCP WIF trust module keeps a repository-name default so the mandatory
CKV_GCP_125 check resolves the trust subject; the identity-literals check does
not flag it, because it matches the owner/repo pair and the IDs, not a bare
org or repo string. scripts/check_tf_gcp_wif_trust rejects a default on the
immutable IDs and on purpose_contexts (ADR-069-R3, ADR-070).
Design Constraints¶
- Keep the default local gate fast.
- Do not rely on external dependencies for the core ADR guard.
- Prefer explicit exceptions over hidden tolerances.
- Do not make CI architecture checks skippable through the normal test-skip path.
- Keep review friction focused on guardrail files, not on ordinary feature code.
Guardrail maintenance log¶
- agent-attribution matcher (
scripts/adr_guard/agent_attribution.py): the attribution-detection regexes were simplified from\s*.*to.*to remove super-linear backtracking (SonarCloudpython:S8786, ReDoS). Match behavior is unchanged (.*already spans the leading whitespace the redundant\s*matched) and is pinned by the existingtests/test_agent_attribution.pyparity tests. No change to what the guardrail forbids. - GCP platform-core facade guard (
scripts/check_gcp_tf_modules): #2535 wires the guard and its unit tests into the_quality.ymlTerraform lint job. Before this change, no CI job or hook ran the guard, andplatform-core/main.tfhad three direct resources. The Secret Manager audit config now lives ingcp/modules/project-audit-config. The Cloud Build grant for the Identity Platform blocking function now lives inportal/identity-platform. Both moves havemovedblocks. The guard allowlists only the cross-moduleterraform_data.network_topology_invariant, which creates no cloud resource. - GCP deploy overlay consumers (
scripts/adr_guard/tests/test_deploy_workflow.py): #2535 adds a fourth ephemeralbigrae.yamlconsumer to_gcp-dev.yml, the range telemetry env render. It appliesSHIFTER_CONFIG_OVERLAY_JSONlike the other three consumers, so the exact consumer count changes from 3 to 4. The invariant does not change: every consumer applies the overlay. -
GitHub-less GCP deploy (
scripts/adr_guard/tests/test_deploy_workflow.py): #2571 moves the GCP deploy logic from_gcp-dev.ymlto the deploy commands (ADR-070). The tests now read these sources for the same invariants:Invariant Source that the tests read HIGH and CRITICAL release scan gcp_release_scan.pyRunning-image evidence after superseded pods finish gcp_rollout.py,gcp_deploy_stages.pyPrivate input files scripts/gcp/render_ci_deployment_inputs.py,gcp_terraform.pyConnect Gateway credentials gcp_kube.pyOperator password by variable name; Secrets through stdin _gcp-dev.yml,gcp_control_plane.pySingle range-zone input ( settings.range_cells.zones)scripts/gcp/render_ci_deployment_inputs.py,settings_gcp_deploy.pyThe overlay invariant now counts CI adapter runs. Each run receives
SHIFTER_CONFIG_OVERLAY_JSONand applies it. - GCP running-image check (scripts/adr_guard/tests/test_deploy_workflow.py): #2698 adds the OpenFGA policy servers to the running-image check (ADR-037-R8).gcp_rollout.pypasses a fourth--expected-imageargument,openfga=<image>, only when the release pins a policy image. The exact argument count changes from 3 to 4. The test also requires the conditional OpenFGA argument. The invariant does not change: every workload has an expected image.
Private scenario boundary¶
AGENTS.md, .github/copilot-instructions.md, and .gc/plan-rules.md require
private scenario content and adapters to remain in their owning repositories.
Public planning and review evidence uses synthetic examples; existing disclosure
does not authorize further disclosure. Review application and infrastructure
changes for identity-based scenario dispatch, embedded guest scripts, image
recipes, and accidental imports from private adapters. Pack installation cannot
authorize executable code. Runtime adapter bindings require explicit administrator
authorization against a versioned public contract.
The independently buildable SDK lives in shifter/shifter_adapter_sdk. Its paths
route to platform quality jobs, which run SDK lint, security analysis, contract
tests, an isolated wheel-installation test, and distribution builds. make test
also runs the SDK lane. Application images copy the same first-party SDK source
alongside the existing installation package; external authors consume its wheel.
SDK tests reject imports from platform applications. Tenant standup instructions
now use a base-range smoke and leave optional external pack validation and its
evidence in the owning repository.
ADR-041's tenant installation addendum permits organization administrators to install their own plugins. Engine's organization-authority imports and config's advisory bootstrap projection have narrow symbol allowlists. Runtime protocol tests exercise replay, malformed output and target escalation; the worker-output tests verify Job/Pod ownership and bounded streaming. Admission tests evaluate the rendered CEL against actual neutral-runner manifests and privilege overrides. API tests cover tenant denial, immutable versions, encrypted registry credentials, retry and stale probe completion. These tests do not replace live isolation or range-lifecycle qualification.
External image and pack ownership (ADR-041-R10)¶
Private content and image recipes are maintained by their owning repositories. Core quality jobs validate shared base-image behavior and synthetic fixtures; private pack tests move with the implementation. Domain-controller builds require an explicit profile and seed, with no scenario-specific default. Source removal is preceded by a hash-verified private archive. This does not establish live qualification of an external adapter on either cloud.
The independent adapter SDK has its own dependency update entry, like every other Python package root. Private image recipes and their dependency update targets belong to the pack owner.
Named adapter file inputs (ADR-041-R11)¶
Named files reuse CMS's scoped upload ledger, quota mutex, immutable installation and cleanup. Database constraints and custody triggers retain the file purpose, exact object version and original range-use proof. SDK checks require the exact declared input names, nonempty files and a 512 KiB aggregate budget; empty new fields preserve retained request identities. CMS authorizes and fences actual file custody before native creation and through a composition-bound material port before worker dispatch. Engine cannot import CMS.
The rendered runtime-plugin admission policy permits only the invocation's immutable file Secret, projected with explicit bounded keys and a fixed read-only mount. The object-count quota allows three Secrets per reserved Job without increasing the 16-pod execution cap. Synthetic tests evaluate the rendered CEL with actual builder manifests and reject wrong Secrets, writable or extra mounts, path traversal, unsafe modes and oversized key sets. CMS tests cover replacement, retention, quota cleanup, original-proof revocation and digest tampering; these checks require no deployment or live qualification.
Participant model credential cutover (ADR-004-R21, ADR-059)¶
Core no longer creates pack-specific provider roles or issues guest provider keys. The dedicated legacy role checker moved with the removed issuer; generic IAM, permissions-boundary, namespace and model-broker checks remain enforced. The AWS permissions boundary no longer exempts the retired role namespace from its IAM deny. Drain existing ranges that depend on those roles using the previous release before applying the new platform IAM. GCP teardown retains legacy credential revocation, but new ranges receive no provider key. Qualification must establish broker-mediated model access on both clouds before declaring the private adapter migration complete.
Independent SDK publication (ADR-041, ADR-042)¶
adapter-sdk-release.yml publishes BigRAE's own adapter contract package,
independently versioned from the platform. It accepts only the protected main
ref and a version matching the source, tests and builds without an OIDC release
identity, then publishes the exact build artifact from the adapter-sdk-pypi
environment. The publishing job has no checkout/build step and no token fallback.
The release boundary is covered by test_adapter_sdk_release.py; normal SDK
lint, security, tests and wheel builds remain in the Quality matrix. This is a
software release surface and does not publish or curate external packs.
Tenant executable isolation (ADR-041)¶
Runtime plugin jobs require runtimeClassName: gvisor and nodes labeled
node-restriction.kubernetes.io/shifter-pool=runtime-plugin. The protected label
prefix prevents kubelets from attracting work by assigning themselves this label.
Both the host task profile and static/Helm admission enforce this boundary. CEL tests exercise rejection
of absent/default runtimes and platform-node placement using real rendered jobs.
The GCP node pool enables Sandbox on COS_CONTAINERD, with an exclusive taint
and bounded autoscaling. This follows the GKE Sandbox deployment contract.
The AWS pool uses AL2023 and a checksum-pinned gVisor point release, including its
sidecar binaries. Its MIME bootstrap installs the verified archive and configures
the runtime through nodeadm's merge interface.
The chart owns the EKS RuntimeClass; GKE owns its managed class. Both pools retain
one warm node and cap autoscaling at three. An absent runtime or failed bootstrap
blocks plugin startup, with no ordinary-container fallback. Release maintenance
must follow the gVisor installation layout
and containerd configuration.
The checked-in SHA-512 was verified against the complete release archive locally. Live tests must establish actual sandbox execution and deny-all
network enforcement independently of anything the plugin reports.
Broker process and guest authority (ADR-059, ADR-060)¶
The model_broker process has a mandatory import-linter contract forbidding
application domains, Django, PostgreSQL and Redis dependencies. Its only Engine
access is the private TLS control API authenticated with Google workload ID
tokens or a fixed, audience-bound regional STS identity assertion. Provisioner
enrollment has a distinct principal and operation-specific audience; the broker
principal cannot issue enrollment. Neither listener trusts forwarded peer headers.
Engine stores only hashes of one-use enrollment, access and rotating refresh tokens. Every use checks the incumbent range generation, grant epoch, upstream authority projections, original hard expiry and current reserved subnet. Request budget and token authentication share a transaction. PostgreSQL contention tests cover account ceilings and one-use credential rotation. Provider output is never written to accounting records; incomplete usage preserves conservative holds.
Vertex and Bedrock adapters implement the shared provider protocol and fixed origins with deployment-owned model/identity bindings. Token counting and paid transport each recheck a live continuation lease after credential acquisition. HTTP redirects, implicit retries, arbitrary URLs and unsupported billing features are rejected. Stream framing, CRCs, complete usage, disconnect cancellation and revocation are tested through the HTTP/provider boundaries. These local tests do not qualify effective cloud IAM, networking, guest delivery or model availability.
AWS model broker packaging¶
ADR-059's EKS packaging checks live in
platform/terraform/modules/portal/eks-model-broker/tests/boundary.tftest.hcl,
shifter/installation/tests/test_aws_model_broker.py, and the broker chart tests.
They exercise exact invocation IAM, private endpoint/routing readback, deployment
intent mismatch rejection and the combined NetworkPolicy permissions. Run native
Terraform tests, installer tests and chart tests when these boundaries change.
Live AWS and GCP qualification remains a separate release obligation.
Architecture handbook drift (ADR-022-R2)¶
The current-state handbook is owned through CODEOWNERS. Architecture features in
docs/adr/documentation-coverage.yaml declare optional drift_sources globs
alongside their existing user/technical pages. A mapped source change requires
review/update of that feature's technical page in the same diff; an unrelated
Markdown edit does not satisfy the rule. Record the reviewed date/revision when
the explanation stays accurate. New interfaces extend the existing manifest.
documentation-coverage validates all feature pages and index links on every
run. Local changed-path checks enforce pairing for their supplied scope. The always-run Quality path classifier also executes the same coverage and
drift check against the complete diff before emitting job selections, including
deleted sources. A source-only change cannot skip enforcement through the ADR
job filter; production ownership classification still excludes deleted files. The
full CI check compares the working tree/PR against the fetched base, including
deleted and renamed sources, and keeps base-revision associations binding when
mappings change. CI's existing ADR_GUARD_SNAPSHOT_ENFORCE=1 refuses unavailable
comparison history. Local full checks use available integration history and
fall back to working-tree changes when history is absent.
Run the existing guard and strict MkDocs build. Verify links and rendered views because MkDocs currently reports some broken references as informational. Automated pairing checks do not evaluate architecture prose or establish live qualification; CODEOWNERS review supplies that judgment. Historical preflights carry a visible status and link to the current handbook.
The documentation coverage entrypoint keeps pairing and manifest validation in
_guard/checks/_documentation_drift.py. The existing guard facade preserves
its public helper surface; Quality uses the same entrypoint.
The focused helper module also owns coverage-violation construction and shared manifest shape checks. Coverage validation and CI path routing therefore retain one set of rule identifiers and diagnostics when their implementation is split.
Operations runbook catalog¶
The public operations handoff under docs/runbooks/ retains the stable
RB001 through RB024 incident identifiers. The existing ADR-guard unittest
discovery runs test_operations_runbooks.py, which checks that all 24 pages are
present and indexed, carry the required Symptom, Investigation, Resolution and
Prevention sections in order, state an escalation boundary, and mark fenced
shell examples as read-only. The same test rejects command examples that read
secret values or directly mutate Kubernetes, cloud resources, Terraform, or
Helm. This is focused GEN-001 evidence within the existing test estate, not a
new documentation schema, manifest, or adr_guard runtime check.
The deployment cleanup uses one GCP Terraform execution root, explicit selected var-files and per-environment backend metadata. #2571 removed the Kustomize component, and the Helm chart is now the only renderer (ADR-070). The ADR enforcement record and recovery procedure describe retained owners, callers and the evidence limit for undeployed environments.
Canonical GitHub routing and the workflow expression model now use
OpenRAE/bigrae, after the transfer to the OpenRAE organization (#2660).
GitHub-less GCP deployment guardrails (ADR-070)¶
ADR-070 moves the GCP deploy into the bootstrap CLI and removes the GitHub dependency of a deployment. These guardrails changed with it:
release-workflow-provenance(described above) guards the release workflow that builds the images and the deployer image.scripts/check_tf_gcp_wif_trustruns in the Terraform lint job. Noreleasepurpose exists, because the release workflow publishes to the public registry with the workflow token (#2659). Each token-creator or act-as grant outside the build self-grants must use the singleimpersonationresource. That resource grants each named principal access only to the identity of its own purpose.impersonation_principalsmust admit onlyrelease_scan,deploy, anddestroy, withuser:,group:, orserviceAccount:members.github_repository_id,github_owner_id, andpurpose_contextsmust have no default (ADR-069-R3). The resolved-plan verifier requires no WIF provider when no federated subject exists, and exactly one provider otherwise. It also requires the token-creator grants to equal the named principals.- The Helm chart is the only Kubernetes renderer. The
k8s-lintjob is removed, becausechart-lint-securityruns kube-linter on the renders.k8s-schemarenders the chart and runskubeconform -strict, andsecurity-k8sruns Checkov on the renders. Thevalidate-gcp-manifestsaction is removed. The CKV_K8S_35 and CKV_K8S_38 exceptions now name the chart templates; the CKV_K8S_43 exception is removed. - The pre-commit hook
adr-guard-gcp-overlay-identityis nowadr-guard-gcp-deploy-identity. It runsno-live-gcp-deploy-identityon the chart values files. - The
gcp_deployerquality unit routesplatform/deployer/**to two jobs.container-images-lint-securityruns the BuildKit check and the Trivy configuration scan of the deployer Dockerfile.gcp-deployer-imagebuilds the image with a fixture release manifest and starts it.
Adapter preparation (ADR-041-R12, ADR-063-R4)¶
The SDK restricts prepare to declared provisioning concerns, existing scalar
payload leaves and bounded responses. Core evaluates the original RAES domains,
recursive constraints and all overlapping authority before accepting any value.
Migration 0119 makes accepted preparation and its pin/parent identities immutable
through SQL. Acceptance and cancellation share the Range lock; accepted mapping
and planned invocation become visible atomically. A destroy input retains that
mapping, or explicitly records that the mandatory pre-effect gate never opened.
The latter is a scoped proof of no effects, not an inference from a missing Job.
Core checks the complete future destroy envelope before accepting a preparation.
Prepared cleanup uses the original input; unprepared cleanup reads no mutable
image registry or guest material. Oversized encrypted snapshots are refused
before any provider effect.
Accepted preparation continues through normal provider inventory/readback.
Targeted SDK, Engine PostgreSQL, provisioner and admission-policy tests cover confidential output, exact-value rejection, retention, tampering, replay and late acceptance. The chart allows only one input key and an optional result key from the same invocation Secret. See the design.
Registered GCP range projects (ADR-032-R11)¶
The implementation for #2716 adds Engine-owned project registration and retained range-use records. Migration 0120 enforces immutable accepted baseline and project identity, one unreleased use per project, immutable lease custody, and refusal to delete an active use. A release update requires the current applied native destroy receipt, verified absence without residuals, and matching original-lease baseline readback. The targeted PostgreSQL tests exercise those guards through bulk SQL writes, plus atomic multi-project allocation, organization isolation and replay. Shared contract tests cover ciphertext identity, bounded baseline decoding and semantic parity, including changed policy conditions and resource incarnations.
Registration uses the existing native operation input, recorded initiating proof and append-only result inbox. Installation policy and the exact live credential are checked before dispatch. No cloud I/O belongs in the portal or adapter worker. These checks establish custody; they do not claim live provider realization or deployment qualification. The design describes the remaining provider preflight, execution and readback boundaries.
Local implementation design checks¶
The .ground-control.yaml module mappings select existing implementations and
governing architecture decisions. Repository-wide decisions apply to all paths;
CMS and shared.raes also select their admission and archive designs.
The design stage compiles platform modules, checks the existing import rules,
and generates a dependency view from Python imports. It then runs each named
acceptance test on the local design commit through tests/design_checks.py.
An assertion failure establishes missing behavior; collection errors, fixture
errors, skipped tests, and ambiguous selection do not. The design review runs
before implementation. These commands add no runtime dependency or deployment.
Existing CI, pre-commit, architecture and completed-work review checks still apply.