feat(skills): add setup-override-upstream — promote local override into framework PR

[potiuk]

Summary

New framework skill that walks an adopter through promoting a local .apache-steward-overrides/<skill>.md file into a PR against apache/airflow-steward. Closes the loop on the override mechanism: overrides start out as adopter-local modifications (per #38, #39), and when one stops being project-specific and starts looking like a missing feature, this skill is the path to upstream it.

What the skill does

Step	What
0	Pre-flight: adopter has overrides + snapshot is current + framework clone available
1	Pick the override (auto-pick when only one; prompt when multiple)
2	Read the override + the framework skill it modifies (from the snapshot)
3	Decide if upstreamable — four buckets: project-specific (stop), missing feature (continue), better default (continue), refactor a step (continue)
4	Design the framework-level abstraction — four possible shapes: add a config knob, change a default, add an optional step, refactor an existing step
5	Implement in the user's apache/airflow-steward clone, run framework pre-commit
6	Confirm + open the PR (assistant proposes, user fires)
7	Surface post-merge cleanup pointer: once the PR merges + /setup-steward upgrade lands, delete the override file in the adopter repo

Golden rules

1. Not every override should be upstreamed. Project-specific overrides (canned-response wording, scope-label taxonomy, milestone-format regex) should stay local. The skill walks through the decision and stops early when the change isn't generalisable.
2. Write to the framework clone, never to the gitignored snapshot. The PR is implemented in a separate apache-steward clone (the one the user contributes to). The snapshot under .apache-steward/ is a build artefact and stays untouched.
3. Assistant proposes, user fires. Every state-changing action (clone, branch, commit, push, gh pr create) is proposed first and only happens on explicit confirmation.
4. Decouple PR-open from override-deletion. Opening the framework PR is one step; deleting the now-redundant override file is a separate step that happens AFTER the PR merges AND the adopter has run /setup-steward upgrade. The skill prints the cleanup pointer at the end; it does not delete preemptively.

Standard pre-flight blocks

The skill includes both standard pre-flight sections per the framework's conventions:

• ## Adopter overrides (per feat(skills): hook every framework skill into override-consultation protocol #39) — consults .apache-steward-overrides/setup-override-upstream.md if it exists, applies any agent-readable instructions.
• ## Snapshot drift (per feat(skills): wire drift check into every framework skill's pre-flight #41) — compares local lock vs committed lock; doubly important here, because this skill designs the framework-level abstraction against the snapshot's current state. Stale snapshot → wrong abstraction. The block calls this out explicitly.

Test plan

• Skill registers in Claude Code's available-skills list (live discovery picked up the new file in-session)
• All prek run --all-files hooks pass (markdownlint, typos, doctoc, check-placeholders)
• Cross-references to setup-steward/overrides.md, setup-steward/upgrade.md, docs/setup/agentic-overrides.md resolve
• Reviewer eyeballs the four-bucket decision in Step 3 — captures the right "stop" cases (project-specific) vs "continue" (missing feature, better default, refactor)
• Reviewer eyeballs the four shapes in Step 4 — captures the canonical framework-level abstraction patterns
• CI link-check (lychee) passes

🤖 Generated with Claude Code