Gate the markdown link checker on a fingerprint of the broken links

[Azat Mukhametshin (azat-msft)]

Problem

md-link-checker runs every Friday and starts Copilot unconditionally, even when the deterministic scan finds nothing. The three most recent clean scheduled runs each reported 190 working, 0 broken and together burned 48.523 AI credits deciding there was nothing to do:

Run	Result	AI credits
2026-08-07	190 working, 0 broken	15.205
2026-08-14	190 working, 0 broken	16.381
2026-08-21	190 working, 0 broken	16.937

Approach

Mirrors the HTTP checker design in #16413 (now merged; this branch has been merged with main). md-link-check-probe.yml takes over the Friday slot, runs check-md-links.py, and dispatches the agent only when the broken set differs from the checked-in fingerprint at .github/workflows/scripts/known-broken-md-links.txt.

Comparing whole sets, rather than gating on broken_count > 0, matters because the workflow deliberately supports links that cannot be fixed. Counting alone would wake the agent every week for links already reviewed and accepted.

check-md-links.py gains broken-links.txt: the broken set as sorted, unique source_file|link lines. It carries only the source file and the link as written — no resolved paths, counts, or report wording — with forward slashes and LF endings, so the same breakage produces the same bytes on a Windows laptop and on the runner, and rewording the report can never move the fingerprint. It is written on the early-exit paths too, so the probe never has to guess whether a missing file means "clean" or "the scan did not run".

md-link-checker.md becomes dispatch-only and refreshes the fingerprint before opening its PR, so both fixes and reviewed-unfixable links are recorded.

Duplicate-run protection

The safe-output prefix changes from the shared [link-checker] to [md-link-checker]. With the shared prefix, an open HTTP checker PR would suppress the markdown checker's dispatch, and vice versa. The probe also skips dispatch when an agent run is already in flight but has not opened its PR yet, and uses a concurrency group so two probes cannot race.

The open-PR guard does not trust the search count. GitHub matches a quoted phrase loosely and ignores the brackets, so '"[md-link-checker]" in:title' also returns titles that merely contain the words md link checker — in this repo it returns #16131, which carries no prefix at all. A false match fails quietly in the expensive direction: the probe would decide a checker PR is already open and skip dispatch, leaving genuinely new broken links unreviewed for as long as that unrelated PR stays open. The search is kept only as cheap server-side narrowing, and jq re-checks the real startswith("[md-link-checker] ") prefix.

Worth a follow-up, not changed here: the merged HTTP probe's guard has the same looseness. Searching '"[link-checker]" in:title' matches #16417, #16413, and #16104, none of which carry the prefix. Left alone to keep this PR scoped.

Files

File	Change
.github/workflows/md-link-check-probe.yml	New scheduled deterministic gate
.github/workflows/md-link-checker.md	Dispatch-only, [md-link-checker] prefix, fingerprint update
.github/workflows/md-link-checker.lock.yml	Regenerated (gh-aw v0.81.6, the version the repo is compiled with)
.github/workflows/scripts/check-md-links.py	Stable machine-readable broken set
.github/workflows/scripts/known-broken-md-links.txt	Accepted fingerprint (currently empty)
.github/workflows/README.md, .github/agents/md-link-checker.md	Document probe vs. agent

Validation

All of these were executed, not just reasoned about, and re-run after merging main:

• Script reports 190 working, 0 broken against the repo; the fingerprint is legitimately empty.
• Fixture run with broken links confirms broken-links.txt is sorted, forward-slashed, LF-only, and preserves paths with spaces and cross-file anchors.
• Compare step run against fixtures — no dispatch for a matching, reordered, or comments-only fingerprint; dispatch for added, removed, and missing fingerprints. The comments-only case caught a real bug: grep -v exits 1 when the file is all comments, which set -e would have turned into a step failure. Fixed with || true.
• Dispatch guards run against a stubbed gh — skips on an open PR, skips on an in-flight run, dispatches when clear.
• Prefix filter verified against live data: the loose search returns 1 PR and the filtered count is 0, while the same filter still finds all 6 genuinely prefixed [link-checker] PRs.
• gh aw compile md-link-checker succeeds and the regenerated lock has only workflow_dispatch.
• Probe YAML parses; every run: block passes bash -n.

Confirmed that workflow_dispatch is a documented exception to the GITHUB_TOKEN recursion-prevention rule, so the probe can dispatch the agent with the default token.

Note: as in #16413, dropping the schedule makes gh-aw omit the agent's gh-aw-copilot-${{ github.workflow }} concurrency group. The probe's in-flight check covers the automated path.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Note

This error may be related to your runner configuration. You can now configure runners for Copilot code review separately from Copilot cloud agent by creating a copilot-code-review.yml file with your setup steps. Read the docs for details.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

Suppressed comments (2)

Previously missed (2) — in code that hasn't changed since the last review.

.github/workflows/md-link-check-probe.yml:76

• The known-fingerprint parsing claims the file is “forgiving to edit by hand”, but the pipeline only drops full-line comments/blank lines and does not trim leading/trailing whitespace. If someone indents an entry (or a line gains trailing spaces), it will be treated as a distinct fingerprint entry and the probe will dispatch even when the broken set is unchanged. Trimming whitespace makes the comparison robust without changing the accepted format.

            # Drop blank lines and '#' comments so the file stays forgiving to edit by hand.
            # A real entry is "source_file|url", and a source path never starts with '#'.
            # grep exits 1 when the file is nothing but comments, which is the normal state
            # while the accepted set is empty, so its status must not fail the step.
            { grep -v '^[[:space:]]*#' "$KNOWN" || true; } | awk 'NF' | sort -u > "$OUT_DIR/known.sorted"

.github/workflows/md-link-checker.md:166

• This section says to “commit the fingerprint update” but then directs the agent to use create-issue. Accepting/reviewing unfixable anchors requires updating the checked-in fingerprint, which is a code change that needs a PR; otherwise the probe will keep dispatching on every run. Align this branch with the HTTP checker pattern: when the working tree changes (including the fingerprint), create a PR and document the unfixable anchors in the PR body instead of creating an issue.

**If you could not fix anchors**
- Still commit the fingerprint update, so the reviewed-and-unfixable links stop waking you weekly
- Use the `create-issue` safe output to create an issue with broken links
- In the issue description, include:
   - A summary of how many links could not be fixed

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.