/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 layer, P2 — One-way 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 an advisory under P6 — Maturity vocabulary (the project's rules exist only as vibes), and the audit's coverage of P1 — Source-truth layer and P2 — One-way layering is correspondingly `partial`, which the coverage map must say.

Never infer a source-truth layer the project did not declare — an invented layer would turn findings under P1 — Source-truth layer and P2 — One-way layering into 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. Test files are in scope: a test that states a requirement is read against the product code it exercises (check 10). 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 — Confidence + provenance) — 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 — One-way layering) — an import or call crossing layers against the declared direction; symbolic/derived/mock logic inside the source-truth layer (P1 — Source-truth layer). 3. Hardcoded prior (P5 — Injectable priors) — a magic number encoding a judgment call, not injected/versioned config. 4. Overstated maturity (P6 — Maturity vocabulary) — code or docs claiming current/done for something partial/mock/planned. 5. Missing lineage (P8 — State-first lineage) — 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 a test asserting auditMeta(metaOf(value)) is empty (`.toEqual([])` or length 0 in JS; `== []` in Python).

6. Unexplained drift (P9 — Golden baseline + explain-the-drift) — 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 — Quarantined fakery) — 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 — Contracted outputs) — a public output shape with no versioned, validated contract: missing a validator, a version constant, or a canonical key list. 10. Test changed to pass (spine; P4 — Quarantined fakery for a substitution) — a test changed so that an unmet requirement reads as met: the unavailable dependency substituted in the requirement's own test (a mock, a stubbed global such as `fetch`, a local fake server, an injected fixture client) so it passes against a stand-in; the test skipped, deleted, commented out, or marked as an expected failure without `strict`; its assertion rewritten to expect what the code now returns; its threshold or gate loosened; or retries and longer timeouts added to hide a failur