fix(ci-build-infra): document NuGet cache fallback safety and suppress System.Reactive packages.config warning (#730)

[drmoisan]

Suggested title

fix(ci-build-infra): document NuGet cache fallback safety and suppress System.Reactive packages.config warning (#730)

Summary

• Consolidates two build-infrastructure findings into one configuration-only change: (1) a documentation-only comment block explaining why the NuGet cache restore-keys bare-prefix fallback in three CI workflows is already safe, and (2) a new repository-root Directory.Build.props that suppresses the System.Reactive packages.config "unsupported scenario" warning.
• No application source code (.cs), .csproj, packages.config, or Directory.Build.targets file is touched by either fix.
• No coverage threshold, Pester job, or coverage gate is added or changed (that scope belongs to CI collects coverage but enforces no threshold: _mstest-coverage.yml never converts to Cobertura or compares a floor #561/No Pester job in CI: production PowerShell under scripts/vscode has zero CI coverage #562/Coverage threshold contradiction remains: CLAUDE.md/csharp.md say 80%, general-unit-test.md/quality-tiers.md say 85%/75%, and two live gates disagree #563).
• All 8 acceptance criteria in the spec are met and checked off, with full baseline/post-change evidence captured under the feature folder.
• A remediation cycle closed one artifact-hygiene finding from feature review: an absolute host path with the operator account name in the research document has been replaced with a <repo-root> placeholder.

Why

• Finding 1 (cache fallback): .github/workflows/_build-analyzers.yml, _build-nullable.yml, and _mstest-coverage.yml each use a bare-prefix restore-keys fallback (nuget-${{ runner.os }}-) with no lock-file hash and no restore-verification step. Research confirmed this is already safe for this repository's packages.config + classic nuget.exe restore model: every package is restored into a version-qualified directory (packages/{id}.{version}/) that exactly matches every HintPath, and nuget restore runs unconditionally after the cache step in all three workflows. The change documents this invariant rather than fixing a defect, since none exists.
• Finding 2 (System.Reactive warning): packages.config pins System.Reactive 7.0.0, which is unsupported for packages.config-style references and emits an "unsupported scenario" warning (System.Reactive.PackagesConfigCheck.targets) on every build of the five consuming projects. No suppression existed. RxUseUnsupportedPackagesConfig=true is the package's own documented escape hatch for this exact, intentionally-accepted trade-off (this repository keeps its legacy VSTO / .NET Framework 4.8.1 projects on packages.config rather than migrating to PackageReference).

What Changed

Tooling / CI

• .github/workflows/_build-analyzers.yml, _build-nullable.yml, _mstest-coverage.yml: identical 16-line explanatory comment block inserted immediately above restore-keys: in each file. Comment-only; key:, path:, uses: (actions/cache@v4), restore-keys: and its value, and the subsequent Restore solution step are byte-identical to before.

Build configuration

• Directory.Build.props (new, repository root): sets RxUseUnsupportedPackagesConfig to true inside a <PropertyGroup>, with an inline XML comment documenting the accepted trade-off. Picked up automatically by all five System.Reactive-consuming projects via MSBuild's standard Directory.Build.props auto-import; inert for the other thirteen projects in the solution.

Docs / evidence

• Feature folder (docs/features/active/2026-09-02-ci-build-infra-debt-730/): issue, spec, research, atomic plan (9 preflight/revision rounds, documented in the plan's own Framing section), and full baseline/post-change evidence (msbuild rebuild logs, csharpier check, vstest regression run, git-scope-boundary diffs).
• A remediation cycle (also fully evidenced) fixed one artifact-hygiene finding: an absolute host path with the operator account name in research/research.2026-09-02T09-15.md line 8, replaced with the <repo-root> placeholder already used elsewhere in this feature's evidence.

Architecture / How It Fits Together

Both fixes are additive, independent, and configuration-only:

• The comment block sits above an unmodified restore-keys: key; it has zero effect on YAML evaluation, cache key computation, or the cache/restore step's control flow.
• Directory.Build.props is picked up by MSBuild's Microsoft.Common.props auto-import chain, the same mechanism already proven live in this repository through the existing Directory.Build.targets file. It supplies exactly one new property that no .csproj currently sets, so there is no override or collision risk with any of the eighteen projects in the solution.

Verification

Completed (evidence under docs/features/active/2026-09-02-ci-build-infra-debt-730/evidence/):

• dotnet tool run csharpier check . — exit 0, no formatting drift.
• msbuild TaskMaster.sln /t:Rebuild ... /p:EnableNETAnalyzers=true /p:EnforceCodeStyleInBuild=true — baseline: 5 System.Reactive.PackagesConfigCheck warnings (one per affected project: QuickFiler, TaskMaster, ToDoModel, UtilitiesCS, UtilitiesCS.Test), 0 errors. Post-change: 0 such warnings, 0 errors — genuine recompiles confirmed via csc.exe/CoreCompile invocation counts in both logs.
• msbuild TaskMaster.sln /t:Rebuild ... /p:TreatWarningsAsErrors=true — same baseline-to-zero warning delta, 0 errors in both passes.
• vstest.console.exe regression run (UtilitiesCS.Test + QuickFiler.Test, /EnableCodeCoverage /InIsolation) — 6095/6095 passed, 0 failed.
• Workflow diffs independently verified comment-only (dual-parser deep comparison against origin/main during feature review).
• Absolute-host-path sanitization: 0 residual matches for the operator account name across the entire changed-file set, confirmed via a run-time-derived (not hardcoded) sweep.

Recommended (not run by this branch, informational only):

• Confirm on the first post-merge CI run of each of the three named workflows that cache hit/miss/fallback behavior is unaffected (expected, since the diff is comment-only).
• Confirm on the first post-merge full solution rebuild that the five System.Reactive.PackagesConfigCheck warnings no longer appear.

Backward Compatibility / Migration Notes

None. Both fixes are fully backward compatible:

• The comment insertion changes no evaluated YAML semantics.
• Directory.Build.props introduces a new, additive property recognized only by System.Reactive.PackagesConfigCheck.targets; it is silently ignored by every other project in the solution.
• No file rename, removal, or breaking change of any kind.

Risks and Mitigations

• Solution-wide reach of Directory.Build.props. A root-level Directory.Build.props is auto-imported by all eighteen .csproj files in the solution, not just the five System.Reactive-consuming ones. Mitigation: this change adds exactly one property, confirmed inert for the thirteen non-System.Reactive projects; any future addition to this file should be re-evaluated for solution-wide impact before merging.
• Vendor guard-target behavior not directly inspected. The exact System.Reactive.PackagesConfigCheck.targets XML was not read directly during research (packages were not yet restored in that session), so the property name/effect rests on corroborating evidence rather than a live read of the vendor file. Mitigation: the pre/post rebuild-transcript verification in this PR directly observes the real vendor guard target's behavior at build time (5 warnings → 0), closing this gap empirically.
• Repository history still contains the pre-sanitization research document blob in four earlier commits on this branch (the file was modified, not added, so its prior content remains reachable via those commits' trees). Mitigation: recommend a squash merge for this PR so the pre-sanitization blob does not become reachable from main's history.

Review Guide

Suggested order:

1. Directory.Build.props (new file, 19 lines) — the substantive change.
2. The three workflow file diffs — mechanically identical 16-line comment insertions; diffing any one confirms the pattern for all three.
3. docs/features/active/2026-09-02-ci-build-infra-debt-730/spec.md — acceptance criteria and scope boundaries.
4. Evidence files under evidence/baseline/ and evidence/qa-gates/ — supporting proof, not required reading for a correctness review of the two fixes themselves.

Noisy/mechanical: four raw MSBuild rebuild logs (evidence/*.log, ~11.7–12k lines each) are committed as evidence; they are sanitized of host-identifying paths and do not need line-by-line review.

Follow-ups

• Four references to the mutable path docs/features/active/2026-09-02-ci-build-infra-debt-730/... (three workflow comments, one Directory.Build.props comment) will go stale once this feature folder is archived. Not addressed in this PR to keep the change strictly scoped; a follow-up cleanup can drop the path prefix and rely on the issue #730 reference already present in each comment.
• Cosmetic: the inserted comment block sits at 12-space indentation (matching the restore-keys: block-scalar value), one level deeper than the sibling key:/restore-keys: lines at 10 spaces. Confirmed functionally inert (dual-parser verification), but could be dedented for visual consistency in a future pass.

GitHub Auto-close

• Closes Bug: ci-build-infra-debt #730