/slop-score — make "less slop" provable, then prove it moved

An instance of the generic scorecard doctrine (read that for the five laws and the RSI loop). It is the slop sibling of quality-score (classic defects: gofmt, vet, untested packages) and appeal-score (prose voice). Where quality-score grades the slop the compiler and go vet already catch, this grades the slop they can't see: code that builds, vets clean, and has a test present, yet rots the kernel from the inside — copy-paste clones, tests that assert nothing, dead unexported symbols, commented-out cruft.

The shape: run the scorecard → read the slop-debt work-list → retire debt worst-first (genuine fixes only) → re-measure and prove the drop → regenerate the snapshot → DOS-witness the commit → commit ONLY your lane by explicit path.

The headline metric is slop-debt (corpus.slop_debt): the count of concrete, re-derivable HARD defects across the slop axes, re-derived from disk every pass so it can't drift or be talked past. Drive it toward zero and "less slop" becomes a number you moved, not a claim you made. The epic that tracks the program is #775; Track A (drive the debt down) is what this skill runs.

---

The measure (six axes — four HARD, two SOFT; deterministic, same tree → same score)

tools/code_slop_scorecard.py folds these into a slop_score (0–100, A–F) and the slop_debt integer. HARD axes emit slop-debt (they gate ok); SOFT axes score but never gate. ok is False iff any HARD defect exists.

KPI	HARD/SOFT	one unit of slop-debt is…	the genuine fix
duplication	HARD	a normalized Go token-window copy-pasted into 2+ distinct sites	extract ONE shared helper both sites call (behavior-preserving) — #776
dead_code	HARD	an unexported symbol defined but referenced nowhere else	delete it, or wire it if it has a real intended caller (e.g. cmdTraj into main.go) — #777
vacuous_tests	HARD	a Test* func body that makes zero assertions	add a real assertion that can actually FAIL on a regression — #778
comment_slop	HARD	a tautological doc comment (// X does X) or a commented-out code block	delete the cruft (NOT an honest // TODO/[STUB] marker — see anti-gaming)
stub_masquerade	SOFT	an exported func whose body is only return nil / panic("unimplemented")	advisory only — the honest [STUB] ledger is a feature; promotion to HARD is #781 (gated on a multi-release zero-FP soak), not this pass
churn_bloat	SOFT	recent commits that ADD .go files without ever removing any (HEAD-relative)	advisory trend over --range, not a tree defect; never gate it, never "fix" it by deleting files

Benchmark* and Fuzz* funcs are not graded by vacuous_tests (a benchmark's job is to time, not assert) — so never demote a Test to a Benchmark to dodge the axis.

---

Step 1 — Run the scorecard (it builds your work-list)

From the repo root:

python tools/code_slop_scorecard.py            # human scorecard (per-KPI + work-list)
python tools/code_slop_scorecard.py --json     # machine payload (the loop reads this)

It exits non-zero whenever slop-debt > 0 (this is the gate the epic wires fully at zero, #779). Read corpus.score, corpus.slop_debt, and corpus.breakdown (per-KPI debt, worst first). The per-KPI defects arrays ARE the work-list: each entry names the exact files+lines of a clone group, a dead symbol, or a vacuous test.

The scorecard walks the working tree (rglob("*.go"), not git ls-files) so an uncommitted change scores — re-measure reflects what's on disk right now. The committed snapshot docs/CODE-SLOP-SCORECARD.md can read LOWER than a live run when HEAD has grown since the snapshot was last regenerated; the live number is the truth, and Step 4 re-stamps the snapshot to match. Skip the Go toolchain probe (faster, static-only): --no-toolchain. Tune the SOFT churn window: --range HEAD~40..HEAD.

Record the baseline. Before touching anything, write down slop_debt = N, score = S, and the heaviest KPI. The whole point is to prove the delta, so you need the before-number.

Step 2 — Retire slop-debt worst-first, using GENUINE fixes only

Attack the heaviest KPI first (corpus.breakdown[0]), but only via fixes that are safe on a shared trunk and genuine (they improve the code, not just the number):

• duplication (usually heaviest). For a named clone group, extract the shared body into ONE helper (a package-level func, or a small internal package if the sites span packages) and have every site call it. Keep behavior byte-identical. Most clones live in the cmd/*bench and demo mains (flag wiring, readHFConfig, writeFile, output blocks) — those are the high-count groups. Do ONE group per pass and validate hard (Step 3); a half-done extraction that changes behavior is worse than the clone.
• dead_code. A dead unexported symbol is either (a) genuinely orphaned → delete it, or (b) something that was meant to be wired and never was (e.g. a cmdTraj subcommand missing from its main.go dispatch) → wire it to its real caller. Decide per symbol by reading it; don't blanket-delete something a peer is mid-wiring (check git log/blame).
• vacuous_tests. Add a real, table-driven assertion to the named test — one that can FAIL if the function under test regresses. A fabricated assert true is worse than no assertion and is exactly the gaming the measure exists to refuse.
• comment_slop. Delete a // Foo does Foo-style tautology or a block of commented-out code. Never delete an honest // TODO/[STUB] marker — this repo keeps a [STUB] ledger where that marker is a deliberate honesty feature.

Never edit the frozen ABI (internal/abi), add a dependency, or touch the detector to move a number. Hardening the detector (AST clone detection #780, the SOFT→HARD promotions #781) is deliberate Track-B work with its own issues — it is NOT a way to drop debt.

Step 3 — Validate every change (the honesty gate)

Native go test is OS-blocked on the Windows dev box, so validate under WSL:

go build ./...                                   # compiles (catches structural breaks)
go vet ./...                                     # typechecks incl. _test.go files
wsl -e bash -lc 'cd /mnt/c/work/fak && go test ./<changed-pkg>/... -count=1'

A de-dup extraction or a new assertion you have NOT run is not done — it might not even compile. Run it; if it fails or won't build, fix or revert it. Re-run gofmt -l <files> so your edits stay format-clean (the quality-score format KPI catches them otherwise).

Step 4 — Re-measure, PROVE the drop, regenerate the snapshot

The slop scorecard has no --compare flag — prove the drop by re-running and reading slop_debt against your recorded baseline:

python tools/code_slop_scorecard.py --json      # confirm corpus.slop_debt fell N → M

State the delta plainly: slop-debt N → M (−k), score S → S'. Then regenerate the committed snapshot so the doc matches the tree, and confirm freshness:

python tools/code_slop_scorecard.py --markdown --stamp YYYY-MM-DD > docs/CODE-SLOP-SCORECARD.md
python tools/code_slop_scorecard.py --check-doc                  # must exit 0 now

(Use the Bash tool's > — it preserves UTF-8. A PowerShell > re-encodes to UTF-16 and mangles the ·/— glyphs.) If you lowered the debt, re-pin the control-pane floor so the gain ratchets and a future regression back up is caught:

python tools/scorecard_control_pane.py --pin     # rewrites tools/scorecard_baseline.json

Commit tools/scorecard_baseline.json in the same lane (the control pane reads slop via corpus.slop_debt).

Step 5 — Ground the ship in DOS, then commit ONLY your lane

fak sync reconcile --apply
fak commit --path <your explicit paths> -F <msgfile>
dos commit-audit HEAD                             # MUST print [diff-witnessed] / verdict OK
fak sync push

• Subject honesty. A de-dup extraction → refactor(<scope>): extract … (#776). A deletion of dead code → refactor(<scope>): drop dead … (#777). New assertions → test(<scope>): assert … (#778). Lead with a recognized verb (the commit-message witness ABSTAINs on a noun-led subject). End every ship commit with a (fak <leaf>) trailer so the dos verify referee binds it. Cite the Track-A child issue you closed (or #775 for an epic-level increment).
• dos commit-audit HEAD is the gate. subject-only / CLAIM_UNWITNESSED means your diff doesn't back your subject — reword to what the diff actually did. [diff-witnessed] is the green light.
• Shared-trunk discipline. Stay on main (the OFF_TRUNK guard refuses a branch). Stage and commit by explicit path via fak commit --path — NEVER git add -A. If a peer's MERGE_HEAD is set (cannot do a partial commit during a merge), wait for it to clear, then re-try the pathspec commit. Never force-push.

---

The RSI loop (why this is a self-improvement skill, not a one-shot)

Each pass: measure → retire the heaviest genuine debt → prove the drop → regenerate + re-pin → commit witnessed. Run it again and the new heaviest KPI surfaces — the loop walks slop-debt down monotonically because the number is re-derived from the working tree every time. The discipline that makes it RSI and not vibes: every pass moves a number grounded in evidence the agent did not author — the scorecard's re-derivation from disk, a go test red→green under WSL, and dos commit-audit on the commit.

The full gate (the bare run + --check-doc wired into make demo-scorecards so a regression turns CI RED) lands once slop-debt hits 0 — that is #779, blocked until Track A drains the duplication/dead_code/vacuous_tests debt this skill retires.

Anti-gaming laws (the measure is only as honest as the pass)

1. Never write a vacuous test to pass vacuous_tests, and never demote a Test to a Benchmark/Fuzz to dodge it. An assertion must be able to FAIL on a real regression.
2. Never "de-dup" by deleting a copy that's actually needed at both sites. Extract a shared helper both call; validate build/vet/test. Deleting working code to drop a clone count is a regression wearing a green number.
3. Never delete an honest // TODO / [STUB] marker to move comment_slop or stub_masquerade — those are deliberate honesty features (the latter is SOFT for this exact reason).
4. Never touch the detector or the baseline to drop debt. Detector hardening (#780, #781) is deliberate Track-B work with its own gates, not a debt-dodge. Lower the floor (--pin) only AFTER a genuine drop you proved.
5. Never add a dependency or edit the frozen ABI to move a number.
6. Re-measure with the FULL scorecard (not --no-toolchain) before claiming a drop, and dos commit-audit your commit before claiming it shipped.

When to run this

• To baseline code slop (first run records slop_debt + score).
• To drive slop-debt toward 0 worst-first (the #775 Track-A program), one KPI per pass.
• After a burst of new cmd/* benches/demos (they land with copy-pasted flag-wiring and output blocks → duplication spikes; this pass retires it genuinely).
• On a /loop cadence to keep the kernel from re-accreting slop between releases.

The scorecard is read-only; this skill's only writes are your genuine fixes, docs/CODE-SLOP-SCORECARD.md, tools/scorecard_baseline.json, and the tool itself. It never edits the frozen ABI, never games a SOFT axis, and never weakens the detector to score.