1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
# WHAT THIS WORKFLOW SHOULD DO (Intent-Driven Architecture)
#
# PURPOSE:
# This workflow should ensure Table of Contents in markdown files stays synchronized
# with actual content WITHOUT automatically modifying the repository. It should fail
# CI if TOC is out of date, forcing developers to update it locally.
#
# RESPONSIBILITIES:
# 1. Validate TOC is current in all markdown documentation
# 2. Fail CI check if TOC is outdated
# 3. Provide clear instructions on how to fix TOC issues
# 4. Only run when markdown files are modified (path filtering)
# 5. Never commit changes automatically to avoid merge conflicts
#
# CONSTRAINTS:
# - Must use CHECK_ONLY mode (never auto-commit)
# - Must only trigger on pull requests, not pushes to master
# - Must filter for markdown file changes only
# - Must complete quickly (<5 minutes typical)
# - Must provide actionable error messages when failing
#
# ERROR HANDLING:
# - TOC outdated → Fail check with instructions on how to regenerate
# - Tool error → Fail with diagnostic information
# - Network issue → Retry once, then fail
#
# CORE TEAM BEST PRACTICE:
# CI validates, it never modifies. Developers own their commits completely.
#
# REFACTORING PRIORITIES:
# - [P1] Add comment to PR when TOC validation fails with fix command
# - [P2] Cache dependencies for faster runs
name: TOC Validation
on:
pull_request:
paths:
- 'README.md'
- 'docs/**/*.md'
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
validate-toc:
name: Validate Table of Contents
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- name: Checkout
uses: actions/checkout@v5
with:
fetch-depth: 0
- name: Validate TOC is up to date
uses: technote-space/toc-generator@v4
with:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
TARGET_PATHS: 'README.md,docs/**/*.md'
CHECK_ONLY: 'true'