GEN-002: Executable Architecture Governance¶
Statement¶
The repository shall maintain executable architecture governance for accepted architecture constraints. Accepted ADRs with enforceable impact shall be represented in a machine-readable registry, time-bounded exceptions, and automated checks that run locally and in CI; workflow or test skip mechanisms shall not bypass architecture conformance.
Rationale¶
The repo now has guardrail enforcement in ADR registry, adr_guard, CI, hooks, and agent policy. This is a governance NFR, not implementation guidance for feature delivery.
Traceability¶
- IMPLEMENTS → CODE_FILE
scripts/adr_guard/changed_python_quality.py(Select changed owned Python paths for the existing static quality gate without traversing installed dependencies) -
TESTS → TEST
scripts/adr_guard/tests/test_changed_python_quality.py(Preserve source scope, Git diff coverage, filename handling and quality-gate failures) -
IMPLEMENTS → GITHUB_ISSUE
2555(Repair blocking quality coverage during the BigRAE rename) - IMPLEMENTS → CONFIG
scripts/adr_guard/ruff.toml(Blocking lint and security rules for architecture tooling) - IMPLEMENTS → CONFIG
scripts/quality_ownership/ruff.toml(Reuse the architecture tooling policy) - IMPLEMENTS → CONFIG
scripts/stack-smoke/ruff.toml(Blocking smoke helper lint and security rules) - TESTS → TEST
scripts/stack-smoke/test_page_smoke.py(Reject non-HTTP smoke transports before file access) - TESTS → TEST
scripts/adr_guard/tests/test_deploy_secret_sync.py(Compatible config options and conflict rejection without GitHub writes) - TESTS → TEST
scripts/bootstrap/tests/test_github_oidc_subjects.py(Immutable and explicit legacy bootstrap subjects; reject invalid identities) - TESTS → TEST
platform/terraform/global/iam/tests/github-subject.tftest.hcl(Native AWS trust subjects retain exact repository IDs and protected refs) - IMPLEMENTS → CODE_FILE
scripts/check_checkov_invocation_parity/compat/immutable_subjects.py(Version-bound scanner syntax compatibility without a policy waiver) - TESTS → TEST
scripts/check_checkov_invocation_parity/test_immutable_subjects.py(Native scanner decisions and fatal compatibility drift) - TESTS → TEST
scripts/bootstrap/tests/test_cli.py(CLI behavior without internal orchestration mocks) - TESTS → TEST
scripts/bootstrap/tests/test_gcp_control_plane.py(Process-boundary bootstrap and GDC ordering behavior) -
DOCUMENTS → DOCUMENTATION
docs/architecture/bigrae-rename-quality-design-2555.md(CI data flows and protection controls) -
IMPLEMENTS → GITHUB_ISSUE
Brad-Edwards/bigrae#2571(GitHub-less GCP deployment) - IMPLEMENTS → CODE_FILE
scripts/adr_guard/_guard/checks/release_workflow.py(release-workflow-provenanceguard for the GCP release workflow (ADR-070-R1)) - TESTS → TEST
scripts/adr_guard/tests/test_release_workflow.py(Release workflow provenance guard regression tests) - IMPLEMENTS → CODE_FILE
scripts/check_tf_gcp_wif_trust/check_tf_gcp_wif_trust.py(Release purpose, closed impersonation grants, and default-free trust anchors (ADR-069-R3, ADR-070)) - TESTS → TEST
scripts/check_tf_gcp_wif_trust/test_check_tf_gcp_wif_trust.py(Identity trust guard regression tests) -
TESTS → TEST
scripts/adr_guard/tests/test_deploy_workflow.py(GCP deploy invariants read from the deploy command modules) -
IMPLEMENTS → GITHUB_ISSUE
Brad-Edwards/bigrae#1583(In-tenant artifact preparation and dependency compatibility) - IMPLEMENTS → CODE_FILE
shifter/shifter_platform/shared/cloud/preparation_policy.py(Executable preparation Job authority and exact-image admission) - IMPLEMENTS → CODE_FILE
shifter/shifter_platform/shared/cloud/preparation_installation_readback.py(Fail-closed verification of installed Kubernetes authority) - IMPLEMENTS → CODE_FILE
shifter/shifter_platform/shared/cloud/preparation_cloud_readback.py(Independent installed cloud IAM and isolation verification) - TESTS → TEST
shifter/shifter_platform/tests/shared/cloud/test_preparation_installation_readback.py(Reject unapproved execution, RBAC, network policy and unconverged installations) - TESTS → TEST
shifter/shifter_platform/tests/shared/cloud/test_preparation_cloud_readback.py(Reject cloud authority and network drift) - TESTS → TEST
shifter/shifter_platform/tests/shared/cloud/test_preparation_runtime.py(Exact worker image, identity, command and Secret-backed transport policy) - TESTS → TEST
shifter/shifter_platform/tests/engine/services/test_preparation_postgres.py(Real concurrent request serialization, idempotency and capacity across grant versions) - DOCUMENTS → DOCUMENTATION
docs/ops/artifact-preparation.md(Operator installation and enforced responsibility boundaries) - IMPLEMENTS → CODE_FILE
scripts/check_tf_gcp_iam_resource_scope/check_tf_gcp_iam_resource_scope.py(Closed dynamic-secret name and participant-version conditions verified in the tenant) -
TESTS → TEST
scripts/check_tf_gcp_iam_resource_scope/test_check_tf_gcp_iam_resource_scope.py(Reject widened prefixes, participant classes, permissions and invalid condition compositions) -
DOCUMENTS → GITHUB_ISSUE
Brad-Edwards/bigrae#689(Refactor CI and guardrail automation god files) - CONSTRAINS → ADR
ADR-001(Cross-layer access goes through service boundaries) - CONSTRAINS → ADR
ADR-002(Guardrail changes must remain documented) - CONSTRAINS → ADR
ADR-003(ADR enforcement is a required architecture gate) - CONSTRAINS → ADR
ADR-004(Use stack-appropriate off-the-shelf policy tooling where it fits) - CONSTRAINS → ADR
ADR-006(Kubernetes workloads must meet Pod Security Standards) - CONSTRAINS → ADR
ADR-032(raes-plan-accessor-boundary/v1structurally pins the cross-process RAES plan-reader decision from #1937) - IMPLEMENTS → CONFIG
docs/adr/index.yaml(Machine-readable ADR registry) - IMPLEMENTS → CONFIG
docs/adr/exceptions.yaml(Time-bounded ADR exceptions) - IMPLEMENTS → CODE_FILE
scripts/adr_guard/adr_guard.py(ADR guard architecture policy runner) - IMPLEMENTS → CODE_FILE
scripts/adr_guard/_guard/checks/adr_registry.py(Typed accepted-ADR interface-contract validator) - IMPLEMENTS → CONFIG
.gc/plan-rules.md(Ground Control plan rules for architecture checks) - IMPLEMENTS → CONFIG
.github/workflows/_quality.yml(CI architecture and quality gate) - IMPLEMENTS → CONFIG
.github/workflows/codeql-analysis.yml(Blocking CodeQL analysis and upload gate) - IMPLEMENTS → CONFIG
.github/dependabot.yml(Update ownership for every Python package root) - IMPLEMENTS → CONFIG
.pre-commit-config.yaml(Local guardrail pre-commit hooks) - TESTS → TEST
scripts/adr_guard/tests/test_adr_guard.py(ADR guard regression tests) - DOCUMENTS → DOCUMENTATION
docs/adr/README.md(ADR enforcement documentation) - DOCUMENTS → DOCUMENTATION
docs/adr-enforcement-plan.md(ADR enforcement design plan) - IMPLEMENTS → PULL_REQUEST
947(ADR enforcement audit and guardrail backfill) - IMPLEMENTS → GITHUB_ISSUE
Brad-Edwards/bigrae#915(deploy: single source of truth for deployment mode and portal sizing) - IMPLEMENTS → CONFIG
.github/workflows/_shifter-platform.yml(AWS portal deploy workflow topology enforcement) - IMPLEMENTS → PULL_REQUEST
964(fix: unify portal deploy mode source) - IMPLEMENTS → GITHUB_ISSUE
Brad-Edwards/bigrae#927(test: adopt a boundary-mock policy + lint to stop topology-coupled tests) - IMPLEMENTS → PULL_REQUEST
973(test: add boundary mock policy guard) - IMPLEMENTS → CODE_FILE
scripts/adr_guard/boundary_mock_baseline.json(Boundary mock legacy baseline) - CONSTRAINS → ADR
ADR-019(Tests mock external boundaries, not first-party topology) - DOCUMENTS → DOCUMENTATION
docs/technical/dev/adr-enforcement.md(Developer ADR enforcement documentation) - DOCUMENTS → DOCUMENTATION
docs/architecture/raes-provisioning-plan-accessor-boundary-preflight-1937.md(Accepted RAES accessor-boundary decision and compatibility handoff to #2082) - IMPLEMENTS → CODE_FILE
scripts/quality_ownership/contract.py(Production-path quality-ownership contract parser (#1530)) - IMPLEMENTS → CODE_FILE
scripts/quality_ownership/classify_paths.py(Fail-closed changed-path classifier for the _quality.yml paths job (#1530)) - IMPLEMENTS → CONFIG
.github/quality-path-filters.yaml(Versioned production-path quality-ownership contract (#1530)) - TESTS → TEST
scripts/adr_guard/tests/test_quality_path_ownership.py(Quality-path-ownership gate tests (#1530)) - IMPLEMENTS → GITHUB_ISSUE
1530(REV1 Testing: enforce production-path ownership in routed CI) - TESTS → TEST
scripts/adr_guard/tests/test_deploy_workflow.py(Sonar, dependency, exact-image, secret handling, and release-security workflow invariants) - IMPLEMENTS → CODE
scripts/gcp/verify_running_image_ids.py(exact repository-and-digest verification for every running release container) - TESTS → TEST
scripts/gcp/tests/test_verify_running_image_ids.py(missing, lookalike, and partial-rollout regression coverage) - IMPLEMENTS → CODE_FILE
scripts/check_tf_gcp_wif_trust/check_tf_gcp_wif_trust.py(Purpose-specific GCP CI role-boundary guard) - TESTS → TEST
scripts/check_tf_gcp_wif_trust/test_check_tf_gcp_wif_trust.py(Purpose-specific GCP CI role-boundary regression tests) - IMPLEMENTS → GITHUB_ISSUE
Brad-Edwards/bigrae#2084(GCP exact-release security gate reconciliation) - IMPLEMENTS → CODE_FILE
scripts/adr_guard/_guard/checks/documentation.py(lilrae-identity-boundarycheck enforcing ADR-024-R6 identity and scenario-pack terminology) - TESTS → TEST
scripts/adr_guard/tests/test_adr_guard.py(LilraeIdentityBoundaryTests for rename continuity, TechVault role, false pairing, and historical evidence boundaries) - IMPLEMENTS → CONFIG
.github/workflows/iam-drift-check.yml(Out-of-band global/iam CI drift-check gating onterraform plan -detailed-exitcode(ADR-004-R26, #247)) - IMPLEMENTS → CODE_FILE
scripts/adr_guard/_guard/checks/_deploy_workflow_iam_drift.py(global-iam-drift-checkguard pinning the global/iam drift-check workflow (ADR-004-R26, #247)) - TESTS → TEST
scripts/adr_guard/tests/test_global_iam_drift.py(global/iam drift-check guard regression tests (#247)) - IMPLEMENTS → GITHUB_ISSUE
Brad-Edwards/bigrae#247(Audit and scope down OIDC IAM permissions) - IMPLEMENTS → GITHUB_ISSUE
Brad-Edwards/bigrae#202(Repository-wide quality ownership and expired-exception closure) - IMPLEMENTS → CONFIG
.github/quality-path-filters.yaml(Blocking lint, security and test ownership for every prior production-path gap) - IMPLEMENTS → CONFIG
.github/workflows/_quality.yml(ADR tooling, stack smoke, MCP, container, chart and CloudFormation blocking jobs) - IMPLEMENTS → CONFIG
.github/actions/install-shellcheck/action.yml(Checksum-verified shared ShellCheck installation) - IMPLEMENTS → CODE_FILE
scripts/bootstrap/cli.py(Injectable CLI dependency and GDC bootstrap boundary) - IMPLEMENTS → CODE_FILE
scripts/bootstrap/gcp_control_plane.py(Explicit GDC substrate operation ports) - TESTS → TEST
scripts/bootstrap/tests/test_cli.py(CLI dispatch through injected boundaries) - TESTS → TEST
scripts/bootstrap/tests/test_gcp_control_plane.py(GDC substrate orchestration through operation ports) - IMPLEMENTS → CONFIG
scripts/adr_guard/boundary_mock_baseline.json(Reduced repository boundary-mock ratchet with no replacement exception) - TESTS → TEST
scripts/adr_guard/tests/test_quality_path_ownership.py(Bandit ownership and root portal-image-context routing) - TESTS → TEST
shifter/shifter_platform/tests/platform/test_stack_smoke_job.py(Authenticated smoke redirects cannot forward session cookies)