Execute and govern GoCPG architecture checks

This guide explains how an architecture result becomes a release decision. It is for repository owners and CI operators who already have a validated model and a CPG for the revision they intend to check. Start with model and rules to define components and contracts. Use interfaces and results to inspect the output.

The gocpg architecture validate command only checks the rule’s schema and language applicability. The production CI path needs a project policy, a project key, a release-control document and an output artifact. The system must also prove that the graph, facts, model and rules belong to the evaluated commit.

Choose a profile for your rollout stage

Start with discovery while defining components. Use advisory to review findings and tune the policy with the team. After recording baseline debt, enforce_new checks new violations. Choose enforce_all when releases must account for existing debt as well, or strict for the full check matrix, including empty selections.

The profile determines how findings affect the decision. Input completeness determines whether the system can make an enforcing decision.

Release Gate Profiles

The gate evaluates evidence completeness before counting findings. It needs a fresh CPG, a complete full or equivalent incremental run, every active rule’s outcome, complete required capabilities, known dependency denominators, classification and resolution coverage, and trusted governance.

Any enforcing profile returns BLOCKED_INCOMPLETE when its inputs are stale, partial, unknown or untrusted. Only PASS sets release_allowed=true. NOT_APPLICABLE means no enforcing decision was requested. A run with zero resolved dependency facts needs a known denominator; it cannot claim 100% resolution coverage from an empty result.

For a working repository, a CI call has this shape. Run from the repository root in PowerShell, with gocpg on PATH, a Git base ref and all four paths configured for the same project. Replace the paths and project key with your own; the policy is a repository policy manifest, not the standalone kind: architecture rule used by architecture validate.

For the first run, create the output directory and parse a CPG from the same repository root. ci-update uses the CPG’s stored source binding; an architecture run with a missing database returns git_source_scope_unavailable.

New-Item -ItemType Directory -Force .gocpg | Out-Null
gocpg parse --input . --output .gocpg/cpg.duckdb --lang python

Then update the graph and produce the architecture artifact:

gocpg ci-update --input . --output .gocpg/cpg.duckdb `
  --base-ref origin/main --head-ref HEAD --lang python `
  --architecture-policy .gocpg/architecture/policy.yaml `
  --architecture-project-key my-repository `
  --architecture-release-control .gocpg/architecture/release-control.yaml `
  --architecture-artifact .gocpg/architecture/result.json --json

The four architecture flags must be supplied together. A minimal release control for reviewing findings can select advisory, but it still must satisfy the current release-control schema and any required repository evidence. Inspect the artifact’s run identity, completeness, rule outcomes and gate status. A successful CLI exit alone does not establish PASS. The adoption guide explains the broader rollout sequence.

Act on the result

Baseline Guide

A baseline identifies debt already reviewed for an exact rule, fingerprint version, finding fingerprint and rule semantic hash. In enforce_new, an exact known finding is excluded from the new-violation count; enforce_all and strict still consider known unwaived debt. A baseline acknowledges the finding. It does not make the dependency acceptable or alter the graph.

Consider a run where UI imports storage. If its fingerprint is reviewed as existing debt, the next identical run can classify it as known. If the rule changes from direct to transitive, its semantic hash changes; the old decision moves to needs_review. If the import disappears and later returns, its lifecycle is regressed, not silently known again.

The safe sequence is a complete full run, a reviewed proposal for each finding, issuance of a signed governance manifest by the control plane, and a new run bound to that manifest. Repository-local baseline exports help review changes but do not authorize suppression.

Waiver and Trust Model

A waiver is an exception for one finding and an expiry. It records rule owner, requester, approver, reason, decision reference, fingerprint, semantic hash, fingerprint version and scope. Requester and approver must be different actors. A changed fingerprint, rule, repository or revision needs a fresh decision; a symbol alias cannot transfer a waiver.

The Ed25519 governance payload binds project, repository, commit, branch, model and rules hashes, validity window and monotonic revision. Trusted public keys and revocation state come from the control plane or CI configuration. Validation checks signature, key ID, revocation, validity and exact scope. Expired, revoked, unused and stale waivers remain visible as findings. A signature or scope failure blocks enforcement with BLOCKED_INCOMPLETE.

For example, if a waiver was signed for commit A and the policy is evaluated at commit B, do not copy its fingerprint into a local YAML file to suppress the finding. Obtain a decision for the current scope after a complete run.

Incremental Scan Semantics

The planner uses changed paths and affected component UIDs to decide whether to reuse previous work. Model, public API, dependency edge, strongly connected component, baseline and waiver changes expand invalidation. Unknown components or a partial invalidation set are errors. The default full-scan threshold is an affected-component ratio greater than 0.20; a model change always selects a full run.

incremental_complete has release authority only when fingerprints, lifecycle states, baseline and waiver states, coverage, semantic digest and gate decision match a full run for the same inputs. A partial enforcing run gets one synchronous full retry. If that retry is partial, failed, stale or mismatched, the result remains BLOCKED_INCOMPLETE.

For example, moving src/ui/ to a new component changes classification and can affect edges that do not appear in the edited file list. The model change therefore triggers a full scan. Merely scanning the changed files would miss relations whose endpoints were reclassified.

Migration Guide

Legacy checks can be migrate, retain advisory, retire or defer. Discovery and advisory may show labelled legacy evidence, but legacy output cannot create canonical PASS, finding lifecycle state, baseline, waiver or release authority.

1. Inventory old handlers and rule packs, assigning each one disposition.
2. Run old and canonical paths in shadow on the same revision; classify each difference by stable fingerprint and source witness.
3. Qualify golden fixtures and resolve unexplained blocking false negatives.
4. Observe two real advisory release cycles with stable semantic identity.
5. Move consumers to persisted canonical results and prove that legacy enforcement is disabled.

Rollback can return enforcement to advisory. It cannot promote an old checker into release authority. A local parity test demonstrates only its fixture scope, not production adoption.

Executable examples for the normative topics

From the gocpg module root, these tests verify implementation contracts. They are not evidence that an arbitrary repository passed its release gate.

go test ./pkg/architecture -run '^TestSignedGovernanceRequiresExactScopeAndSeparationOfDuties$' -count=1
go test ./pkg/architecture -run '^TestNormativeGovernanceRequiresCompleteScopeRevisionAndRevocationState$' -count=1
go test ./pkg/architecture -run '^TestNormativeReleaseGateFiveProfilesAndStateMatrix$' -count=1
go test ./pkg/architecture -run '^TestStory1240FullIncrementalEquivalence$' -count=1
go test ./pkg/architecture -run '^TestCodeGraphReleaseGateRejectsLegacyAuthorityInEnforceNew$' -count=1