Skip to content

feat(skills): wire drift check into every framework skill's pre-flight#41

Merged
potiuk merged 1 commit into
apache:mainfrom
potiuk:feat/skills-drift-check-pre-flight
May 4, 2026
Merged

feat(skills): wire drift check into every framework skill's pre-flight#41
potiuk merged 1 commit into
apache:mainfrom
potiuk:feat/skills-drift-check-pre-flight

Conversation

@potiuk

@potiuk potiuk commented May 4, 2026

Copy link
Copy Markdown
Member

Summary

Follow-up to #40. Wire the drift-detection mechanism into every framework skill's pre-flight, alongside the override-consultation hook from #39. Each of the 15 framework skills (excluding setup-steward, the bootstrap + drift mechanism itself) now carries a ## Snapshot drift section right after its existing ## Adopter overrides section.

Standard block inserted

## Snapshot drift

Also at the top of every run, this skill compares the
gitignored `.apache-steward.local.lock` (per-machine
fetch) against the committed `.apache-steward.lock`
(the project pin). On mismatch the skill surfaces the
gap and proposes
[`/setup-steward upgrade`](../setup-steward/upgrade.md).
The proposal is non-blocking — the user may defer if
they want to run with the local snapshot for now. See
[`docs/setup/install-recipes.md` § Subsequent runs and drift detection](../../../docs/setup/install-recipes.md#subsequent-runs-and-drift-detection)
for the full flow.

Drift severity:

- **method or URL differ** → ✗ full re-install needed.
- **ref differs** (project bumped tag, or `git-branch`
  local is behind upstream tip) → ⚠ sync needed.
- **`svn-zip` SHA-512 mismatches the committed
  anchor** → ✗ security-flagged; investigate before
  upgrading.

The block is identical across all 15 skills (the link target is the same — setup-steward/upgrade.md — for every skill).

Skills updated (15)

Setup family Security family PR-management family
setup-isolated-setup-install security-issue-import pr-management-code-review
setup-isolated-setup-update security-issue-import-from-md pr-management-stats
setup-isolated-setup-verify security-issue-import-from-pr pr-management-triage
setup-shared-config-sync security-issue-invalidate
security-issue-sync
security-cve-allocate
security-issue-deduplicate
security-issue-fix

Not updated: setup-steward — it IS the bootstrap + upgrade + verify + override-management skill; the drift check it would perform is the same one its verify sub-action already exposes.

Test plan

  • All prek run --all-files hooks pass (markdownlint, typos, doctoc, check-placeholders)
  • Every framework skill except setup-steward has the ## Snapshot drift section (visual grep — 15/15 covered)
  • Insertion point is consistent: directly after each skill's ## Adopter overrides block, before the next ## heading (Golden rules / Inputs / Prerequisites depending on the skill)
  • CI link-check (lychee) passes

Out of scope

  • Mechanical enforcement of the drift check (currently a documented convention, not a runtime injector). Future tooling — e.g. a sentinel pre-flight pre-commit hook on framework skill files — can verify each skill carries the section. Beyond this PR.

🤖 Generated with Claude Code

Mirror of apache#39's override-consultation hook for the new
drift-detection mechanism that landed in apache#40. Every framework
skill (excluding setup-steward, which IS the drift mechanism)
now declares a `## Snapshot drift` section right after its
`## Adopter overrides` section.

The standard block in every skill:

  ## Snapshot drift

  Also at the top of every run, this skill compares the
  gitignored `.apache-steward.local.lock` (per-machine
  fetch) against the committed `.apache-steward.lock` (the
  project pin). On mismatch the skill surfaces the gap and
  proposes [`/setup-steward upgrade`]. The proposal is
  non-blocking — the user may defer if they want to run with
  the local snapshot for now.

  Drift severity:
    - method or URL differ        → ✗ full re-install
    - ref differs                 → ⚠ sync needed
    - svn-zip SHA-512 mismatches  → ✗ security-flagged

15 skills updated:

  setup-isolated-setup-install         security-issue-import
  setup-isolated-setup-update          security-issue-import-from-md
  setup-isolated-setup-verify          security-issue-import-from-pr
  setup-shared-config-sync             security-issue-invalidate
                                        security-issue-sync
  pr-management-code-review            security-cve-allocate
  pr-management-stats                  security-issue-deduplicate
  pr-management-triage                 security-issue-fix

Skill not updated:

  setup-steward — IS the bootstrap + upgrade + verify +
  override-management skill; the drift check it would
  perform is the same one its `verify` sub-action exposes.

The hook is documented behaviour, not runtime injection. A
skill that has the `## Snapshot drift` section commits to
performing the check when invoked. Future tooling can enforce
mechanically; for now the convention is binding via the
published contract.

Generated-by: Claude Code (Claude Opus 4.7)
@potiuk potiuk merged commit 8c90b40 into apache:main May 4, 2026
6 checks passed
potiuk added a commit that referenced this pull request May 4, 2026
…to framework PR (#43)

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.

Walkthrough

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

Golden rules

1. Not every override should be upstreamed.
2. Write to the framework clone, never to the gitignored
   snapshot.
3. Assistant proposes, user fires (clone, branch, commit,
   push, PR — every state-changing action confirmed first).
4. Decouple PR open from override deletion (the cleanup
   happens AFTER the PR merges, not preemptively).

Includes the standard pre-flight blocks per the framework's
conventions:

- ## Adopter overrides — consults
  .apache-steward-overrides/setup-override-upstream.md
  (per #39).
- ## Snapshot drift — compares local lock vs committed
  lock (per #41), with a doubly-important note: the skill
  designs against the snapshot's framework code, so stale
  snapshot leads to wrong abstraction design.

Generated-by: Claude Code (Claude Opus 4.7)
@andreahlert andreahlert added the mode:platform Substrate / infra — not a mode (sandbox, CI, validators) label May 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

mode:platform Substrate / infra — not a mode (sandbox, CI, validators)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants