Docs checks workflow (bdfinst/agentic-dev-team)

name: Docs checks
 
# Catches broken documentation links before they merge - the class of breakage a
# deleted or renamed doc leaves behind (e.g. a nav entry or README link pointing at
# a file that no longer exists).
#
# Relationship to the local gate (issue #531): the `nav-integrity` job below is
# the CI superset of `chk_nav_integrity` in `scripts/ci-local.sh`. Both assert
# every nav entry resolves to a file (via `check_nav_integrity.py`); CI *also*
# runs `mkdocs build` and offline `lychee` on top. Those two tools are kept
# CI-only intentionally so contributors don't have to install them locally -
# `chk_nav_integrity` is the fast subset every developer can run before pushing.
 
on:
  # No 'paths' filter, on purpose. nav-integrity and body-links are REQUIRED
  # status checks, and a path-filtered workflow reports NO status on PRs that
  # don't match the filter - deadlocking every unrelated PR at "Waiting for
  # status to be reported" (it can never go green). Both jobs are cheap and
  # hermetic (assemble + mkdocs build + offline lychee), so they run on every
  # PR and always report. (Same rationale as agent-eval.yml's free gates.)
  pull_request:
  push:
    branches: [main]
  workflow_dispatch:
 
permissions:
  contents: read
 
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
 
jobs:
  # Validates the MkDocs nav: a nav entry pointing at a missing file fails the build.
  nav-integrity:
    timeout-minutes: 30
    name: Docs nav integrity
    runs-on: latchkey-small
    steps:
      - uses: actions/checkout@v7
 
      - uses: actions/setup-python@v6
        with:
          cache: 'pip'
          python-version: "3.x"
 
      - name: Install MkDocs dependencies
        run: pip install -r requirements-docs.txt
 
      - name: Assemble docs sources
        run: bash scripts/assemble-docs.sh
 
      - name: Build site
        run: mkdocs build --site-dir /tmp/site
 
      # Same nav-integrity assertion the local gate runs (scripts/ci-local.sh's
      # chk_nav_integrity), kept in one script so CI and pre-push can't drift.
      - name: Assert every nav entry resolves to a file
        run: python3 scripts/check_nav_integrity.py
 
  # Validates relative links and anchors inside the documentation bodies. Offline:
  # only local file links are resolved, so external link rot never flakes the gate.
  body-links:
    timeout-minutes: 30
    name: Docs link check
    runs-on: latchkey-small
    steps:
      - uses: actions/checkout@v7
 
      - name: Check documentation links
        uses: lycheeverse/lychee-action@v2
        with:
          args: >-
            --offline
            --no-progress
            README.md
            GETTING-STARTED.md
            CONTRIBUTING.md
            CHANGELOG.md
            docs/**/*.md
            plugins/dev-team/README.md
            plugins/dev-team/docs/**/*.md
          fail: true