Architecture-aware review

A good reviewer knows your architecture: which layers may depend on which, and which dependencies are forbidden. Architecture-aware review gives the model that same map. If your repo ships an architecture.json, CommitBrief reads it and feeds a compact summary of your declared layers and their allowed / forbidden import edges into the review prompt — so the reviewer can flag a diff that crosses a boundary your architecture forbids. New in v1.11.0 (ADR-0030).

Where the map comes from

architecture.json is the public config of the sibling tool archlint, which deterministically lints import-boundary rules. CommitBrief reuses that same file:

{
  "layers": { "domain": ["internal/domain"], "db": ["internal/db"] },
  "rules":  { "domain": [], "db": ["domain"] }
}

• layers maps a layer name to the path prefixes that belong to it.
• rules lists, per layer, the layers it is allowed to import. [] means it may import no other layer. In the example above, db may import domain, but domain may import nothing — so a new domain → db import is a boundary violation.

CommitBrief folds a summary of this into the prompt as a distinct <architecture_constraints> block. The reviewer can then call out a diff that, say, adds a domain → db dependency the architecture forbids.

It reads — it does not enforce

This is a strict one-way read of archlint’s config. CommitBrief never lints the import graph and never enforces anything itself — it only grounds the LLM so it can reason about the change. For the deterministic gate, run archlint check in CI; architecture-aware review is the soft, prose-level complement that catches a boundary slip in the same pass as the rest of the review.

A missing or malformed architecture.json is a transparent no-op — it never breaks a review.

Cache behavior

Because the architecture summary folds into the system prompt, editing architecture.json automatically invalidates stale cached reviews — the next run reflects the new constraints. A repo without the file produces a byte-identical cache key to before, so adding this feature caused no mass cache invalidation.

Turning it off and pointing it elsewhere

On by default. Skip it for one run, or disable it persistently:

# Per-run: review without the architecture block.
commitbrief --staged --no-architecture

# Per-config.
review:
  architecture: true              # default true; --no-architecture is the per-run equivalent
  architecture_file: ""           # override the discovery path; empty = auto-discover architecture.json at the repo root

commitbrief config set review.architecture false

Point it at a non-default location with review.architecture_file (relative to the repo root, or absolute).

Architecture-aware review applies to a normal review and to dry-run; remote pr is unchanged.

See also

• Review rules — COMMITBRIEF.md, the prose rules that steer the review alongside the architecture map.
• Configuration — review.architecture and review.architecture_file in the config reference.
• Safety and cost — how the prompt feeds the cache key.