12 KiB

Raw Blame History

Brooks-Lint — Full Sweep Guide

Sequential autonomous pipeline: review → test → debt → audit. Fixes findings in place, iterates until clean or capped, reports residuals. One interaction point: Step 0 (pre-flight consent) — after approval the pipeline runs hands-free until Step 8.

Every finding follows the Iron Law: Symptom → Source → Consequence → Remedy.

Goal: State scope, cost, and irreversibility up front; get explicit consent once so later steps never have to ask.

0a. Estimate the file count using git ls-files | wc -l if in a git repo, or find . -type f -not -path '*/.git/*' -not -path '*/node_modules/*' -not -path '*/.venv/*' -not -path '*/build/*' -not -path '*/dist/*' -not -path '*/vendor/*' -not -path '*/target/*' | wc -l otherwise. Order-of-magnitude is enough.

0b. Show this notice verbatim with the estimate filled in. Do not paraphrase — the user is agreeing to this exact scope.

⚠️  /brooks-sweep — Full Repository Sweep & Auto-Fix

Scope:    Four analysis dimensions run in sequence — PR code decay (R1–R6),
          test quality (T1–T6), tech debt, architecture. Edits are made in
          place inside the detected project scope.
Estimated files in scope: ~N

Order:    brooks-review → brooks-test → brooks-debt → brooks-audit.
          Each dimension scans, queues, and fixes before the next starts.

Autonomy: Fully autonomous. Safe single-file fixes apply directly. Multi-file
          fixes that have test coverage AND do not break a public interface
          also apply directly. High-risk fixes (public API break, cross-module
          structural change, or no test coverage) are NOT applied — they are
          recorded in the residual report for human review.

Iteration: After each dimension pass, modified files + same-module + static
          consumers are re-scanned. A finding that fails to fix 3 times is
          retired to the unresolvable set and never re-queued. Non-critical
          rounds cap at 3 iterations; critical findings iterate until
          resolved or retired.

Git impact: The pipeline edits files. It does NOT commit, push, or amend.
          If you have uncommitted work you want to preserve, commit or stash
          first.

Proceed with full autonomous sweep? [Y/n]

0c. Parse the reply (first match wins, evaluate rules in order):

Hard negation (no, n, abort, cancel, 取消, 不要): abort with "Aborted before scan — no files modified."
Consent (Y, yes, ok, sure, proceed, go, continue, 好, 好的, 行, 可以): proceed to Step 1.
Soft pause (wait, hold on, 等一下, 等我, let me): acknowledge in one line ("Understood, waiting"), then wait for the user's next message and re-evaluate from rule 1.
Question: answer it, then re-show the notice once and wait for the next reply. If the next reply is not Consent (rule 2) — whether a second question, another pause, or anything else — abort with "Aborted — did not receive consent after clarification."

0d. After consent, do not ask further questions until Step 8.

Step 1 — Scope enumeration and state init

1a. Apply Auto Scope Detection from ../_shared/common.md if the user did not specify files or a directory. Otherwise honor the user's explicit scope.

1b. Read .brooks-lint.yaml from the project root if present. Apply disable, severity, ignore, focus, and custom_risks per common.md. Record the applied config values and reuse them across all iteration rounds — do not re-read the file in Step 6 even if files were modified.

1c. Initialize pipeline state (persists across all rounds):

unresolvable (set): findings retired after 3 failed attempts — keyed by (file, line_range, risk_code); signature breaks ties. Never re-queued.
non_critical_rounds (int, 0): incremented each round producing Warning/Suggestion; reset on clean round.
fix_log (list): each fix with file, line range, risk code, description, and outcome (applied / reverted / retired).

1d. Record the final scope file list in the Fix Report output buffer for Step 8.

Step 2 — brooks-review pass (R1–R6 code decay)

Scan every file in scope against all R-series risks defined in ../_shared/decay-risks.md.

2a. For each R-risk, apply its symptom checklist. Record each hit as a finding with: risk code, file + approximate line range, Symptom, Source, Consequence, Remedy, Severity (Critical / Warning / Suggestion), and Fix-Class (see Step 2b).

2b. Assign Fix-Class per finding:

Class	Criteria
Safe	Single-file AND fully local: rename a non-exported symbol, extract a constant, remove dead code, add a null guard at a leaf, add a test scaffold for an untested pure function. Any change that modifies or removes an exported symbol is NOT Safe even if in one file.
Extended-Safe	Multi-file but (a) a project test command exists and passes pre-fix, AND (b) the change does not rename, remove, or alter the signature of any publicly exported symbol, AND (c) touches ≤ 5 files in this pass.
Residual	Public API break, cross-service boundary change, no test coverage to fall back on, or remedy ambiguous. NOT applied — carried to the Step 8 residual report.

2c. Skip any finding that matches an entry in the unresolvable set.

2d. Apply every Safe and Extended-Safe fix in this dimension, lowest risk within each severity tier first. For each fix: Edit or Write, then append one row to fix_log with outcome applied. If two fixes touch overlapping line ranges in the same file, apply higher-severity first, re-read the file, then apply the next.

2e. After all fixes in this dimension, run the project test/lint command if one exists (package.json scripts, pytest, cargo test, go test ./..., etc.). If tests fail: revert fixes from this dimension in reverse order one at a time, re-running the test command after each revert, until tests pass. Mark each reverted fix with outcome reverted in fix_log and promote the finding to Residual. If no test command is found, note this once in the report and continue.

2f. Record dimension summary: N scanned, M Safe applied, K Extended-Safe applied, R reverted, P Residual.

Step 3 — brooks-test pass (T1–T6 test decay)

Scan test files (and untested production code) against T-series risks defined in ../_shared/test-decay-risks.md.

Follow the same sub-steps as Step 2 (classify → apply → verify → summarize), using T-prefix risk codes. For production files with no test coverage at all, record as T2 (Missing Tests). A test scaffold that adds a pure-function test is Safe; adding tests that require new test infrastructure is Residual.

Step 4 — brooks-debt pass (tech debt accumulation)

Re-classify R-findings through a debt lens — same symptoms at accumulation scale: repeated duplication, layered workarounds, stale TODO/FIXME clusters, dead flags. Score each with Pain (1–3) × Spread (1–3); total 7–9 = Critical, 4–6 = Warning, 1–3 = Suggestion. Apply a severity bump for pattern-level occurrences (isolated Suggestion → 4+ modules Warning).

Follow the same sub-steps as Step 2. Debt findings often span multiple files and are more likely to land in Extended-Safe or Residual than Safe.

Step 5 — brooks-audit pass (architecture integrity)

Scan the full scope for architecture-level issues. The dependency-direction symptoms (inverted dependencies, circular imports, cross-domain coupling) are defined in ../_shared/decay-risks.md Risk 5 — use that checklist. Step 5 additionally covers architecture-only concerns that R5 does not: missing abstraction layers, god modules, leaked infrastructure inside domain code, and seam-boundary violations.

Most architecture findings are Residual by definition — they require human judgment on module boundaries. A few are Extended-Safe (e.g. extract a shared constant used in 3+ modules into a new module that nothing else imports yet). Do not auto-refactor module layouts, rename packages, or change public exports.

Follow the same sub-steps as Step 2.

Step 6 — Iteration loop

Goal: Re-scan what the fixes touched and converge. Stop on clean round, cap, or no progress.

6a. Build the re-scan scope:

every file modified in Steps 2–5 of the current round, PLUS
every file in the same module as a modified file, PLUS
every file that statically imports from a modified file.

Do not re-scan files whose dependencies were not touched. On monorepos where a "module" may span hundreds of files, narrow the same-module bucket to files that import from or are imported by a modified file (direct dependency graph only).

6b. Re-run Steps 2–5 on the re-scan scope. For each new finding in this round:

If it matches an entry in unresolvable → skip.
Else if 🔴 Critical → queue and fix; Critical findings iterate until resolved OR retired (3 failed attempts → unresolvable).
Else 🟡 Warning / 🟢 Suggestion → queue and fix, subject to cap below.

6c. Classify the round after all fixes attempted:

Clean round (no new findings outside unresolvable): pipeline converged → proceed to Step 7.
Critical-only round: do NOT increment non_critical_rounds; return to 6a.
Mixed or non-critical round (any Warning / Suggestion produced): increment non_critical_rounds by 1. If it reaches the cap (default 3, or sweep.max_iterations from .brooks-lint.yaml), proceed to Step 7 with remaining non-critical findings recorded as "Unresolved — iteration cap reached". Otherwise return to 6a.

6d. Fix-retry rule: if a single finding fails verification (Step 2e) 3 times across any combination of rounds, retire it to unresolvable with reason "3-retry budget exhausted" and stop attempting it.

Step 7 — Residual aggregation

Collect everything that was NOT fixed in place, de-duplicated:

All Residual-class findings from Steps 2–5 (first round + re-scan rounds)
All unresolvable entries with their retirement reason
All iteration-cap residuals from Step 6c

Sort Critical → Warning → Suggestion. Within each severity, list file path, risk code, Symptom (one line), Remedy (one line), and the reason it was not applied (public API break / no test coverage / 3-retry budget / iteration cap).

Step 8 — Sweep report

Output the final report. Use the standard Report Template from ../_shared/common.md with these additions:

# Brooks-Lint — Full Sweep Report
Mode: Full Sweep | Scope: <files or directory>
Config: .brooks-lint.yaml applied (N risks disabled, M paths ignored)   # omit if no config

## Dimension Summary
| Dimension | Scanned | Safe Applied | Extended Applied | Reverted | Residual |
|-----------|---------|--------------|------------------|----------|----------|
| Review (R1–R6) | ... | ... | ... | ... | ... |
| Test (T1–T6)   | ... | ... | ... | ... | ... |
| Debt           | ... | ... | ... | ... | ... |
| Audit          | ... | ... | ... | ... | ... |

## Iteration History
Round 1: <classification — clean / critical-only / mixed>, <N> new findings
Round 2: ...
Stopped at: clean round | iteration cap | no outstanding criticals

## Fix Log
| # | File | Lines | Risk | Outcome  | Change |
|---|------|-------|------|----------|--------|
| 1 | ...  | ...   | R2   | applied  | Extract repeated constant |
| 2 | ...  | ...   | T4   | reverted | Test regression; promoted to Residual |
...

## Health Score Delta
Before: <estimated score>/100  →  After: <estimated score>/100
(Re-run /brooks-health for an exact recalculation.)

## Residual Items  (<K> not applied)
<Iron Law entries, sorted Critical → Suggestion, with "Not applied because: ..." line>

## Summary
- Total findings detected: <N>
- Fixed this sweep: <M>
- Residual (needs human review): <K>
- Unresolvable (3-retry exhausted): <U>

If there are zero residual items and zero unresolvable entries, end with: "Sweep complete — codebase is clean."

Mode line in report: Full Sweep

12 KiB Raw Blame History Unescape Escape