ci: make nav-integrity's mkdocs build --strict (#2118 follow-up, blocked on workflow scope)

[bdfinst]

Context

Follow-up to #2118 (now fixed in PR #2121, which clears the 72-item broken-link/anchor backlog against the assembled _mkdocs_src tree). This issue tracks the remaining CI-gap closure: .github/workflows/link-check.yml's nav-integrity job's mkdocs build doesn't currently fail on a broken link or anchor against the assembled tree — the same detection gap #2113 originally found.

Design update, superseding this issue's original advisory-step proposal: mkdocs.yml's validation.links.not_found/anchors options cannot be set to error in the installed MkDocs version — confirmed against mkdocs.config.defaults._LogLevel, which validates strictly against {"warn", "info", "ignore"}. So the actual hard gate is mkdocs build --strict, which aborts the build on any WARNING-level log line (broken links and anchors are both logged at WARNING). This is a stronger fix than the originally-planned advisory-only step, and is safe to land now that #2118's backlog is clear (0 broken links/anchors as of PR #2121).

This has been prepared, verified, and committed locally, but — as before — this session's credentials lack the workflow OAuth scope needed to push a .github/workflows/*.yml change (both git push and the GitHub content-write API reject it with the same error). This issue tracks applying that prepared, verified change.

Exact diff to apply

In .github/workflows/link-check.yml, nav-integrity job, replace:

      - name: Build site
        run: mkdocs build --site-dir /tmp/site

with:

      # --strict (#2118): fails the build on any relative-link or anchor
      # warning against the *assembled* site tree, not just the raw repo tree
      # `body-links` (below) validates — the gap #2113 found undetected. Safe
      # to make blocking now: the 60-item pre-existing backlog #2118 tracked
      # is cleared. mkdocs.yml's own `validation:` block can't express this
      # per-check (this MkDocs version's `links.not_found`/`anchors` only
      # accept warn/info/ignore, no `error`), so `--strict` — which escalates
      # every WARNING-level build log line, not just links — is the gate.
      - name: Build site
        run: mkdocs build --strict --site-dir /tmp/site 2>&1 | tee /tmp/mkdocs-build.log

And after the existing "Assert every nav entry resolves to a file" step, add:

      # Convenience summary only — "Build site" above is what actually blocks.
      # Runs even when that step failed so the count is visible without
      # scrolling the full build log.
      - name: Report assembled-tree broken-link count
        if: always()
        run: |
          count=$(grep -c "target .* is not found among documentation files" /tmp/mkdocs-build.log || true)
          echo "Broken links against the assembled docs tree: ${count:-0}"
          if [ "${count:-0}" -gt 0 ]; then
            echo "::warning::${count} broken link(s) found against the assembled docs site tree — see the 'Build site' step log above for the full list."
          fi

Verified locally (not a guess)

• A clean build (post PR fix(docs): fix 72 broken links/anchors against the assembled site tree #2121) passes with --strict: exit 0.
• A deliberately reintroduced broken link ([bogus](does-not-exist.md) appended to README.md, then reverted) fails it: exit 1, Aborted with 1 warnings in strict mode! — proving the gate can actually fail, not just report.
• python3 -m pytest tests/repo/test_required_status_checks.py -q still passes: this adds a step to the existing nav-integrity job, not a new job, so no new required-check registration is needed.

Acceptance

• .github/workflows/link-check.yml's nav-integrity job builds with --strict
• tests/repo/test_required_status_checks.py still passes
• A PR run with a deliberately broken link fails the Docs nav integrity check; a clean PR passes it

---

Generated by Claude Code

[github-actions]

⚠️ This issue title is not a Conventional Commit.

Specs become epics and plan slices become sub-issues, and these titles seed branch names, PR titles, and release versions — so they must follow the same commitlint ruleset as commits (for example: feat:, fix:, docs:, chore:).

�[90m⧗�[39m   --- input ---
�[1mci: add advisory assembled-site broken-link count to nav-integrity (#2113 part 2, blocked on workflow scope)�[22m
�[31m✖�[39m   header must not be longer than 100 characters, current length is 108 �[90m[header-max-length]�[39m

�[1m�[31m✖�[39m   found 1 problems, 0 warnings�[22m
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

Edit the title to fix; this check re-runs on every edit and clears the label once it passes.