potiuk opened a new pull request, #40: URL: https://github.com/apache/airflow-steward/pull/40
## Summary Rewrite `setup-steward` to support **three install methods**, split the lock file into **committed (project pin) + local (per-machine fetch)**, and drive every framework-skill invocation through a **drift check** that compares the two locks. This is the design step that makes apache-steward behave like a proper distribution-aware framework: a project commits one pin, every contributor's machine fetches against it, drift is detected and remediated automatically. ## Three install methods (copy-pasteable in `docs/setup/install-recipes.md`) | Method | When | Reproducibility | |---|---|---| | **`svn-zip`** | Signed zip from ASF dist (`https://dist.apache.org/repos/dist/release/<project>/`) — the canonical ASF release distribution path per [release-policy](https://www.apache.org/legal/release-policy.html) and [infra release-distribution guidelines](https://infra.apache.org/release-distribution.html). Verified via SHA-512 + optional OpenPGP. Recommended for production once the framework ships official releases. | Frozen by version | | **`git-tag`** | Pinned to a specific git tag. | Frozen by tag | | **`git-branch`** (default `main`) | Tracks a branch tip — the WIP path during the framework's pre-release phase. | Tracks tip | Each recipe is one shell block that adds gitignore entries, downloads + verifies + extracts the framework into `.apache-steward/`, copies the bootstrap skill into the adopter's skills dir (matching flat or double-symlinked convention), and tells the user to follow `/setup-steward` from there. ## Lock-file split | File | Tracked? | Records | |---|---|---| | `.apache-steward.lock` | **committed** | The project's pin: `method`, `url`, `ref`, plus a verification anchor (`commit` for tag, `sha512` for zip). Edited only by `/setup-steward`; bumping it is a deliberate project-level commit visible in PR diffs. | | `.apache-steward.local.lock` | **gitignored** | What THIS machine fetched: `source_method`, `source_url`, `source_ref`, `fetched_commit`, `fetched_at`. Per-developer, per-checkout. | ## Drift detection Every framework skill (and `/setup-steward verify`) compares the local lock to the committed lock at the top of its run. | Drift | Severity | Remediation | |---|---|---| | Method or URL differ | ✗ | `/setup-steward upgrade` (full re-install) | | Ref differs (project bumped tag, or `git-branch` local behind upstream tip) | ⚠ | `/setup-steward upgrade` (sync) | | `svn-zip` SHA-512 differs from committed anchor | ✗ | Investigate before upgrading — the released zip changed under the same version | `upgrade` deletes the gitignored snapshot outright, re-installs per the committed lock, refreshes the gitignored framework-skill symlinks (adds newly-added framework skills, removes renamed-away ones), and reconciles agentic overrides against the new framework structure (surfaces conflicts; never auto-rewrites). ## Changes - Rewrite `.claude/skills/setup-steward/{SKILL,adopt,upgrade,verify}.md` to express the new model. - New: `docs/setup/install-recipes.md` with the three copy-pasteable recipes + explanatory framing (when to use each, what each step does, what the skill takes over post-recipe). - README's "Adopting the framework" section split into **Bootstrap** (the shell recipe) → **Skill takeover** (the interactive part `/setup-steward` does) → **Subsequent contributors** (read the committed lock + reinstall) → **Drift detection** (the run-time mechanism). ## Test plan - [x] All `prek run --all-files` hooks pass (markdownlint, typos, doctoc, check-placeholders) - [x] `setup-steward` re-registers in Claude Code's available-skills list (live discovery picked up the rewrite in-session) - [x] `docs/setup/install-recipes.md` recipes are syntactically valid bash (each is a single fenced block, no obvious shell errors) - [ ] Reviewer copies a recipe verbatim into a scratch repo and confirms it runs cleanly through "snapshot on disk + setup-steward in skills dir" - [ ] Reviewer eyeballs the committed-vs-local lock model for security gaps (especially around the SHA-512 mismatch flow) - [ ] CI link-check (lychee) passes ## Out of scope (follow-up PR) Wire the drift check into each framework skill's pre-flight section, alongside the override-consultation hook from #39. 15 skills to touch; mechanical change, deferred to keep this PR focused on the mechanism design rather than the rollout. 🤖 Generated with [Claude Code](https://claude.com/claude-code) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
