/plumb-line-remediate

name: plumb-line-remediate
description: Use when applying findings from a plumb-line audit report — the builder has a report (or pasted findings) and wants the fixes made. Opt-in and separate from the audit, which is read-only and never fixes.

Remediate plumb-line audit findings

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

The audit finds; this skill fixes. The two never blur: remediation runs only on an explicit invitation, consumes a report the audit produced (any `report-format: v1`+; v3 is current), and applies nothing the builder has not seen. If there is no report, offer to run `plumb-line-audit` first, or accept findings pasted in the findings-table shape (Path / Line / Function / Issue / Suggested Fix / Principle).

**Validate the report before consuming it.** This skill acts on a contracted input, so check the contract when `scripts/check_report_format.py` is reachable:

python3 scripts/check_report_format.py <the report>

A violation is **not** a reason to refuse the run — it is a reason to say what is wrong before acting on it. Report the violations, then ask whether to proceed; the risk a malformed report carries is that a column means something other than you assume, and the builder is the one who can tell. If the checker is unavailable, say the input was not mechanically validated rather than staying silent — the same honesty the audit owes its own output.

The contract (what a remediation run IS)

A remediation run produces, in order:

1. a **fix plan** — every finding classified before any edit, 2. **per-finding diffs** — each shown before it is considered done, 3. a **remediation record** — the finding→change table that gives the remediation itself the lineage it demands of the code (P8), 4. a **verification step** — the project's own enforcement, run, with output.

Editing a file the builder never sees a diff for, or finishing without the record, is a failed run — regardless of whether the fixes were correct.

Step 1 — Classify every finding before touching anything

Read the whole findings table first and classify each row. Print the plan as a table (Finding / Path / Class / Intended action) before the first edit.

**Mechanical** — the principle determines the fix; no epistemic value must be invented. Typical: remove an upward import (P2 — One-way layering); replace a hardcoded constant with the already-existing injected config (P5 — Injectable priors); add a version constant + validator to an uncontracted output (P7 — Contracted outputs); record lineage fields that are computable from inputs in scope (P8 — State-first lineage); relabel maturity to what the code already is (P6 — Maturity vocabulary); wrap an untagged return in `mark`/`derive` where the source is unambiguous (P3 — Confidence + provenance).

**Judgment** — the fix requires a claim only the builder can stand behind: which confidence a value deserves, whether a stub should stay or become a real integration, which layer a relocated piece of code belongs to, what a changed baseline's explanation is (P9 — Golden baseline + explain-the-drift). For each judgment finding, propose a concrete default and ask; apply only on a yes. When the builder is not present to answer, apply the **conservative default** (below), mark it `applied-conservative` in the record, and say it needs their review.

**The conservative default: claim nothing the code cannot support.** Where an epistemic value must be supplied and nobody has answered, take the weakest honest claim — a fabricated or stubbed value gets the floor (`confidence: 0` / lowest rung, `source: mock`, `derivedFromMock: true`); an unverifiable origin is labelled as what it is, not what it is hoped to be. Never pick a "reasonable middle" (0.5-ish) for a value that is actually fake: an invented moderate confidence is an invented fact. Two runs on the same input must produce the same claim — the floor is deterministic; optimism is not.

Step 2 — Apply one finding at a time, diff shown per finding

Work finding by finding, smallest first if order is free. For each: make the edit, then show the diff (before/after or unified) labelled with the finding it resolves, in the conversation, as you go — not a bulk dump at the end. The builder must be able to stop a bad direction after finding 1, not discover it after finding N.

**Scope discipline.** Touch only what the finding requires. Adjacent improvements you notice — a stale comment, a string that could be richer, a refactor begging to happen — go in the record's **Proposed (not applied)** section, never into the working tree. One exception, because honesty beats minimality: if your edit makes an existing statement in the same file false (a comment or docstring naming a constant you just deleted, a doc line describing behavior you just changed), correct that statement as part of the finding's diff — a remediation must not manufacture a lie by omission. Note the correction in the record.

If a fix for one finding would conflict with the fix for another, stop and surface the conflict rather than picking silently.

Step 3 — The honesty guardrail (what a fix may never do)

A remediation may never resolve a finding — or satisfy a gate, a test, a deadline, or a re-audit — by making the code *less* honest. Concretely, never:

• clear or hand-set a taint flag (`derivedFromMock` and kin) on data that is

still mock-derived;

• raise a confidence, or swap a source label for a cleaner one, so a check

passes;

• delete or bypass a null-result / rejection branch so an output always

succeeds;

• drop a provenance, confidence, or lineage field because its honest value

is embarrassing;

• update a golden baseline without a recorded explanatio