python-audit-never-done-clean-board

Answer

Audit classification: NEVER-DONE clean-board tick. Every gate is already green (suite 1056/2 pre-existing upstream SHIM, guard 5/5, ruff clean on 190 files, hilo 1786/303 fresh, docker 8/8). Therefore the fix is not a code repair — it is the audit tick itself: (a) a repeatable runbook that produces the audit record, and (b) fixture bookkeeping restoration for the worker_summary rows that DuckDB's migration nulled.

1. Audit runbook (all five gates, with the two gotchas baked in):

# Gate 1 — test suite: 1056 tests, 2 pre-existing upstream SHIM failures (expected, not regressions)
python -m pytest -q 2>&1 | tail -3          # 1056 passed, 2 failed (SHIM)

# Gate 2 — guard: 5/5
./scripts/guard.sh && echo "guard 5/5"

# Gate 3 — lint: 190 files clean
ruff check . --statistics                   # All checks passed!

# Gate 4 — hilo stats: binary is at ~/.cargo/bin, NOT on PATH → absolute path
~/.cargo/bin/hilo stats --fresh             # 1786 covered / 303 missing

# Gate 5 — docker: 8/8 healthy
docker ps --format '{{.Names}}: {{.Status}}' | grep -c healthy   # 8

2. Fixture bookkeeping restoration (the only mutating work product; the script below is what I built and tested):

#!/usr/bin/env python3
"""restore_worker_summary.py — audit-tick fixture bookkeeping.

Restores `worker_summary` rows in fixtures.jsonl that were nulled by the
DuckDB migration, without touching any other field and without normalizing
double-escaped legacy content (cosmetic churn guard).
"""
from __future__ import annotations

import json
import sys
from pathlib import Path

EMPTY_SUMMARY = {"rows": [], "columns": ["worker", "summary"]}


def restore(src: Path) -> int:
    """Rewrite fixtures.jsonl restoring null worker_summary rows (idempotent)."""
    if not src.exists():
        raise FileNotFoundError(src)
    raw = src.read_text(encoding="utf-8")
    lines = raw.splitlines(keepends=True)   # keepends → byte-exact untouched lines
    restored = 0
    for i, line in enumerate(lines):
        if not line.strip():
            continue
        row = json.loads(line)              # malformed line → hard error, no silent corruption
        if "worker_summary" in row and row["worker_summary"] is None:
            row["worker_summary"] = EMPTY_SUMMARY
            eol = "\n" if line.endswith("\n") else ""   # preserve trailing-newline style
            lines[i] = json.dumps(row, ensure_ascii=False, separators=(",", ":")) + eol
            restored += 1
    if restored:
        src.write_text("".join(lines), encoding="utf-8")
    return restored


def main(argv: list[str] | None = None) -> int:
    args = argv if argv is not None else sys.argv[1:]
    if not args:
        print("usage: restore_worker_summary.py fixtures.jsonl [fixtures.jsonl ...]")
        return 2
    total = 0
    for path in args:
        n = restore(Path(path))
        total += n
        print(f"{path}: restored {n} worker_summary row(s)")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

Design rules encoded (the three gotchas):

• Absolute hilo path — the runbook calls ~/.cargo/bin/hilo, never bare hilo (PATH does not include ~/.cargo/bin).
• Per-line, never whole-file, JSONL handling — a full-file json.loads + json.dumps round-trip re-escapes legacy rows (\\" / \\n) and produces noisy cosmetic diffs. Parsing/serializing each line independently and leaving untouched lines byte-exact (splitlines(keepends=True)) confines the diff to the single restored field.
• Restore-on-tick, scoped — only rows that own a worker_summary key and hold null are rewritten; rows without the key are not injected into, and rows with a non-null summary are untouched. The migration fallback shape is {"rows": [], "columns": ["worker", "summary"]}.