test: guard apply_fix -> al_compile freshness and correct the stale-diagnostic note

[Arthurvdv]

Summary

• Add an end-to-end regression test that exercises apply_fix → al_compile against the real almcp child process, confirming fixed diagnostics disappear.
• Correct documentation and tool descriptions from PR feat!: proxy Microsoft's almcp, narrow ALCops MCP to code fixes, require BC DevTools 18.0 #20 that incorrectly suggested using al_getdiagnostics to verify fixes.

What changed

Test files:

• ApplyFixThenCompileTests.cs (new) — ApplyFixAlMcpFixture launches the full server, applies a code fix, then calls al_compile(onlyErrors: false) and asserts the fixed diagnostic is gone. A skipped al_getdiagnostics variant documents why that endpoint cannot verify fixes.
• AlMcpProxyTests.cs — CreateProxy() gains an optional fixtureName parameter so the new fixture can reuse the helper.

Docs & tool descriptions:

• ApplyFixTool.cs / ApplyFixAllTool.cs — tool descriptions now say: "Verify with al_compile (onlyErrors: false)."
• README.md — new "Verifying a fix" section after the onlyErrors note.
• AGENTS.md — new bullet in "Tool patterns" explaining al_compile vs al_getdiagnostics after a fix.

Reproduction outcome

Characterization (10 consecutive runs, no settle delay): 10/10 PASS.

This is the "passes every run" branch of the decision tree. The race between our file write and almcp's ProjectWatcher (FileSystemWatcher) is not reproducible on this machine: al_compile awaits WaitForProcessingAsync before compiling, and the OS delivers the change event quickly enough that the old text is never compiled.

No runtime code change was needed. The test stays as a regression guard.

The al_getdiagnostics variant confirmed the watcher-drain analysis: it returns {"succeeded":true,"diagnostics":[],"errorCount":0} — zero diagnostics — because it reads cached compilation results rather than re-analyzing. This test is [Skip]-ped with documentation.

Likely sources of the original report: using al_getdiagnostics (returns cached, never re-compiles), a child that had run al_downloadsymbols (disposes the workspace), or a project outside the child's --projects set.

Test plan

• dotnet build --configuration Release — 0 warnings, 0 errors
• dotnet test --configuration Release — 69 passed, 0 failed, 1 skipped (the al_getdiagnostics variant, intentionally skipped)
• 10-run loop of ApplyFix_ThenAlCompile_NoLongerReportsFixedDiagnostic — 10/10 pass with no settle delay

Corrects PR #20's known-issue note

PR #20 noted that al_compile might return stale diagnostics after apply_fix, suggesting callers add a delay or call al_getdiagnostics. This was backwards: the child almcp does not serve a cached compilation for al_compile. It has a per-project FileSystemWatcher (ProjectWatcher) whose pending events al_compile drains via WaitForProcessingAsync before compiling, so it always picks up on-disk changes. al_getdiagnostics, on the other hand, returns the last cached compilation result without re-analyzing — it is the endpoint that misses changes. Only a full child process restart produces a truly "clean" state, but al_compile is fresh enough for verification after a fix.

🤖 Generated with Claude Code