RodriOliveira.AdrGuard 1.2.0

ADR Guard

Português (Brasil)

GitHub Action consumers: see the consumer guide, AI review guide, release policy, security model, public release audit, external verification evidence, and Marketplace publication checklist. The moving @v1 tag is published and exercised by CI against its public check/index contract; opt-in review is published on the v1 line since v1.1.6. Marketplace listing: ADR Guard - Architecture Decision Validator. The listing URL was supplied by the repository owner on 2026-10-07; independent logged-out verification is still pending. Support is available through SUPPORT.md; security reports follow SECURITY.md.

Version availability: Offline new and template-aware draft are published since v1.1.0. CLI review is published since v1.1.2, deterministic review policy since v1.1.3, review security/regression hardening since v1.1.4, and opt-in GitHub Action command: review since v1.1.6. Use the NuGet badge or GitHub Releases as the source of truth for the latest exact patch; documentation intentionally avoids hard-coding a moving "current" patch.

ADR Guard is a lightweight .NET command-line tool for validating and indexing Architecture Decision Records (ADRs).

It is designed for repositories that want ADR conventions to be explicit, reviewable, and enforceable in local development and CI without introducing a heavy runtime dependency.

Features

• validates ADR filenames, titles, statuses, and required sections;
• detects duplicate ADR IDs;
• detects broken relative links between ADRs;
• enforces a valid Superseded by link for superseded decisions;
• generates a deterministic Markdown index;
• avoids rewriting an index that is already current;
• exposes stable validation codes (ADR001 through ADR009);
• exposes predictable exit codes for CI/CD;
• creates human-editable Proposed ADRs offline using built-in or custom Markdown templates;
• supports human-reviewed AI-assisted Proposed ADR drafting through explicit providers and context;
• reviews existing ADRs across eight architectural dimensions with evidence, uncertainty, versioned reports, and optional deterministic policy enforcement;
• ships as a .NET Tool with no third-party runtime dependencies.

Install

Releases are published to both NuGet.org and GitHub Packages.

The simplest installation uses NuGet.org:

dotnet tool install --global RodriOliveira.AdrGuard

Update an existing installation with:

dotnet tool update --global RodriOliveira.AdrGuard

GitHub Packages is also available as a secondary registry. NuGet clients require GitHub authentication to consume packages from that source.

The installed command is:

adr-guard

Container images

ADR Guard is also distributed as the same release version through GHCR and Docker Hub:

ghcr.io/rodri-oliveira-dev/adr-guard
docker.io/rodrigodotnet/adr-guard

Images support linux/amd64 and linux/arm64 and publish exact SemVer, minor, major, and latest tags. For example:

docker run --rm \
  -v "$PWD:/workspace:ro" \
  ghcr.io/rodri-oliveira-dev/adr-guard:latest \
  check docs/adr

The image runs as a non-root user. Release images include OCI metadata, SBOM and provenance attestations, and the CI path is gated by Hadolint, smoke tests, Dependabot base-image updates, and a Trivy vulnerability scan.

See the container image and supply-chain guide for writable mounts, AI-provider credentials, immutable digest pinning, tags, and verification details.

GitHub Action

ADR Guard provides a composite GitHub Action that invokes the published GHCR image directly, so consuming repositories do not need to install the .NET SDK. The repository must be checked out first, and the action supports Linux runners with a working Docker daemon, such as ubuntu-latest.

The moving @v1 compatibility tag is published. Consumers can use uses: rodri-oliveira-dev/adr-guard@v1; the GitHub Marketplace listing is available as the owner-provided listing URL; independent logged-out verification remains pending.

For complete pull-request/main workflows, inputs, annotations, required-check configuration, troubleshooting, and release/Marketplace status, use the GitHub Action consumer guide.

The default operation validates docs/adr:

name: ADR validation

on:
  pull_request:
  push:

permissions:
  contents: read

jobs:
  adr-guard:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v7
        with:
          persist-credentials: false

      - name: Validate ADRs
        uses: rodri-oliveira-dev/adr-guard@vX.Y.Z
        with:
          path: docs/adr
          command: check

Inputs are deliberately small and map directly to supported CLI behavior:

Input	Default	Allowed values / policy
path	docs/adr	Repository-relative ADR directory. Absolute paths, .. traversal, missing directories, and paths resolving outside GITHUB_WORKSPACE are rejected.
command	check	check, index, or explicit review. review is available on the published v1 line since v1.1.6; new and draft are not Action commands.
version	empty	Optional exact image version in X.Y.Z or vX.Y.Z form. When omitted, @vX.Y.Z selects the exact image tag and @vX selects the matching moving major image tag. SHA/branch pins require an explicit exact version.

Version selection never falls back to latest. For uses: rodri-oliveira-dev/adr-guard@v1.2.3, the Action invokes ghcr.io/rodri-oliveira-dev/adr-guard:1.2.3. For uses: rodri-oliveira-dev/adr-guard@v1, it invokes the matching moving major image tag :1. Exact Action tags are immutable; major tags move only to newer successful releases in that major line. If the Action is pinned by commit SHA or a branch, specify the image explicitly:

- name: Validate ADRs from a pinned action commit
  uses: rodri-oliveira-dev/adr-guard@<commit-sha>
  with:
    path: architecture/adr
    command: check
    version: 1.2.3

See the GitHub Action release policy for exact versus major tag semantics, idempotency guarantees, release ordering, and the verification procedure.

The check command mounts the checked-out workspace read-only, so validation cannot mutate repository files. For index, the workspace remains read-only and only the selected ADR directory is over-mounted as writable because the CLI generates or refreshes README.md there:

- name: Generate ADR index
  uses: rodri-oliveira-dev/adr-guard@vX.Y.Z
  with:
    path: docs/adr
    command: index

- name: Fail if the generated index was not committed
  run: git diff --exit-code -- docs/adr/README.md

All user inputs are passed as discrete process arguments rather than executable shell fragments. Paths are resolved against the checked-out workspace before Docker starts, including symlink resolution, and the CLI exit-code contract remains unchanged: 0 success, 1 validation failure, 2 usage/input error, and 3 operational error.

When a check or index run returns exit code 1, the action converts recognized ADR001–ADR009 CLI diagnostics into GitHub file-level error annotations for existing ADR files within the validated directory. The CLI does not provide reliable line numbers, so annotations deliberately do not include a line number. Diagnostic paths and messages are validated and escaped before emitting workflow commands; unexpected output or operational failures are not annotated as ADR rules.

The action writes a compact GITHUB_STEP_SUMMARY with the outcome, exit code, and (for validation failures with recognized output) total and per-rule diagnostic counts. At most 50 file annotations are emitted per run; all diagnostics remain available in the raw CLI log. Raw output is replayed with GitHub workflow-command processing temporarily suspended to prevent untrusted ADR content from injecting annotations or other workflow commands. Reporting errors never replace the original CLI exit code.

The default check/index Action path does not require provider credentials or network access and keeps --network=none. Published opt-in review uses outbound network only for the selected provider, keeps the checkout read-only, forwards only the selected provider credential variable, never forwards GITHUB_TOKEN/GH_TOKEN, accepts only push, workflow_dispatch, schedule, and same-repository pull_request events, rejects all other event types before provider execution, and still needs only permissions: contents: read. AI-assisted draft remains outside the Action contract. See the GitHub Action AI review guide and security model.

Windows, macOS, Linux runners without a working Docker daemon, and root execution for writable index are not supported.

The published rodri-oliveira-dev/adr-guard@v1 Action supports check, index, and opt-in review. new and AI draft remain CLI/.NET Tool or direct-container workflows, not Action commands.

ADR format

ADR Guard expects Markdown files named with a four-digit ID followed by a lowercase kebab-case slug:

0001-use-postgresql.md

A minimal valid ADR looks like this:

# Use PostgreSQL

## Status

Accepted

## Context

We need a relational database.

## Decision

Use PostgreSQL.

## Consequences

The service depends on PostgreSQL operational knowledge.

Supported statuses:

• Proposed
• Accepted
• Deprecated
• Superseded

The required sections are Context, Decision, and Consequences. A Superseded ADR must also contain a Superseded by section linking to an existing ADR.

Create Proposed ADRs offline

The published adr-guard new command creates an editable ADR without AI, credentials, or network access. The destination directory must exist. Minimal and en-US are the defaults; Extended and Custom are opt-in.

mkdir -p docs/adr
adr-guard new docs/adr --title "Adopt Redis"
adr-guard new docs/adr --title "Adopt Kafka" --template extended --culture pt-BR
adr-guard new docs/adr --title "Adopt Cache" --template-file docs/examples/templates/team.en-US.md
adr-guard new docs/adr --title "Preview only" --template minimal --preview
adr-guard check docs/adr
adr-guard index docs/adr

--dry-run is an alias for --preview; neither writes an ADR, updates the index, or reserves an ID. new never updates the index automatically: run check and then index explicitly. --template minimal|extended and --template-file <path> are mutually exclusive. --culture en-US|pt-BR localizes instructional text, not the invariant headings Status, Context, Decision, Consequences or initial Proposed status. Custom files must be UTF-8 .md, at most 65,536 bytes, selected individually and resolved relative to the invocation directory; store templates outside the ADR directory. Creating uses the next ID after the highest existing ID, locks cooperating same-host creators and writes atomically without overwrite; {{id}} is regenerated using the final allocated ID. Structural validation is not architectural approval; an architect must review and replace the editable notes.

Validator-compliant samples: Minimal EN, Extended pt-BR, Custom EN, Custom pt-BR. Read the full offline creation and exit-code guide and custom placeholder rules. Native MADR/alternate-format validation is not supported.

Validate ADRs

v1.2.0 preparation: init, .adrguard.yml, and check --format json|sarif are available from source on the v1.2 development branch. They are not part of a published release until the independent manual v1.2.0 release completes.

Validate a directory recursively:

adr-guard check docs/adr

When the directory is omitted, ADR Guard uses the current directory:

adr-guard check

A successful validation returns exit code 0. Validation failures are printed with the file path, stable rule code, and message.

Example:

docs/adr/0002-use-cache.md: ADR004 Status 'Approved' is invalid. Allowed values: Proposed, Accepted, Deprecated, Superseded.
Validation failed with 1 issue(s).

Source builds prepared for v1.2.0 can initialize a repository and reuse optional configuration:

adr-guard init --adr-directory docs/adr --template minimal --github-actions
adr-guard check

Precedence is explicit CLI arguments, then .adrguard.yml, then legacy defaults. Without configuration, all existing commands retain their previous defaults. The configuration file accepts only the documented scalar schema; it never executes tags, aliases, substitutions, or commands. See the v1.2 CLI and configuration reference.

check keeps text output as the default and can emit deterministic JSON or SARIF 2.1.0 to stdout:

adr-guard check docs/adr --format json
adr-guard check docs/adr --format sarif > adr-guard.sarif

Machine-readable output remains a valid document when validation returns exit code 1; operational messages use stderr. The JSON schema, reporting guide, and least-privilege Code Scanning example define the contracts.

Generate the ADR index

Validate the ADR set and generate README.md inside the ADR directory:

adr-guard index docs/adr

The generated file is deterministic:

# Architecture Decision Records

| ADR | Decision | Status |
| --- | --- | --- |
| [0001](0001-use-postgresql.md) | Use PostgreSQL | Accepted |
| [0002](0002-adopt-opentelemetry.md) | Adopt OpenTelemetry | Proposed |

The index is written only after validation succeeds. If the existing file already matches the generated content, it is left untouched.

A custom output outside the ADR directory can be supplied with:

adr-guard index docs/adr --output adr-index.md

Inside the ADR directory, generated Markdown must be named README.md; otherwise it would become an ADR candidate on the next validation.

AI-assisted ADR drafting

ADR Guard can ask a configured external AI provider to draft an ADR while keeping persistence, context selection, and architectural acceptance under human control. AI output is always treated as a proposal: ADR Guard forces the generated status to Proposed, validates the document structure, and never accepts an architectural decision on behalf of the team.

A minimal persisted draft uses only the inline architectural context supplied on the command line:

adr-guard draft docs/adr \
  --title "Adopt a message broker" \
  --context "We need asynchronous integration." \
  --provider openai \
  --model <openai-model>

The normal persistence workflow allocates the next ADR ID deterministically, creates a compliant filename, and validates the generated candidate with the normal ADR parser/validator. Persistence writes the complete candidate to a temporary file in the ADR directory, flushes it, and only then atomically promotes it to the final filename without overwrite. If cancellation, provider failure, validation failure, an I/O error, or a concurrent filename race occurs, ADR Guard does not leave a partial final ADR and cleans up its temporary file.

The production CLI propagates cancellation through the draft workflow. Pressing Ctrl+C requests graceful cancellation across context loading, provider HTTP calls, validation boundaries, and persistence.

Optional templates for AI-assisted drafts

Without --template or --template-file, draft retains its original rendering, supported .NET cultures, provider contract and explicit context selection. With a selected template, only the final rendering changes locally: template source, guidance and path are never sent to the AI provider. Use --template minimal|extended or --template-file docs/examples/templates/team.en-US.md alongside the existing --provider, --model, --title and --context. Existing ADRs are shared only with explicit --include-existing-adrs; context files only with explicit --context-file. Unlike offline new --preview, draft --preview still calls the provider but skips persistence. See the AI template/privacy guide.

Providers, models, and authentication

ADR Guard does not choose a model automatically. Both --provider and --model are required at runtime.

Provider	CLI value	Authentication	Endpoint
OpenAI	openai	OPENAI_API_KEY	official endpoint; custom --endpoint rejected
Anthropic	anthropic	ANTHROPIC_API_KEY	official endpoint; custom --endpoint rejected
Gemini	gemini	GEMINI_API_KEY	official endpoint; custom --endpoint rejected
OpenAI-compatible	openai-compatible	ADR_GUARD_OPENAI_COMPATIBLE_API_KEY (optional)	--endpoint <uri> required

Examples:

adr-guard draft docs/adr --title "Decision" --context "Context" \
  --provider anthropic --model <anthropic-model>

adr-guard draft docs/adr --title "Decision" --context "Context" \
  --provider gemini --model <gemini-model>

adr-guard draft docs/adr --title "Decision" --context "Context" \
  --provider openai-compatible --model <model> \
  --endpoint https://example.internal/v1

Authentication is read from environment variables rather than CLI arguments, which keeps credentials out of command history and ADR content. The CLI reports provider and model selection but does not print authentication values.

For openai-compatible, remote endpoints must use HTTPS even when no API key is configured, because the architectural context itself may be sensitive. Plain HTTP is allowed only for loopback endpoints such as localhost, 127.0.0.1, or ::1, which keeps local Ollama/LM Studio-style workflows available. If ADR_GUARD_OPENAI_COMPATIBLE_API_KEY is set, HTTPS is required even for loopback endpoints so the Bearer credential is never sent over plaintext transport. Official OpenAI requests explicitly set store: false.

Language and inline context

--context supplies the architectural problem or constraints directly and remains required. Generated prose defaults to en-US; use a .NET globalization culture name such as pt-BR when another language is desired:

adr-guard draft docs/adr \
  --title "Adotar cache distribuído" \
  --context "Precisamos reduzir a latência de leitura." \
  --culture pt-BR \
  --provider openai \
  --model <openai-model>

Canonical ADR headings and the Proposed status remain unchanged regardless of the selected culture. Provider-generated prose is rejected if it attempts to introduce another level-one title or duplicate canonical level-two Status, Context, Decision, or Consequences sections. Headings inside fenced code blocks remain ordinary section content.

Context size limits

ADR Guard bounds provider input deterministically before invoking the configured AI provider:

Context source	Maximum
Inline --context	20,000 characters
Each --context-file	50,000 characters
All explicit context files combined	100,000 characters
Parsed existing ADR context	12,000 characters
Final composed generation context	120,000 characters

Explicit files are read only up to the per-file limit plus one character so arbitrarily large files are not loaded fully just to detect overflow. Oversized inline, per-file, aggregate, or composed context is rejected with an actionable error before provider invocation. Explicit files are never silently truncated.

Existing ADR context

Existing ADRs are not sent to an AI provider by default. Add --include-existing-adrs to opt in:

adr-guard draft docs/adr \
  --title "Adopt a message broker" \
  --context "We need asynchronous integration." \
  --include-existing-adrs \
  --provider openai \
  --model <openai-model>

ADR Guard builds this context from parsed ADR data rather than concatenating repository files. Each selected ADR contributes its ID, title, status, decision, and local Markdown relationships. Ordering is deterministic by numeric ID and then filename.

Existing ADR context is bounded to 12,000 characters. Complete ADR representations are appended in deterministic order while they fit; when the next complete representation would exceed the limit, that ADR and all following ADRs are omitted. Individual ADR fields are not partially truncated by this strategy. The CLI explicitly warns when existing ADR content will be sent to the provider.

Explicit context files

Use repeatable --context-file <path> options to add explicitly selected Markdown or text files:

adr-guard draft docs/adr \
  --title "Adopt a message broker" \
  --context "We need asynchronous integration." \
  --context-file ./architecture/constraints.md \
  --context-file ./notes/runtime.txt \
  --provider openai \
  --model <openai-model>

Only the exact .md and .txt paths supplied by the user are read. ADR Guard does not recursively scan the repository, source tree, sibling files, or parent directories. Multiple files are composed in the same order in which they appear on the command line.

Before generation, the CLI prints the resolved local paths being used. The provider request contains each selected file's name and content, not its resolved local filesystem path.

Context composition is deterministic:

1. inline --context;
2. explicit --context-file content in command-line order;
3. parsed existing ADR context when --include-existing-adrs is enabled.

Preview without persistence

Use --dry-run or its alias --preview to exercise the normal generation and validation path without creating a file:

adr-guard draft docs/adr \
  --title "Adopt a message broker" \
  --context "We need asynchronous integration." \
  --provider openai \
  --model <openai-model> \
  --dry-run

Preview calculates the same deterministic candidate ID and filename, generates the ADR, forces Proposed, parses and validates it, then prints the candidate path and complete generated Markdown. It skips only the final write step: the ADR directory and generated index remain unchanged.

Privacy, limitations, and human review

Any inline context, explicitly selected context-file content, and opted-in existing ADR context is sent to the configured external provider. Review selected material for credentials, personal data, confidential business information, and other sensitive content before generation. Provider-side storage, retention, training, and processing behavior is governed by the provider you configure.

AI-assisted drafting deliberately remains human-in-the-loop. Generated ADRs can be structurally valid while still containing incorrect assumptions, weak trade-offs, security problems, or fabricated details. A human architect or responsible reviewer must review the architectural reasoning before changing an ADR from Proposed to another status.

This workflow does not perform source-code scanning, repository-wide context ingestion, Git diff analysis, automatic detection that an ADR is required, automatic modification of existing ADR statuses, commits or pull requests, RAG/vector search/embeddings, provider fallback, or automatic model routing.

AI-assisted technical review of existing ADRs

adr-guard review is a separate, read-only workflow for reviewing one existing ADR. It does not rewrite the ADR, change its status, update the index, approve/reject the decision, or treat model output as an objective CI gate.

Minimal usage:

adr-guard review docs/adr/0007-cache-strategy.md \
  --provider openai \
  --model <openai-model>

The same provider/model/authentication contract used by draft applies to review: OpenAI/OPENAI_API_KEY, Anthropic/ANTHROPIC_API_KEY, Gemini/GEMINI_API_KEY, or openai-compatible with an explicit endpoint and optional ADR_GUARD_OPENAI_COMPATIBLE_API_KEY. ADR Guard never chooses the model automatically.

Review accepts explicit repeatable --context-file <path>, optional --include-existing-adrs, --policy advisory|enforce, --policy-file <path>, --format text|json, and optional report persistence through --output <path> [--overwrite].

Context remains opt-in and bounded:

Review source	Maximum
Each explicit --context-file	50,000 characters / 150,000 bytes
All explicit context files	100,000 characters / 300,000 bytes
Parsed existing ADR context	12,000 characters
Final composed review context	120,000 characters

By default, only the selected ADR is sent to the configured external provider. Explicit context files must be valid UTF-8 .md/.txt; existing ADR discovery occurs only with --include-existing-adrs. Selected material can leave the local machine/organization and is subject to provider retention, logging, residency, training, billing, quota, and rate-limit policies. To opt out of third-party processing, do not invoke review; check, index, and new remain deterministic/offline workflows.

Every provider response must cover eight dimensions: clarity/rationale, alternatives, non-functional requirements, risks/consequences, architectural consistency, security/compliance, implementation/operational feasibility, and measurable verification criteria. Findings are classified as observed-evidence, potential-risk, missing-context, recommendation-for-human-investigation, or not-applicable. Missing context, potential risks, severe wording, and model recommendations remain advisory.

--policy advisory is the default. --policy enforce --policy-file <path> can fail only deterministic local rules (required-section-content and required-context-file in schema 1.0) and returns exit code 4 before provider invocation when a named rule fails. A passing policy is still not architectural approval.

Text reports are human-readable Markdown-compatible output. --format json emits schema version 1.0 with stable camelCase fields, selected input scope, all dimensions, follow-up findings, uncertainty, limitations, and cost caveat. Provider/transport/timeouts/rate limits/malformed responses are exit 3, never “no issues”.

For the complete public contract, report example, evidence semantics, policy matrix, Action workflow, fork/community guidance, release availability, and troubleshooting, see the AI review guide, policy v1, and security boundary.

Human ownership is mandatory: review output is architectural assistance, not proof of correctness, formal security/compliance certification, or automated acceptance.

Validation rules

Code	Validation
ADR001	Filename must match NNNN-lowercase-kebab-case.md
ADR002	Level-one title is required
ADR003	Status is required
ADR004	Status must be supported
ADR005	Required section is missing or empty
ADR006	ADR ID is duplicated
ADR007	Relative ADR reference is broken
ADR008	Superseded ADR has no valid Superseded by link
ADR009	Canonical level-two ADR section is duplicated

ADR IDs do not need to be contiguous. Gaps are allowed because ADRs may be archived, migrated, or removed without renumbering historical decisions.

Exit codes

Code	Meaning
0	Success
1	ADR validation failed
2	Invalid command-line usage
3	Operational/provider/cancellation error
4	Deterministic review --policy enforce rule failed

This makes CI integration straightforward:

- name: Validate ADRs
  run: adr-guard check docs/adr

Build from source

Requirements:

• .NET SDK 10.0.400 or a compatible patch in the same feature band.

Build and test:

dotnet restore AdrGuard.slnx
dotnet build AdrGuard.slnx --configuration Release --no-restore
dotnet test AdrGuard.slnx --configuration Release --no-build

Create the tool package:

dotnet pack src/AdrGuard/AdrGuard.csproj --configuration Release --no-build --output artifacts/package

Install the locally built baseline package (the repository VersionPrefix is a release-series baseline, not the latest public patch):

dotnet tool install --tool-path ./.tools RodriOliveira.AdrGuard --version 1.1.0 --add-source ./artifacts/package
./.tools/adr-guard check docs/adr

Architecture decisions

ADR Guard validates its own architecture decisions. See docs/adr.

The repository CI builds and tests the solution, packages the .NET Tool, installs that package locally, runs the packaged adr-guard against docs/adr, regenerates the ADR index, and verifies that no documentation drift was introduced. The container path additionally lints the Dockerfile, builds and smoke-tests the image, and blocks fixable HIGH or CRITICAL vulnerabilities detected by Trivy.

For release highlights, see the v1.1.0 release notes (pt-BR) and the exact AI review release availability matrix (pt-BR).

Additional resources

For more background on Architecture Decision Records, including documents, templates, and examples:

• Architecture Decision Record reference repository

Releases

After a pull request is merged into main, the release workflow waits for the CI workflow for that main commit to complete successfully. It then:

1. resolves a stable SemVer version, starting from VersionPrefix and incrementing the patch for subsequent releases;
2. packs RodriOliveira.AdrGuard with that version;
3. publishes the package to NuGet.org through Trusted Publishing (OIDC) and to GitHub Packages;
4. publishes the multi-platform OCI image to GHCR and Docker Hub with exact/minor/major/latest tags, OCI metadata, SBOM, and provenance attestations;
5. verifies the published architectures, attestations, exact image digest, and moving major image digest;
6. smoke-tests Action runtime resolution for the exact vMAJOR.MINOR.PATCH and moving vMAJOR references;
7. creates or verifies the immutable exact Action tag and advances the moving major Action tag only after all runtime/package publication jobs succeed;
8. creates the GitHub Release and attaches the .nupkg without overwriting an existing immutable asset.

A failed container publication cannot expose a new Action tag. Reruns preserve immutable SemVer tags and never move a major compatibility tag backwards. See the GitHub Action release policy for the full verification and idempotency rules.

License

Licensed under the MIT License.