[product-manager-impersonator] Authoring contract lint for workflow docs/examples

[github-actions]

Feature Idea

Summary: Add a CI authoring-contract lint that keeps each workflow’s source (gh-aw-*.md), trigger example (example.yml), and per-workflow README inputs/safe-outputs in sync.

Why a Customer Would Want This

Maintainers and downstream adopters rely on workflow READMEs and examples to configure triggers correctly. When a workflow source adds/changes standard inputs or safe outputs but docs/examples drift, users copy incomplete config and only discover problems at runtime. A contract lint would catch this before merge and reduce onboarding/support churn.

Rough Implementation Sketch

• Add a script (for example scripts/check-workflow-authoring-contract.py) that validates, per workflow slug:
  • .github/workflows/gh-aw-<slug>.md exists and defines workflow_call.inputs + safe-outputs.
  • gh-agent-workflows/<slug>/example.yml references the matching gh-aw-<slug>.lock.yml@v0.
  • gh-agent-workflows/<slug>/README.md Inputs table includes standard inputs exposed by the source (with a small allowlist for intentionally hidden/internal inputs).
  • README Safe Outputs section matches source safe-output capabilities.
• Wire it into existing CI (.github/workflows/ci.yml) alongside check-nav-catalog.
• Document the lint in gh-agent-workflows/DEVELOPING.md and expose a make target for local execution.

Why It Won't Be That Hard

The repository already has lightweight consistency gates and patterns for this exact kind of check (scripts/check-nav-catalog.py + CI invocation), and workflow naming/layout is standardized (gh-aw-<name>.md plus gh-agent-workflows/<name>/...). This is mostly parsing and deterministic comparisons, with minimal surface area.

Evidence

• The maintainer workflow authoring process explicitly requires coordinating three files for every workflow: source, example trigger, and README (gh-agent-workflows/DEVELOPING.md lines 159-163).
• CI currently enforces compile/nav checks but not source↔README input/safe-output parity (.github/workflows/ci.yml lines 30, 36, 55).
• Concrete drift example today:
  • Source defines setup-commands for Internal Gemini CLI Web Search (.github/workflows/gh-aw-internal-gemini-cli-web-search.md line 35; setup step wiring at lines 97 and 99).
  • The corresponding README Inputs table omits setup-commands (gh-agent-workflows/internal-gemini-cli-web-search/README.md, Inputs section).
• Recent activity shows continued workflow reliability hardening (Add noop guardrails to detector workflows to guarantee safe-output emission #2032, Clarify Product Manager Impersonator final safe-output noop requirement #2015, Propagate dispatch failures in trigger CI script #2143, Fix trigger-ci-workflows exit code on dispatch failures #2128), so an authoring-contract lint aligns with current direction and should be a small iterative win.

---

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

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