/plumb-line-audit

name: plumb-line-audit
description: Use when auditing a diff or repository against the plumb-line principles — finds laundered uncertainty, boundary leaks, hardcoded priors, overstated maturity, outputs lacking recorded lineage, and baseline drift with no explanation. Read-only: it reports, never auto-fixes.

Audit against the plumb-line principles

REQUIRED READING FIRST: `reference/portable-principles.md` (plugin root). If this file cannot be read, stop immediately and report: "Cannot audit: `reference/portable-principles.md` is missing or unreadable. Do not proceed from memory — the principles file is the source of truth for this audit."

Scope the audit to the diff if one is given, else the whole repo. For broad sweeps, dispatch read-only subagents and keep only their findings.

**Declared architecture first (stop before auditing blind).** Several checks (P1 source-truth, P2 layering, the omission pass's adoption calibration) are only as good as the audit's knowledge of what the project *declares*. Resolve it, in order: (1) supplied in the invocation/prompt by the builder; (2) the project's ruleset file (`AGENTS.md`, `CLAUDE.md`, or equivalent) and boundary config. If neither yields a source-truth layer and layer direction:

• **Builder present** — stop before the traversal plan and say what is missing.

Offer to invoke `plumb-line-bootstrap` in its **declaration-only entry** (a two-minute detour: it asks only the three declaration questions, writes the ruleset so the next audit never hits this stop, installs nothing, and returns the baton); on yes, invoke it naming that entry, then resume the audit using the freshly declared architecture. On no, proceed as below.

• **Builder absent, or declined** — proceed, calibrated to adopted principles

only (see "Calibrate to adopted principles"), and record the gap in the report: an undeclared architecture is itself a P6-adjacent advisory (the project's rules exist only as vibes), and the audit's P1/P2 coverage is correspondingly `partial`, which the coverage map must say.

Never infer a source-truth layer the project did not declare — an invented layer would make P1/P2 findings artifacts of the audit's own assumptions.

**Coverage honesty (emit a traversal plan first).** Before reading, list the in-scope files — the diff's touched files, or the repo's source tree — and state which you will read, sample, or skip. That list is the audit's **denominator**. Track `read` / `partial` / `not-read` as you go and report it in the coverage map (Report §4). On anything larger than a small diff you will NOT read every file; say so up front rather than at the end. Never state or imply full coverage unless every in-scope file is marked `read` — an unread file with no finding is *not* a clean file, and claiming otherwise is the laundered-uncertainty / overstated- maturity failure this audit exists to catch (P8 — State-first lineage, and the honest-denominator discipline), turned on the audit itself.

Check catalogue (each finding cites the principle it violates)

1. Laundered uncertainty (P3) — a value that lost its confidence/provenance as it flowed downstream; a mock/approximate value treated as clean truth.

• If the project uses the plumb-line provenance primitive: flag code that hand-builds provenance metadata bypassing combineProvenance/derive, and any value given a clean source while derived from a tainted input. Runtime complement: auditMeta().

2. Boundary leak (P2) — an import or call crossing layers against the declared direction; symbolic/derived/mock logic inside the source-truth layer (P1). 3. Hardcoded prior (P5) — a magic number encoding a judgment call, not injected/versioned config. 4. Overstated maturity (P6) — code or docs claiming current/done for something partial/mock/planned. 5. Missing lineage (P8) — an output stored without the inputs needed to reproduce it.

• If the project uses the provenance primitive: flag derived values that are never marked or carry no lineage; recommend asserting auditMeta(metaOf(value)) === [] in tests.

6. Unexplained drift (P9) — a changed golden-baseline value with no recorded reason. 7. Suppressed null result (spine) — a code path that cannot express "no structure/no effect/inconclusive". Confirmed only where rejection is a declared or practiced concern; where rejection is adopted nowhere, an always-accept/always-success stub is an advisory adoption gap, not a violation (see "Calibrate to adopted principles" below). 8. Escaped fakery (P4) — mock/approximate/fallback/cached data that left its container: not labelled (e.g. missing a derivedFromMock-style marker), or flowing into an export/output path that should exclude it unless explicitly opted in. 9. Uncontracted output (P7) — a public output shape with no versioned, validated contract: missing a validator, a version constant, or a canonical key list.

Method

Run two passes — they catch different failure modes, and some checks need both.

**Presence pass — things wrongly present.** A bad thing IS in the code: an upward import (P2), a magic number (P5), an escaped/unlabelled mock (P4), a mock value treated as clean truth (P3), overstated maturity (P6), a changed baseline value (P9 drift). Grep/read for the smell, then confirm by reading context — never report on a keyword match alone.

**Omission pass — things wrongly absent.** A good thing is MISSING, and an absence has no smell to grep. Enumerate instead — and put the enumeration in your report as a table, one row per output-producing function / public output shape. Give each question below its OWN column — do not collapse them. This table is a REQUIRED artifact: the dropped field is invisible unless you walk every output, and skipping the table is how the omission gets missed. For each output ask —

• does it carry **provenance** (where the value came from) where it influences a decision? (P3)
• does it carry **confidence** where it influences a decision? (P3)
• do