[product-manager-impersonator] Trigger table parity lint for workflow READMEs #1082

Feature Idea

Summary: Add a lint check that verifies each gh-agent-workflows/*/README.md Trigger table matches the workflow events defined in its sibling example.yml.

Why a Customer Would Want This

Users copy these example.yml files directly into their repos, but most people first read each workflow README to decide what to install. When trigger docs drift from example.yml, teams misconfigure automation and only discover it after rollout.

Rough Implementation Sketch

• Add a small script (for example, scripts/check-trigger-docs.py) that parses each gh-agent-workflows/*/example.yml on: section and compares it to the workflow README Trigger table.
• Fail with actionable diffs (missing event, wrong type, extra documented trigger, etc.).
• Wire the check into make lint and CI next to existing repository-specific consistency checks.
• Document the rule in gh-agent-workflows/DEVELOPING.md so contributors know Trigger tables are contract-checked.

Why It Won't Be That Hard

This is a focused static validation pass over files already kept side-by-side, with existing precedent for custom lint scripts in this repository. It is additive (no behavior change in runtime workflows) and has a small surface area.

Evidence

• gh-agent-workflows/DEVELOPING.md:38-43 and :158-160 define separate, manually maintained README.md + example.yml artifacts per workflow.
• gh-agent-workflows/issue-triage/README.md:19-24 and gh-agent-workflows/issue-triage/example.yml:2-4 show the same trigger contract duplicated across docs and YAML.
• Makefile:204-217 and :243-245 show existing lint coverage but no trigger-doc parity check.
• .github/workflows/ci.yml:27-33 plus scripts/check-nav-catalog.py demonstrate established precedent for repo-specific consistency gates.
• Recent direction emphasizes contract reliability (#1030, #1012), so this fits current maintenance priorities.

Non-duplication Notes

• Distinct from #796 (linting validity of example.yml syntax itself).
• Distinct from #1041 / #449 (input/output docs parity, not trigger parity).

tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

What is this? | From workflow: Trigger Product Manager Impersonator

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.