Cleanup plan vs pre-commit analyzer gate: rule-family-per-agent decomposition blocks single-package PRs

[rygel]

Problem

The pre-commit analyzer gate (scripts/pre-commit-analyzer-gate.ps1) runs dotnet format style --severity warn and dotnet format analyzers --severity warn across all configured rules on every changed file. But docs/analyzer-cleanup/05-agent-assignments.md decomposes the cleanup work by rule family per agent (Agent A = SA1210, Agent B = SA15xx, Agent E = VSTHRD103, etc.). These two designs are partially incompatible: a single-package PR can land only when a file's co-located warnings all belong to the same agent's assigned rule family.

When a file has findings from multiple rule families (common — e.g. CLI/Program.cs has both SA1210 and VSTHRD103), any agent touching that file for their rule gets blocked by everyone else's co-located findings. The handoff forbids --no-verify, forbids suppressing analyzer rules, and constrains each agent to their own rule family — so there is no in-agent path to land.

Evidence

This hit repeatedly while executing Packages 02A, 01A, 01B, 02B, 03A, 03B, 03C–03F (PRs #736, #738, #739, #740, #741, #742, #743):

• PR test: fix provider analyzer findings (Package 02A / Agent C) #736 (Agent C / 02A): 2 pre-existing IDE0005 warnings on scoped test files blocked the gate. Owner authorized removing the redundant usings.
• PR style: fix non-test SA1210 using order (Package 01A / Agent A) #738 (Agent A / 01A): 22 pre-existing IDE0005 + co-located VSTHRD103/SA1501/SA1512/SA1513/SA1515 warnings blocked 6 of 24 files. Landed only the 18 clean files; deferred the other 6 to Agents B/E.
• PR style: fix Monitor/UI layout analyzer findings (Package 01B / Agent B) #740 (Agent B / 01B): picked up the deferred SA1210/IDE0005 fixes on those same files once the SA15xx blockers were cleared. Required expanding scope beyond the SA15xx family.
• PR fix: replace sync JSON/file APIs with async (Package 03A / Agent E) #741 (Agent E / 03A): needed IDE0005 cleanups + an MA0004 pragma reflow on the touched files.
• PR fix: narrow catch-all exception handlers (Package 03B / Agent F) #742 (Agent F / 03B): needed an SA1615 doc-tag addition (a rule the Release build doesn't even enforce due to SA0001).

Each PR had to either (a) expand scope to clean co-located findings from other rule families, or (b) defer files and leave assigned findings unlanded.

Impact

• Reviewer cognitive load: each cleanup PR mixes multiple rule families because it has to. Reviewers can't easily verify "this PR is purely SA1210."
• Plan-ordering rigidity: Agent B (01B) effectively depends on Agent A (01A) being deferred-partial, and Agent E (03A) gets dragged into Agent A's files. The "one package per agent" model degrades into "whoever touches a file last cleans everything."
• Agent H (rule promotion) is hard to land: promoting any rule to error requires the entire codebase to be clean for that rule, but the gate already enforces zero-warning on changed files — so the promotion's blast radius is wider than any single agent can address.

Suggested options (not prescriptive)

1. Narrow the changed-file gate to assigned rule families. Add a per-PR allow-list (e.g. a \.analyzer-gate/scope.json entry per branch) so the gate only enforces the rules the PR claims to fix. Keep the full gate for the merge-to-main path. Smallest behavior change; preserves the package decomposition.
2. Re-decompose packages to be file-complete. Group by file rather than rule family: each agent owns a set of files and fixes all warnings in them. Eliminates the cross-package dependency but produces larger, less reviewable PRs.
3. Run a one-shot repo-wide cleanup pass outside the agent model: a single PR that fixes all warnings across all files, then enable the full gate. Highest-risk single PR but removes the decomposition problem entirely.
4. Add InternalsVisibleTo / test scaffolding up front for the rules that need regression tests (e.g. WebProviderUsageMapper.Map is internal with no test access — Agent G's 03F couldn't add a focused test without a production-assembly policy change).

Recommendation

Option 1 is the smallest change that unblocks the remaining agents (especially H) without restructuring the plan. It also keeps each PR's scope honest — a reviewer reading "Package 01A" can trust the diff is SA1210-only.

Out of scope of this issue

The 7 linked PRs are all merge-ready (green CI, gate-passed). This issue is about the next round of cleanup work and the promotion step (Agent H), not about the current PRs.

cc @rygel

[rygel]

Update: Agent H (rule promotion) complete

The cleanup's terminal step is done. After PRs #736, #738, #739, #740, #741, #742, #743, #745, #746 all merged with a zero-warning baseline, Agent H promoted the now-clean rule families from warning to error severity in three steps:

Step	PR	Rules promoted to error
1	#747	SA1210, SA1101, IDE0009, MA0006
2	#748	SA1501, SA1503, SA1507, SA1512, SA1513, SA1515
3	#749	CA1031 (prod only; test scope keeps none), CA2024, VSTHRD003, VSTHRD103

All three are merged to develop. Each promotion was verified per the handoff's step-7 contract: clean-tree build stays clean (0 errors), and a deliberately-introduced violation correctly fails the build as error (probed each group with a temporary violation in ProviderUsage.cs, then reverted).

Final state of merged develop: fresh non-incremental Release build = 0 errors; AIUsageTracker.Tests 1418 pass / 2 pre-existing skips; AIUsageTracker.Monitor.Tests 142 pass. CI will now reject any PR that reintroduces these 16 rule violations in production code.

Status of this issue's options

The structural mismatch described here is still real for future cleanup work — any agent touching a file with co-located warnings from multiple rule families will hit the same gate friction. But for the 16 rule families the cleanup plan tracked, the problem is now moot: they're all at error severity, so the gate fails loudly on any reintroduction rather than silently accumulating warnings. Option 1 (narrow the gate to assigned rule families) is no longer needed for these rules. The remaining deferred items from the original plan are:

• Group 4 (currently-suppressed member-ordering rules SA1201/02/04/14, SA1117/18, SA1402): still at none severity in .editorconfig. The plan's step 4 order. Requires the per-rule enable-fix-promote cycle.
• Group 5 (documentation rules SA1600/01/02/04/11/16/18, SA1651): still at none. Requires a repo policy decision on required XML documentation per the plan's step 5.

These are out of scope of the just-completed cleanup but documented here for whoever picks up the next round.

Note on pre-existing flaky tests discovered during Agent H

Two tests intermittently failed during full-suite gate runs under machine load, unrelated to any cleanup change:

• UpdateChannelConfigurationEndToEndTests.GenerateAppcastScript_* — spawns generate-appcast.sh as a subprocess; intermittently hits STATUS_DLL_INIT_FAILED (0xC0000142) on Windows.
• UpdatePipelineEndToEndTests.BetaDownloadUrl_ForEachArchitecture_ReturnsHttp200 — live-network integration test.

Both pass reliably in isolation (3/3 runs each). They're pre-existing environmental flakiness and should probably be [Trait("Category","Integration")]-gated or skipped on local runs in a separate follow-up.