Audit gates

Audit gates are structural checks that protect substrate invariants — a missing barrel re-export, a tool name no definition emits, an event type with no scrubber allowlist, a published dist/ artifact missing a .d.ts. Most gates are pure source-text scans (.mjs) that run in under a second.

External consumers (plugin authors, sibling SKU authors, hosts embedding @pleach/core) care about a subset: the ones that protect the published surface they consume. This page covers that subset. The full internal gate set — coordinator-process gates, refactoring scaffolds, soak ledgers gating in-flight substrate moves — lives in scripts/audit/ on the source repo. Source there is canonical.

This page is organized by subsystem. To read the same gates by the contract they enforce — which clause of the auditability and replayability promise each one holds up — see CI enforcement of the audit contract.

Run any gate via npm:

npm run audit:<name>

Suffix conventions are stable across gates. :strict is the CI mode (fails on novel drift). :json emits machine-readable output. :list dumps the inventory. :update-baseline regenerates the allowlist after intentional drift.

Package shape (gates every consumer should know)

These run before any first-publish and before any 1.x release tag. They catch silent failure modes invisible to in-monorepo builds — workspace path aliases that resolve cross-tree locally but fail in a real npm install, tsup DTS emission that exits 0 but produces no .d.ts, peer-deps not declared in dependencies.

If you're authoring a sibling @pleach/* SKU OR a third-party plugin that ships its own npm package, these are the gates to mirror in your own CI.

Plugin contract (gates plugin authors should know)

The plugin substrate is a strict contract between @pleach/core/plugins and host code. These gates enforce completeness on both sides — every contributeX hook has a paired collector accessor on PluginManager, every host extension stays out of domain-coupling-suspect deep paths.

If you're writing a HarnessPlugin, mirror these in your plugin's repo.

Tool coverage (gates tool authors should know)

A "reverse-invariant" audit verifies the VALUES (or KEYS) in a runtime lookup table all resolve to canonical tool names. Forward direction (every tool has an intent) is covered by the tool-generation pipeline; these audits close the reverse — every NAMED tool in a map is a REAL tool.

Event log + hash chain

The event log is the canonical record of every session turn. These gates enforce the redaction surface, the hash chain, and the producer/projection contracts.

Config manifest

The config manifest records which substrate ran each session, content-addressed and referenced by every event-log row. These gates protect its hash determinism and its referential integrity against the event log.

Multi-tenant

These gates close tenant_id propagation end-to-end — every tenant-scoped table has RLS, every event-log write stamps the tenant.

Graph + lattice

The compiled agent graph obeys the four-stage lattice (anchor-plan → tool-loop → synthesize → post-turn, one-way, with a messageId-guarded synthesize → synthesize retry). These gates enforce that invariant, the recovery-dispatch surface, and the AuditableCall row shape.

API protection (host-side)

Domain purity + frontmatter

Substrate hygiene at PR time.

Bundled commands

Composite scripts that chain related gates.

Internal coordinator-process gates

The substrate carries additional gates for in-flight refactoring ladders, soak ledgers, slot reservations, and parallel-session coordination. They protect the engineering process, not the shipped surface. External consumers will not run them; mention of them in public docs would be misleading.

If you're operating the substrate (committer access to the upstream repo, authoring a design pack, running a multi-agent refactoring fleet), see scripts/audit/ directly. The script source files carry the canonical purpose + mode documentation per gate.

Calendar-substitution pattern

Worth knowing as a general technique. When a "let it bake for N days" soak window has a deterministic failure mode the script can catch directly, the calendar collapses into a script gate that runs at PR time. Replace ≥30d of zero fires on probe X with last 3 canvas batches at probe X count == 0. The script gate then becomes the permanent regression-detection surface.

The pattern has applied across 8+ internal initiatives. When you see a calendar wall in a design doc, default-search for "what would the script gate look like?" before accepting the wall.

Mirroring gates in your own repo

The upstream gates protect the substrate. Hosts that build on top of @pleach/* often want the same discipline for their load-bearing invariants — a per-tenant key never appears in logs, every domain tool has a matching detector, a feature flag hasn't been left on past its sunset date.

The pattern is the same:

• Write a script that walks the relevant source and asserts the invariant. Exit non-zero with a structured error message that names the offending file and line.
• Wire it into package.json under an audit:<name> script and into the PR-blocking CI job.
• Document the gate alongside its sibling gates in your repo's equivalent of this page — the audit only earns its keep when the next contributor knows it exists.

The audit:plugin-contract-completeness script in the upstream core repo is a small reference shape: it walks the HarnessPlugin interface, asserts every contribute* hook has both a typed schema and a wire-check entry, and fails with the hook name when one is missing. Host-side audits that follow that shape — one invariant per script, structured failure output, documented in source-tree-adjacent prose — compose cleanly with the substrate's existing gate set.

The audit gate is the regression-detection surface; the discipline is that adding a new invariant means adding a new gate, not adding it to a code-review checklist.

Where to go next