fix-lints: wire sweep-remediation.md reference into the Sweeps step

jared commented

2026-08-02 13:52:22 +00:00

Owner

Problem

The fix-lints Sweeps step runs `bin/dup-sweep` (flay) but gives the driver no guidance on what to do with the findings. flay scores by mass, and mass alone doesn't distinguish a missing abstraction (identical boilerplate across 30 files) from healthy repetition (similar-looking tests). Without remedy guidance, drivers either over-extract (wrong abstractions) or just report scores.

Solution — reference file already drafted

`plugins/os-sdlc/skills/fix-lints/references/sweep-remediation.md` already exists in the working tree (drafted by the discovering session, uncommitted). It triages flay findings into four shapes with a preferred remedy each: identical cross-file boilerplate → declarative factory + role module (with a Zeitwerk one-file-per-constant guard); parallel pairs → mixin, maybe; merely-similar/tests → leave alone; thin sibling wrappers → usually fine. Advisory-only, ADR-on-adoption, re-run-and-report-delta rules included.

Proven on caldotcom-api: shape-1 remedy (`Support.define` factory) dropped flay 1267 → 737 and eliminated the whole top tier of findings (recorded there as ADR-0001).

Remaining wiring (this repo's side)

Point the SKILL.md Sweeps step at the new reference (same pattern as the batch/iterative/residual phase references — e.g. "See `references/sweep-remediation.md`").
Review/edit the drafted reference for house style, replace or drop its "ticket #NNN" header convention as appropriate, and commit both files together.
Any cleanup: aidd-lint pass on the new reference if that's the house gate.

Discoverer: /home/jared/dev/ruby-gems/caldotcom-api, session da297b53-3c4a-4db1-b2de-145838042e92, 2026-08-02. Sweeps step reported flay findings with no encoded remedy preferences; the preferred remedies were worked out live and should be captured for every project the plugin lints.

## Problem The fix-lints Sweeps step runs \`bin/dup-sweep\` (flay) but gives the driver no guidance on what to *do* with the findings. flay scores by mass, and mass alone doesn't distinguish a missing abstraction (identical boilerplate across 30 files) from healthy repetition (similar-looking tests). Without remedy guidance, drivers either over-extract (wrong abstractions) or just report scores. ## Solution — reference file already drafted \`plugins/os-sdlc/skills/fix-lints/references/sweep-remediation.md\` **already exists in the working tree** (drafted by the discovering session, uncommitted). It triages flay findings into four shapes with a preferred remedy each: identical cross-file boilerplate → declarative factory + role module (with a Zeitwerk one-file-per-constant guard); parallel pairs → mixin, maybe; merely-similar/tests → leave alone; thin sibling wrappers → usually fine. Advisory-only, ADR-on-adoption, re-run-and-report-delta rules included. Proven on caldotcom-api: shape-1 remedy (\`Support.define\` factory) dropped flay 1267 → 737 and eliminated the whole top tier of findings (recorded there as ADR-0001). ## Remaining wiring (this repo's side) - Point the SKILL.md Sweeps step at the new reference (same pattern as the batch/iterative/residual phase references — e.g. "See \`references/sweep-remediation.md\`"). - Review/edit the drafted reference for house style, replace or drop its "ticket #NNN" header convention as appropriate, and commit both files together. - Any cleanup: aidd-lint pass on the new reference if that's the house gate. -------- **Discoverer:** /home/jared/dev/ruby-gems/caldotcom-api, session da297b53-3c4a-4db1-b2de-145838042e92, 2026-08-02. Sweeps step reported flay findings with no encoded remedy preferences; the preferred remedies were worked out live and should be captured for every project the plugin lints.

jared commented

2026-08-02 14:09:24 +00:00

Author

Owner

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Wire the drafted sweep-remediation reference into the fix-lints Sweeps step and commit it

Current behavior:
The fix-lints Sweeps step runs the flay-based dup-sweep but gives the driver no guidance on acting on findings — flay mass alone doesn't distinguish a missing abstraction from healthy repetition, so drivers over-extract or just report scores. A remediation reference (sweep-remediation.md, in the fix-lints skill's references directory) already exists uncommitted in the working tree, triaging findings into four shapes with a preferred remedy each; its shape-1 remedy was proven on caldotcom-api (flay 1267 → 737, recorded there as ADR-0001).

Desired behavior:
The fix-lints SKILL.md Sweeps step points the driver at the remediation reference, using the same pattern the batch/iterative/residual phases use for their references. The reference itself is edited to house style (drop or adapt its "ticket #NNN" header convention as appropriate), passes the aidd-lint gate, and both files land in one commit.

Key interfaces:

The fix-lints SKILL.md Sweeps step — gains a "See references/sweep-remediation.md" pointer matching the existing phase-reference pattern
The reference's advisory-only stance, ADR-on-adoption rule, and re-run-and-report-delta rule must survive the style edit

Acceptance criteria:

The Sweeps step references the remediation doc the same way other phases reference theirs
The reference passes /os-aidd-lint:check (or the Tier-1 cops at minimum) with no new findings
The four remedy shapes and their preferred remedies are intact after editing
SKILL.md change and reference are committed together, and bin/refresh-plugins is run after

Out of scope:

Changing dup-sweep/flay mechanics or thresholds
Applying remedies to any target project (the reference is guidance only)

> *This was generated by AI during triage.* ## Agent Brief **Category:** enhancement **Summary:** Wire the drafted sweep-remediation reference into the fix-lints Sweeps step and commit it **Current behavior:** The fix-lints Sweeps step runs the flay-based dup-sweep but gives the driver no guidance on acting on findings — flay mass alone doesn't distinguish a missing abstraction from healthy repetition, so drivers over-extract or just report scores. A remediation reference (`sweep-remediation.md`, in the fix-lints skill's references directory) already exists **uncommitted in the working tree**, triaging findings into four shapes with a preferred remedy each; its shape-1 remedy was proven on caldotcom-api (flay 1267 → 737, recorded there as ADR-0001). **Desired behavior:** The fix-lints SKILL.md Sweeps step points the driver at the remediation reference, using the same pattern the batch/iterative/residual phases use for their references. The reference itself is edited to house style (drop or adapt its "ticket #NNN" header convention as appropriate), passes the aidd-lint gate, and both files land in one commit. **Key interfaces:** - The fix-lints SKILL.md Sweeps step — gains a "See `references/sweep-remediation.md`" pointer matching the existing phase-reference pattern - The reference's advisory-only stance, ADR-on-adoption rule, and re-run-and-report-delta rule must survive the style edit **Acceptance criteria:** - [ ] The Sweeps step references the remediation doc the same way other phases reference theirs - [ ] The reference passes `/os-aidd-lint:check` (or the Tier-1 cops at minimum) with no new findings - [ ] The four remedy shapes and their preferred remedies are intact after editing - [ ] SKILL.md change and reference are committed together, and `bin/refresh-plugins` is run after **Out of scope:** - Changing dup-sweep/flay mechanics or thresholds - Applying remedies to any target project (the reference is guidance only)

jared added the

enhancement

ready-for-agent

labels

2026-08-02 14:09:33 +00:00

jared commented

2026-08-02 14:15:32 +00:00

Author

Owner

Work started (implementing per Agent Brief).

jared commented

2026-08-02 14:17:43 +00:00

Author

Owner

Done in e3ee249. Sweeps step in fix-lints SKILL.md now points at references/sweep-remediation.md (same inline-pointer pattern as the other phases). The reference was edited: ticket-provenance line dropped, standing-rules bullets split/tightened, one parenthetical reworded — the four remedy shapes, advisory-only stance, ADR-on-adoption rule, and re-run-delta rule are intact. aidd-lint Tier-1 passes clean on the reference; all remaining SKILL.md findings are pre-existing and untouched. bin/refresh-plugins run.

Done in e3ee249. Sweeps step in fix-lints SKILL.md now points at references/sweep-remediation.md (same inline-pointer pattern as the other phases). The reference was edited: ticket-provenance line dropped, standing-rules bullets split/tightened, one parenthetical reworded — the four remedy shapes, advisory-only stance, ADR-on-adoption rule, and re-run-delta rule are intact. aidd-lint Tier-1 passes clean on the reference; all remaining SKILL.md findings are pre-existing and untouched. bin/refresh-plugins run.

jared added the

review

label

2026-08-02 14:17:44 +00:00

jared commented

2026-08-02 14:30:12 +00:00

Author

Owner

Follow-up in dcaec85: shapes 2–4 are now marked provisional. Instead of applying their written remedies, the driver calls each occurrence out with the real code as a problem/solution example in plain terms, gives a POODR-weighted recommendation, and the user decides. The decision is then recorded in the reference and the provisional marker dropped, so future sessions apply it without a call-out. Shape 1 stays as-is (field-validated on caldotcom-api). Lint clean; plugins refreshed.

Follow-up in dcaec85: shapes 2–4 are now marked provisional. Instead of applying their written remedies, the driver calls each occurrence out with the real code as a problem/solution example in plain terms, gives a POODR-weighted recommendation, and the user decides. The decision is then recorded in the reference and the provisional marker dropped, so future sessions apply it without a call-out. Shape 1 stays as-is (field-validated on caldotcom-api). Lint clean; plugins refreshed.

jared commented

2026-08-02 14:34:52 +00:00

Author

Owner

Correction in 1ca06d8: shapes 2–4's written remedies were speculative (drafted by the discovering session, never discussed) and have been removed entirely so they can't anchor in-the-wild recommendations. Those shapes now carry tells only, marked (unsettled), remedy 'undecided — call it out'. The call-out protocol now reads as open POODR-lens debate → user decision → reference updated with the settled remedy on approval. Lint clean; plugins refreshed.

Correction in 1ca06d8: shapes 2–4's written remedies were speculative (drafted by the discovering session, never discussed) and have been removed entirely so they can't anchor in-the-wild recommendations. Those shapes now carry tells only, marked (unsettled), remedy 'undecided — call it out'. The call-out protocol now reads as open POODR-lens debate → user decision → reference updated with the settled remedy on approval. Lint clean; plugins refreshed.

jared referenced this issue

2026-08-02 14:46:14 +00:00

Add likelihood gate to the no-speculative-hardening rule in its enforcing artifacts #233

jared closed this issue

2026-08-02 14:48:16 +00:00

jared commented

2026-08-02 14:48:17 +00:00

Author

Owner

Closed on user sign-off. Shipped in e3ee249, dcaec85, 1ca06d8: Sweeps step wired to references/sweep-remediation.md; shape 1 remedy field-validated; shapes 2–4 identification-only (unsettled) with the call-out protocol. Follow-up on the likelihood gate for enforcing artifacts tracked in #233.

Closed on user sign-off. Shipped in e3ee249, dcaec85, 1ca06d8: Sweeps step wired to references/sweep-remediation.md; shape 1 remedy field-validated; shapes 2–4 identification-only (unsettled) with the call-out protocol. Follow-up on the likelihood gate for enforcing artifacts tracked in #233.

jared referenced this issue from a commit

2026-08-02 14:49:53 +00:00

Wire sweep-remediation reference into fix-lints Sweeps step (#232)

jared referenced this issue from a commit

2026-08-02 14:49:53 +00:00

Mark sweep shapes 2-4 provisional with a user call-out protocol (#232)

jared referenced this issue from a commit

2026-08-02 14:49:53 +00:00

Strip speculative remedies from sweep shapes 2-4 (#232)

jared referenced this issue from a commit

2026-08-02 14:49:53 +00:00

Record #232 sweep-remediation wiring in os-sdlc status leaf