feat(setup-steward): multi-install + committed/local lock split + drift detection

[potiuk]

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 and infra release-distribution guidelines. 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

• All prek run --all-files hooks pass (markdownlint, typos, doctoc, check-placeholders)
• setup-steward re-registers in Claude Code's available-skills list (live discovery picked up the rewrite in-session)
• 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