Auditors

An auditor is the check bound to an exit condition — the thing that proves the condition’s invariant holds. Akka ships a small set of built-in introspective auditors. Beyond those, auditors are authored per ecosystem as inline commands, provisioned as harness assets, or delegated via attestation. There is no large closed catalogue of checks you pick from by id, but there is a built-in set.

Every auditor is one of three kinds — introspective, provisioned, or delegated — set by where the check can run. This page describes the auditor concept; auditor kinds cover each kind in detail.

Built-in and inline auditors

Akka’s built-in auditors are introspective: they inspect the working tree and read a tool’s exit code. maven-compile and maven-test for Java/Akka, git-clean and git-secrets over the git tree, no-build-output and deps-pinned for repository hygiene, content-vale over docs/, ci-green for prior CI runs, file-adr for a recorded decision. A condition binds one by naming its id in the check field.

Where a project introduces an ecosystem the built-ins do not cover, it authors an inline introspective auditor: a command plus the surface it applies to, written under the condition’s auditor field.

auditor:
  run: ["npm", "run", "-s", "typecheck"]   # the command that decides the invariant
  applies_to:
    requirement: node                       # environment it needs (node, maven, git, …)
    module: web                             # the sub-project it runs in (relative to the root)

It is green when the command exits zero, red otherwise. The point is delegation: the auditor does not encode knowledge of React or Akka — it runs the ecosystem’s own type-checker, test runner, or linter where the surface lives. In practice, "no invented APIs" reduces to "it type-checks in every language present": tsc --noEmit fails on an invented React hook, mvn compile fails on an invented Akka method. New auditor work is needed per ecosystem, not per dependency.

Provenance and trust

Where an auditor comes from sets how far it is trusted:

Provenance Trust

Akka-provided / organization-declared (in policy.yaml)

Trusted; runs without a separate approval.

Project- or assistant-authored

Runs only after you approve its exact command (the first-run execution gate), and is reviewed adversarially for adequacy.

New or changed checks are surfaced to you at the exit-condition level — "I’d like to add these exit conditions, and here is how I’ll check each" — for you to approve, adjust, or skip. It is never phrased as a low-level "approve running a command"; approving the exit condition is the single decision that covers both its design and running its command.

The two locked gates

Two Process-integrity conditions are always on and cannot be struck. They make the verification apparatus police itself:

  • PROC-AUDITOR-COVERAGE — every material build surface has a covering auditor, else red. See The coverage gate.

  • PROC-ADEQUACY-REVIEWED — a fresh adversarial review, keyed to the current checks, covers every auditor. See The adequacy review.

Waiving a surface

A detected surface that genuinely needs no check (a demos or scripts folder) can be marked intentionally unaudited, with a recorded reason; the coverage gate then skips it. This is the escape hatch for the "every surface is material" rule.

Related