Design checks

A design check grades a proposed change against your architecture: the standards you have recorded, the compliance frameworks and custom policy packs you have applied, the metamodel your account permits, and the current-state structure your connectors discovered.

It runs from a pipeline through the REST API, from an AI coding agent through the MCP server, or from a terminal. The verdict cites what it was judged against, so a developer told “no” also learns why.

Adding it to a pipeline

GitHub Actions

permissions:
  contents: read
  security-events: write     # so findings land on the diff

steps:
  - uses: actions/checkout@v4
    with: { fetch-depth: 0 }

  - uses: archngn/archngn-app/integrations/github-action@main
    with:
      token: ${{ secrets.ARCHNGN_TOKEN }}
      diff-against: origin/${{ github.base_ref }}
      artifacts: |
        openapi=openapi.yaml

security-events: write is the line worth getting right: with it, every finding is annotated on the offending line of the pull request through code scanning, which is the difference between a check people read and one they scroll past.

Templates for GitLab CI and Azure DevOps work the same way, and anywhere else:

pipx install archngn-check
archngn check --artifact terraform_plan=plan.json --diff-against origin/main

You do not describe your architecture to it

The check reads the artifacts your build already produces.

Artifact	Where it comes from	What it establishes
OpenAPI spec	your spec file	endpoints, and whether each is authenticated
Terraform plan	terraform show -json tfplan	what the change provisions — and what changes, since a plan states actions
SBOM	CycloneDX or SPDX	dependencies
Kubernetes / Compose	your manifests	workloads, and the services they are configured to call
Git diff	--diff-against origin/main	line numbers — the only artifact that has them

Send the ones you have. An artifact that fails to parse becomes a warning on the result, never a failed build: one bad input out of five must not stop the gate, but you are told the check graded less than you sent.

Matching the change to the right system

The highest-value thing you can supply is an identity signal — a repository URL, a container image reference, a cloud resource id. The repository URL is detected automatically from every supported CI platform.

With one, the change is graded against that system’s recorded owners, criticality and existing integrations. Without one, it is graded on the change alone, and the result says so.

What it looks at

Four deterministic evaluators, in order:

1. Registry resolution — is this component in the model? If not, that is itself worth knowing: code that is about to deploy and has never been registered.
2. Metamodel conformance — does the change introduce a type or relationship your account’s model does not permit?
3. Rule conformance — the frameworks and custom policy packs you have applied, run over the change as if it had landed.
4. Structural drift — a new dependency on a system you have decided to retire, a second integration style between systems that already integrate, a new link into a more critical system with nothing governing it, or the removal of a link something critical depends on.

Findings are limited to what the change is answerable for. Pre-existing gaps elsewhere in the registry belong in the conformance report, not in somebody’s build.

Three depths

fast     every commit          blocking gate, no AI, milliseconds
deep     every pull request    + an AI pass over your written standards
review   release or nightly    the full design review document

fast is the four evaluators above. No AI, no credit cost, and it runs even when your monthly allowance is exhausted.

deep adds one bounded AI pass that reads the standards nobody encoded as a rule — which is most of them.

Deep findings are always advisory. They report at their assessed severity and can move a verdict to warn, never to fail. An AI in the blocking path would make a build non-reproducible: the same commit passing on Tuesday and failing on Wednesday. The useful consequence is that turning deep on cannot break a pipeline that fast was already passing.

review queues a full Design Review and produces a document in the workspace. It returns immediately with an id to poll; there is no verdict, because the output is a document rather than a judgement.

See Usage for what each costs.

Passing and failing

Your pipeline sets the blocking threshold — severity is our judgement, blocking is your policy. Start at high.

A failing check is still a successful request. The verdict is in the response body and in a header; the HTTP status is not the verdict. A pipeline that cannot tell “your architecture is wrong” from “the gate is unreachable” ends up ignoring both.

Two categories never block at any threshold: findings from a pack or rule set to Advisory, and findings whose risk has been accepted. Only rules set to Enforce can fail a check.

Accepting a risk

The gate will be wrong eventually. The honest response is to accept the risk, with a reason and an expiry, not to switch the step off. Do it from the check’s findings under Governance → Checks, or from a terminal:

archngn waive \
  --rule structure.dependency-on-retiring-system \
  --subject legacy-core \
  --reason "Cutover to the replacement is scheduled for Q4, tracked in ARCH-412." \
  --days 90

Three things keep an accepted risk honest, and none is optional:

• A reason is required, and short ones are refused. A suppression nobody can explain later is one nobody can review.
• An expiry is required: 90 days by default. A permanent exception is an undocumented architecture decision that outlives everyone who understood it.
• The finding still appears in every result, marked as accepted. It leaves the verdict and nothing else.

Accepted risks are listed under Governance → Exceptions, where they can be renewed with a new reason and expiry, or revoked. A revoked risk can’t be renewed.

Accepting a risk needs the check:waive scope on a token, or the same capability in the app, which account admins have. The person a gate blocks should not also be the person who can unblock it unobserved. Accepting and revoking are both recorded in the audit log.

History in the app

Governance → Checks lists every check run against the active workspace: when, the component, the source, the mode, the verdict (Pass, Warn or Fail) and the findings. Filter by component, mode, verdict, or whether a check had findings. Open a check to see each finding with the standard it cited, the standard’s intent and reasoning, and what to do.

Above the list:

• Changes checked: checks by month for the last six months: passed, warned, and stopped before merge.
• Drift: structural findings inside recent checks: unregistered components, new dependencies on retiring systems, and new integration styles.

With no checks yet, the tab explains how to connect a pipeline or an agent, and offers Create a token.

Every check is recorded with its verdict and counts. The full findings are kept only when the run asks with record: true, because a per-commit gate fires dozens of times a day per repository. Ask for them on the runs worth reading again later: a nightly deep check, a release gate, an audit answer.

Reading the history needs only workspace read access. A developer should be able to see why their build was blocked without an admin in the loop.

Related

• REST API and tokens: the endpoints and the token scopes.
• MCP server: the same engine, for AI coding agents.
• Findings: the same rules, applied to the estate as it stands.
• Frameworks and Custom policies: the rules a check grades against.
• Exceptions: every accepted risk, with who accepted it and why.
• Reference Library: where the standards it cites are written.