archgate check

Run all automated ADR compliance checks against the codebase.

archgate check [options] [files...]

Loads every ADR with rules: true in its frontmatter, executes the companion .rules.ts file, and reports violations with file paths and line numbers. When file paths are provided as positional arguments, only ADRs whose files patterns match those files are executed.

Options

Option	Description
--staged	Only check git-staged files (useful for pre-commit hooks)
--base [ref]	Compare changed files against a base ref (auto-detects when omitted)
--output <format>	Output format: console (default), json, github, or sarif. See SARIF output.
--adr <id>	Only check rules from a specific ADR
--verbose	Show passing rules and timing info
--strict	Treat any rule-severity warning, and advisory findings (briefing budget, suppression, unparsed ADRs), as failures. See Strict mode.

Arguments

Argument	Description
[files...]	Optional file paths to scope checks to. Only ADRs whose files patterns match will run. Supports stdin piping.

Exit codes

Code	Meaning
0	All rules pass. No violations found.
1	One or more violations detected, or --strict escalated warnings or advisory findings into failures.
2	Rule execution error (e.g., malformed rule, security scanner block).

Examples

Check the entire project:

archgate check

Check only staged files before committing:

archgate check --staged

Check all files changed on the current branch vs main:

archgate check --base main

Check a single ADR:

archgate check --adr ARCH-001

Treat any rule-severity warning and any advisory finding (briefing budget, suppression, unparsed ADRs) as a failure (useful in CI):

archgate check --strict

Check specific files (only matching ADRs run):

archgate check src/foo.ts src/bar.ts

Pipe from git (check only changed files):

git diff --name-only | archgate check --output json

Get JSON output for CI integration:

archgate check --output json

Get GitHub Actions annotations:

archgate check --output github

Get SARIF output for GitHub Code Scanning:

archgate check --output sarif > results.sarif

SARIF output

archgate check --output sarif emits SARIF 2.1.0, the standard format GitHub’s Code Scanning and Code Quality features ingest in CI. Every rule violation becomes a SARIF result; error/warning/info severities map to SARIF error/warning/note. Advisory findings (briefing-budget, suppression, and unparsed-ADR warnings) are included too, as synthetic results under dedicated rule IDs (archgate/briefing-budget, archgate/suppression-warning, archgate/unparsed-adr), always at warning level — matching how they’re never treated as blocking outside --strict.

--output sarif is opt-in only: unlike agent-context json, it is never auto-detected.

Upload results to GitHub’s Security tab in CI:

- name: Run archgate check
  run: archgate check --output sarif > results.sarif

- name: Upload SARIF to GitHub Security tab
  if: success() || failure()
  uses: github/codeql-action/upload-sarif@7188fc363630916deb702c7fdcf4e481b751f97a # v4.37.1
  with:
    sarif_file: results.sarif

The if: success() || failure() condition is required: archgate check exits 1 when it finds violations, which would otherwise skip the upload step exactly when there are findings to report. Prefer it over always(), which would also run the upload for cancelled jobs. The job also needs the security-events: write permission for the upload to succeed.

See the CI integration guide for the full workflow.

Changed files detection

By default, archgate check auto-detects the base branch and populates ctx.changedFiles with the branch diff (git diff <base>...HEAD) plus any uncommitted working-tree changes (staged, unstaged, and untracked non-ignored files). This enables cross-file dependency rules to work locally — not just in CI — and ensures edits that haven’t been committed yet are still checked.

The base ref is resolved in priority order:

Priority	Source	changedFiles populated with
1	--staged	Git staging area only
2	--base <ref>	git diff <ref>...HEAD + working-tree changes
3	.archgate/config.json baseBranch	git diff <resolved-ref>...HEAD + working-tree changes
4	Git auto-detect	git diff <detected-ref>...HEAD + working-tree changes
5	Detection fails	Empty (full-scan mode)

Auto-detection tries origin/HEAD, then origin/main, origin/master, local main, and local master. To set a project default, add baseBranch to .archgate/config.json:

{ "baseBranch": "main" }

Diagnostics

During execution, archgate check emits warnings for common misconfigurations that may cause slow or unexpected results:

Warning	Condition	Recommendation
Broad file scope	An ADR’s files patterns resolve to more than 1,000 files or the glob scan takes over 2 seconds	Narrow the files patterns in the ADR frontmatter to target only the relevant source directories
Unscoped gitignore opt-out	respectGitignore: false is set without a files scope	Add files patterns to avoid scanning all files including node_modules/, .git/, etc.
All files excluded by gitignore	Explicit files patterns match files, but every match is excluded by .gitignore	Set respectGitignore: false in the ADR frontmatter to include gitignored files

These warnings appear in the standard output and do not affect the exit code. They also appear in JSON output when --output json is used (as violations with "severity": "warning").

Briefing budget

archgate review-context --verbose embeds each applicable ADR’s Decision and Do’s and Don’ts sections and truncates each one at a fixed character cap. Prose past that point never reaches the agent the ADR governs, and no companion rule can detect it — rules measure code, not the ADR’s own prose.

archgate check therefore reports every ADR section that exceeds the cap, across all ADRs including those with rules: false:

[briefing] ARCH-024 "Decision" is 3574 chars; review-context truncates at 2000, hiding 1574 from agent briefings

The same entries appear in JSON output under briefingWarnings, with adrId, file, section, length, and cap.

An ADR that cannot be read or parsed is measured by nothing, so it is reported separately rather than counted as compliant:

[adr] could not be parsed, so it was excluded from every check above  .archgate/adrs/BROKEN.md

JSON output lists those files under unparsedAdrs. An empty briefingWarnings means “nothing over budget” only when unparsedAdrs is empty too — otherwise part of the corpus was never inspected.

These are advisory and never affect pass, unless --strict is set — see Strict mode.

To clear an overflow, apply the remedies that cannot cost a rule: move rationale into Context or Consequences, which are never briefed and therefore never capped; drop historical narration; and merge bullets stating the same rule twice.

If the next cut would remove a normative clause — an enumerated identifier list, an ordered guardrail, an exemption — stop. That section is expected to exceed the cap and MUST NOT be shortened further. Record why in the ADR’s own Compliance section, and order the section so its most normative content precedes the cut, since truncation always removes the tail.

By default, warnings (both diagnostics and rule-reported "severity": "warning" violations) never change the exit code. Pass --strict to escalate them into failures — see Strict mode.

Strict mode

--strict combines two escalations behind one flag: any rule-severity "warning" violation fails the build (the JSON output’s warningsExceeded field is true and pass is false), and it separately fails the build when briefingWarnings, suppressionWarnings, or unparsedAdrs is non-empty — the advisory diagnostics above that never affect pass by default. The JSON output’s strictAdvisoryExceeded field is true when the latter condition triggered the failure.

The briefing-budget and unparsed-ADR diagnostics are corpus-wide, not rule-scoped: they are collected and enforced even when no rules: true ADR exists, so a prose-only ADR corpus still fails --strict on a briefing overrun or an unparseable ADR file. Suppression warnings, by contrast, derive from rule violations and only arise when rules run.

--strict also applies to archgate review-context and archgate adr sync. See the Configuration reference for the full schema.

To avoid passing --strict on every invocation, set a project default in .archgate/config.json:

{ "strict": true }

There is no --no-strict flag: --strict on the command line can only turn strict mode on over an absent or false config default — it cannot turn off a configured strict: true.

JSON output format

When --output json is used, the output is a single JSON object.

results contains only rules that have something to report: failures, rule errors, and any rule with violations (including warning- and info-only rules). Rules that pass cleanly are omitted — their entry would only restate static ADR text, and on a large project those entries dominate the payload. The total and passed counts still report exactly how many rules ran and passed. Pass --verbose to include every rule in results.

{
  "pass": false,
  "total": 4,
  "passed": 3,
  "failed": 1,
  "warnings": 0,
  "errors": 1,
  "infos": 0,
  "ruleErrors": 0,
  "warningsExceeded": false,
  "strictAdvisoryExceeded": false,
  "truncated": false,
  "results": [
    {
      "adrId": "ARCH-001",
      "ruleId": "register-function-export",
      "description": "Command file must export a register*Command function",
      "status": "fail",
      "totalViolations": 1,
      "shownViolations": 1,
      "violations": [
        {
          "message": "Command file must export a register*Command function",
          "file": "src/commands/broken.ts",
          "line": 1,
          "endLine": 1,
          "endColumn": 42,
          "severity": "error"
        }
      ],
      "durationMs": 12
    }
  ],
  "durationMs": 42
}

Violation fields

Field	Type	Description
message	string	What the violation is
file	string?	Relative file path
line	number?	Start line (1-based)
endLine	number?	End line (1-based) — for precise editor highlighting
endColumn	number?	End column (0-based) — for precise editor highlighting
fix	string?	Suggested fix (guidance only)
severity	string	"error", "warning", or "info"

Blocked rule files

When a rule file is blocked by the security scanner (e.g., uses Bun.spawn()) or a companion .rules.ts file is missing, the result appears in the JSON output with status: "error" and ruleId: "security-scan". Violations include the exact file and line of the blocked code (or the rules: true line in the ADR for missing companions).