Architectural intelligence

donmai arch is the built-in architectural drift detector. It fetches a PR's diff, derives architectural observations from the changed files, and applies a configurable gate so CI can block on drift.

The command is native to the donmai binary: no external binary, npm package, or service is required. Earlier releases shelled out to an external af-arch / @donmai/architectural-intelligence binary; that path is now a deprecated, opt-in fallback (see DONMAI_ARCH_BIN below).

How it works

donmai arch assess fetches the PR diff through gh, then runs Layer 1 - diff observation: a pure, dependency-free analysis of the changed files that infers file zones, detects conventions, infers decisions, and infers acceptance criteria. The resulting observations are evaluated against the configured gate policy, which sets the command's exit code.

Layer 1 requires no API key, model, or datastore - only that gh is installed and authenticated for the target repository.

Scope: Layer 1 only

OSS donmai ships the diff-reader and drift gate (Layer 1). Full architectural drift detection against a learned, per-repository baseline - the observation graph and LLM deviation analysis - is a hosted-platform capability and is not part of the OSS distribution.

Usage

# Assess a GitHub PR by URL
donmai arch assess https://github.com/org/repo/pull/123

# Or specify the repository and PR number explicitly
donmai arch assess --repository github.com/org/repo --pr 123

# Block the build on any deviation
donmai arch assess https://github.com/org/repo/pull/123 --gate-policy zero-deviations

# Print a human-readable summary instead of JSON
donmai arch assess https://github.com/org/repo/pull/123 --summary

By default assess prints a JSON report to stdout.

Flags

Flag	Description
`--repository`	Repository identifier, e.g. `github.com/org/repo`.
`--pr`	PR number within the repository.
`--gate-policy`	Gate policy (overrides `DONMAI_DRIFT_GATE`).
`--scope-level`	Scope level: `project`, `org`, `tenant`, or `global`.
`--project-id`	Project ID for the scope.
`--summary`	Emit a human-readable summary instead of JSON.

Gating CI

The exit code reflects the gate policy, so donmai arch assess drops directly into a CI step:

Exit code	Meaning
`0`	Clean - no deviations, or the gate was not triggered.
`1`	Gated - the deviation threshold was exceeded per policy.
`2`	Error - invalid arguments, network failure, or a parse error.

Set the policy with DONMAI_DRIFT_GATE or the --gate-policy flag:

Policy	Behavior
`none`	Never gate.
`no-severity-high`	Block on high-severity deviations. (default)
`zero-deviations`	Block on any deviation.
`max:N`	Block when total deviations exceed `N`.

# Fail the job on any high-severity drift
donmai arch assess "$PR_URL" --gate-policy no-severity-high

Legacy exec-shim

DONMAI_ARCH_BIN is a deprecated escape hatch that execs the external @donmai/architectural-intelligence TypeScript binary instead of the native path. It exists for parity during the transition and is not required - the native diff-reader and gate are the supported path. Leave it unset unless you specifically need the legacy binary.