clash-verge-rev/.github/workflows/docs-consistency.yml

name: docs-consistency

# Checks routing anchors and local links in collaboration documents.
# Wording checks do not establish semantic agreement between policies.
on:
  pull_request:
    paths:
      - CONTRIBUTING.md
      - AGENTS.md
      - CLAUDE.md
      - GEMINI.md
      - REVIEW.md
      - src/AGENTS.md
      - src-tauri/AGENTS.md
      - .github/ISSUE_GUIDELINES.md
      - .github/agents/agentic-workflows.md
      - .github/skills/agentic-workflows/SKILL.md
      - .github/PULL_REQUEST_TEMPLATE.md
      - .github/workflows/pr-ai-slop-review.md
      - .github/workflows/docs-consistency.yml
  push:
    branches: [dev]
    paths:
      - CONTRIBUTING.md
      - AGENTS.md
      - CLAUDE.md
      - GEMINI.md
      - REVIEW.md
      - src/AGENTS.md
      - src-tauri/AGENTS.md
      - .github/ISSUE_GUIDELINES.md
      - .github/agents/agentic-workflows.md
      - .github/skills/agentic-workflows/SKILL.md
      - .github/PULL_REQUEST_TEMPLATE.md
      - .github/workflows/pr-ai-slop-review.md
      - .github/workflows/docs-consistency.yml
  workflow_dispatch:

permissions:
  contents: read

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - name: Check cross-document anchors
        run: |
          check() { grep -q "$2" "$1" || { echo "::error::anchor '$2' missing from $1"; exit 1; }; }
          check CONTRIBUTING.md '## Contribution Expectations'
          check CONTRIBUTING.md 'ai-slop:med'
          check CONTRIBUTING.md 'ai-slop:high'
          check AGENTS.md 'Issue first'
          check AGENTS.md 'Author accountability'
          check AGENTS.md 'pr-ai-slop-review'
          check AGENTS.md 'Disclose AI automation'
          check CONTRIBUTING.md 'Assisted by:'
          check .github/workflows/pr-ai-slop-review.md '(../../CONTRIBUTING.md)'
          check .github/workflows/pr-ai-slop-review.md '(../../AGENTS.md)'
          check AGENTS.md 'gh aw compile'
          check CONTRIBUTING.md 'gh aw compile'
          check AGENTS.md 'Tests are justified'
          check CONTRIBUTING.md 'Do not pad'
          check CLAUDE.md '@AGENTS.md'
          check GEMINI.md 'AGENTS.md'
          check AGENTS.md 'REVIEW.md#ai-context-sharing'
          check REVIEW.md '## AI Context Sharing'
          check CONTRIBUTING.md '(REVIEW.md)'
          check .github/workflows/pr-ai-slop-review.md 'Linkage Laundering'
          check .github/PULL_REQUEST_TEMPLATE.md '## Problem'
          check .github/PULL_REQUEST_TEMPLATE.md '## Approach'
          check .github/PULL_REQUEST_TEMPLATE.md '## Scope'
          echo "All cross-document anchors are consistent."
      - name: Check local documentation links
        run: |
          python3 - <<'PY'
          import re
          from pathlib import Path
          from urllib.parse import unquote, urlsplit

          sources = [
              "AGENTS.md", "CONTRIBUTING.md", "REVIEW.md", "CLAUDE.md", "GEMINI.md",
              "src/AGENTS.md", "src-tauri/AGENTS.md", ".github/ISSUE_GUIDELINES.md",
              ".github/PULL_REQUEST_TEMPLATE.md", ".github/workflows/pr-ai-slop-review.md",
              ".github/agents/agentic-workflows.md", ".github/skills/agentic-workflows/SKILL.md",
          ]
          errors = []
          for source in map(Path, sources):
              text = re.sub(r"(?ms)^```.*?^```[^\n]*", "", source.read_text())
              for href in re.findall(r"\]\(([^\s)]+)\)", text):
                  link = urlsplit(href)
                  if link.scheme or link.netloc:
                      continue
                  target = source.parent / unquote(link.path) if link.path else source
                  if not target.exists():
                      errors.append(f"{source}: missing target {href}")
                  elif link.fragment and target.suffix == ".md":
                      headings = re.findall(r"(?m)^#{1,6} +(.+?) *#*$", target.read_text())
                      anchors = {re.sub(r"[^\w -]", "", h.lower()).replace(" ", "-") for h in headings}
                      if unquote(link.fragment) not in anchors:
                          errors.append(f"{source}: missing heading {href}")
          for error in errors:
              print(f"::error::{error}")
          if errors:
              raise SystemExit(1)
          print(f"Local links checked in {len(sources)} collaboration documents.")
          PY
      - name: How to fix a failure
        if: failure()
        run: |
          cat <<'EOF'
          A routing anchor or local link is missing. Update the reference and
          its target together. For intentional wording changes, update this
          check's anchor list and review policy agreement separately.
          EOF