Skip to content

Audit remediation: nolint reasons, goast naming, plan status reconciliation, TODO triage #365

Open

Description

@David-Noble-at-work

A mechanical audit on 2026-08-11 produced five findings. Verification against the source invalidated one and narrowed another. This issue tracks the three survivors plus the two corrections.

Plan: docs/plans/audit-remediation.md

Findings

# Finding Verdict
3 Two bare nolint directives Confirmed
4 A backward-compatibility path in the goast production parser Wrong — reduced to a naming defect
1 status: used as a prose dumping ground Confirmed — 59 free-text values
2 Three incompatible status conventions Confirmed — plus 41 docs with no status
5 22 TODO/FIXME markers Narrowed — ~11 real; the rest are product output

Finding 4 was wrong. SchemaElement.Type is the schema's live required classifier (yaml:"type", no omitempty); Production and Consumes are the newer optional refinements. The defaulting code in NewProduction is load-bearing — deleting it breaks every schema element that does not spell both out. The defect is the word "legacy" in two comments and the two test names that inherited it.

Finding 5 was overstated. About half the 22 markers are the goast doc-stub generator's own product output — the TODO(go-style) text it writes into undocumented code — plus its tests. Real debt is ~11 sites. Three are stubs, but all three fail loudly rather than returning success, so none is the critical-bug class.

Rulings

  1. Phase 3 splits per plan subtree, one PR each.
  2. The plan status enum is replaced with seven tokens in lifecycle order: draft | proposed | chartered | in-progress | completed | deferred | abandoned. chartered means approved. settled folds into it; complete becomes completed.
  3. Every one of the ~244 plan documents is reconciled against the code and the merged PRs, with a proposed status reported for each — not just the 41 that lack a status field.

Phases

  1. lint/nolint-reasons — the two suppressions get reasons.
  2. chore/goast-type-field-naming — two comments, two test names; no behavior change.
  3. Plan status reconciliation — 3.0 rewrites TEMPLATE.md to the seven-token enum; 3.1 produces the reconciliation report over all ~244 documents, editing none of them; 3.2..N apply approved statuses per subtree.
  4. chore/todo-triage — every marker fixed, cited to an issue, or deleted.

Metadata

Metadata

Labels

Epic:QualityCoverageCode quality, coverage, and the lint gatesfeatureDeliverable unit within an epic

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions