docs: plan for remediating the 2026-08-11 audit findings - #366

A mechanical audit produced five findings. Verification against the source
invalidated one and narrowed another; this plan carries the three survivors
along with both corrections, in four phases.

Finding 4 was wrong. The claim was that NewProduction carries a
backward-compatibility path that the greenfield principle makes a critical bug.
SchemaElement.Type is the schema's live required classifier (yaml:"type", no
omitempty); Production and Consumes are the newer optional refinements. The
defaulting code is load-bearing — deleting it breaks every schema element that
does not spell both out. The real defect is the word "legacy" in two comments
and the two test names that inherited it, which phase 2 corrects.

Finding 5 was overstated. About half the 22 TODO markers are the goast doc-stub
generator's own product output and the tests asserting it. Real debt is ~11
sites; three are stubs, but all three fail loudly rather than returning success,
so none is the critical-bug class from the CLAUDE.md checklist.

Confirmed and carried: two bare nolint directives, and plan status split across
four conventions (186 YAML frontmatter, 16 bold, 1 table, 41 absent) with 59
free-text values occupying a machine-readable field.

Three rulings are recorded. Phase 3 splits per plan subtree. The status enum is
replaced with draft, proposed, chartered, in-progress, completed, deferred, and
abandoned, where chartered means approved. Every one of the ~244 plan documents
is reconciled against the code and the merged PRs, with a proposed status
reported for each, before any status is applied.

Documentation only; no code changes.
Issue: #365

Finding 3 was undercounted by an order of magnitude. The tree carries 315
nolint directives, of which 18 are bare — no reason after the linter list. The
original count of 2 came from a grep truncated at head -20 whose cap was then
read as the total.

The 18 split evenly. Nine are errcheck discards on terminal writes and flag
registration (cmd/lore/lore/commands.go, internal/pwsh/pwsh.go, and six sites
in internal/console/console.go). Nine are gocognit/gocyclo suppressions on
functions that .golangci.yaml does not exclude, against thresholds of gocyclo
15 and gocognit 20.

That second class implicates plan #312 (complexity-refactors.md, status
complete), which decomposed 61 functions across seven PRs and states it covered
every function in the repository exceeding the configured complexity limits —
"the repository's only remaining lint debt". Nine functions sat out that
campaign behind suppressions, so the claim does not hold as written. The plan
records #312's status as a known candidate for revision in phase 3.1.

Ruling 4 is added: the nine complexity suppressions are decomposed under the
#312 discipline and deleted, not annotated. Phase 1 accordingly becomes stage
1a (nine errcheck reasons, one branch) and stage 1b (nine decompositions across
four branches).

Four other complexity suppressions in the tree are argued and correctly placed;
they are out of scope and recorded as such.

Documentation only; no code changes.
Issue: #365