/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`+; v4 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 / Status / Issue / Suggested Fix / Principle; a v3 or earlier table has no Status).

**Validate the report before consuming it.** This skill acts on a contracted input, so check the contract. The checker ships inside this plugin (`<plugin root>/scripts/check_report_format.py`; `scripts/check_report_format.py` inside the plumb-line repo):

python3 <plugin root>/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 — State-first lineage), 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. Then, before anything changes the tree under remediation, write the plan table (Finding / Path / Class / Intended action) to a file with a tool call of its own, and wait for it to complete: no edit may be in the same call or the same step as the plan write. A change to the tree is an edit, a write, a shell command that modifies a file in it, or a git command that writes inside it, such as `git init` or `git stash`; reading files, or copying them out to a snapshot elsewhere, is not. Put the plan file outside the code under remediation, for example `plumb-line-plan.md` in a temp directory, and show the table to the builder too, before the first edit. Name each principle inline in the plan (`P2 — One-way layering`), as in the record.

Repeat the same plan table in your final message, below the record, headed "Fix plan", and give the plan file's path. Make no claim about when the plan was printed or written: the order of your tool calls shows it, and a claim cannot. The repeat is checked with the record (see "The message is the text the checker passed", below).

Why: the plan is what lets a builder stop an edit before it happens, so it has to exist before the first edit, where anyone can see it did. Four remediators under the release harness's pressure protocol, told to print the plan first, edited first; three of them then said in their final message that the plan had come before the first edit, which their transcripts do not show (#589). A plan file written by a tool call, completed before the first edit, is on the record; a sentence about timing is not.

**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: the lowest value in the project's own confidence representation (in a plumb-line envelope the `"none"` rung, plus `confidenceScore` `0` where scores are used; where the project's confidence field is a number, `0`), a mock-labelled source (`source: "mock"` in an envelope), and `derivedFromMock: true`. Match the field's existing type; never write a rung string into a numeric field. An unverifiable origin is labelled as what it is, not what it is hoped to be. Never pick a "reasonable middle" (0.