/foundry:drift-sweep

An operator/agent ADVISORY sweep that names the whole batch of frozen atoms a schema/module migration just invalidated, instead of letting each one be rediscovered one at a time, weeks apart, at its own build. It is the batch-level, schema-coherence analogue of /foundry:coherence-check (which covers citations): same advisory posture, same tri-state fail-closed exit, same fresh-walk-every-run discipline — the missing dimension is schema identifiers instead of citations.

DORMANT: the engine below (scripts/foundry_drift_sweep.py) does not ship — the command is design intent for a re-implementation, not a runnable verb today.

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/foundry_drift_sweep.py" \
  --base  /path/to/base-snapshot.json \
  --head  /path/to/head-snapshot.json \
  --corpus-root "$CLAUDE_PROJECT_DIR"      # default: $CLAUDE_PROJECT_DIR or cwd

Input — a base->head snapshot PAIR (host-side, HOW obtained is a wiring concern)

The sweep takes two already-built snapshots from the system-state snapshot tool (foundry_system_snapshot.build_system_snapshot() results — {schema_version, schema_grounded, module_grounded, grounding_configured, entities, modules, signature}) as JSON files. It opens no grounding source itself and does no git plumbing — how the caller obtains the base (pre-migration) and head (post-migration) snapshots (e.g. re-resolving the same grounding block at two different migration-history points) is an operational wiring concern, not this sweep's.

What counts as a candidate (schema-delta vocabulary)

A dropped/renamed candidate identifier is one present in the base snapshot and absent from the head snapshot, over the grounded dimensions:

• table — a base entities key absent from head.
• column — a base <entity>::<column> absent from head.
• module — a base modules member absent from head.

A RENAME is observed as a drop of the old identifier — the new name appears as an addition, which is never a candidate (only disappearances are). An identifier present in both, or added only in head, is never a candidate.

The back-reference scan

For each candidate identifier, the sweep scans every AUTHORIZED contract in the corpus (AUTHORIZED per foundry_authz) for that identifier:

1. Primary — the system_grounding block (written by the system_grounding validators): a whole-string match against each artifact's identifier.
2. Fallback — the spec body, when an AUTHORIZED atom carries no system_grounding block (it predates the block): a whole-identifier-token grep — the candidate must be bounded by a non-identifier character (or start/end of text) on both sides over the identifier class [A-Za-z0-9_.:]. Candidate vehicle matches the token vehicle but never vehicles (suffix continuation), vehicle_parts (suffix continuation), or dealer_vehicle (prefix continuation) — a partial overlap is not a hit.

DRAFT (non-AUTHORIZED) atoms are always excluded, even when they reference the identifier.

Output — a worklist naming EVERY affected atom (deterministic JSON on stdout)

{
  "provenance":  {"corpus_root": "/abs/root", "source": "fresh-walk", "error": null},
  "candidates":  ["public.vehicles", "public.vehicles::vin", ...],   // sorted
  "drift_suspects": [
    {"spec_ref": "specs/features/.../feat-x.md", "identifier": "public.vehicles",
     "hit_via": "system_grounding"}
  ],
  "counts": {"candidates": N, "drift_suspects": M}
}

drift_suspects entries are the pinned field set {spec_ref, identifier, hit_via} — hit_via ∈ {"system_grounding", "spec_body"} — sorted ascending by (spec_ref, identifier). A single sweep lists every affected atom, not one at a time.

Tri-state, fail-CLOSED exit (LOAD-BEARING)

• 0 — ran, zero drift-suspects.
• 1 — ran, ≥1 drift-suspect. This is ADVISORY only — a worklist / re-audit nudge, never a veto.
• 2 — operational failure: a malformed/unreadable snapshot input, a missing/mis-resolved corpus root, or the corpus walk raising — including an unreadable/corrupt AUTHORIZED contract encountered mid-walk. A scan error is a HARD stop, never a silent skip to a partial 0/1 worklist.

Unconfigured no-op

When either snapshot has grounding_configured: false (no schema surface to diff) the sweep emits zero drift-suspects and exits 0 — never a false signal for an adopter with no schema source configured. This holds for both asymmetric permutations (base configured / head not, and vice-versa).

Venue boundary — ADVISORY, NOT a merge gate

This sweep is NOT part of the merge floor:

• It does NOT run as part of the merge floor (.github/workflows/ci.yml + btb-gates — the bespoke foundry-merge-gate.py this line originally named was retired; the boundary principle carries over to whatever embodies the floor).
• It is NOT a branch-protection required status.
• It emits a signal / re-audit nudge — it does NOT rewrite frozen specs or re-authorize them (that disposition is the operator's, via re-audit).

The enforcement floors live elsewhere in the reality-grounding gate: the review-time grounding-reconciliation check catches the divergence at each atom's own review; the merge-time grounding-reconciliation check, foundry_reconcile.py) was designed to reconcile mechanical drift at each atom's own merge, but its original call site — the deleted bespoke merge gate — no longer exists, and it is not currently wired into ci.yml/btb-gates (a sweep finding, flagged honestly here, not fixed in this pass). This atom is the batch early warning at migration-merge time regardless: a single sweep names the whole affected batch instead of waiting weeks for each to be rediscovered independently.

Anti-patterns

• Promoting exit 1 into a required merge status. It is advisory by contract; do not wire this sweep into the merge floor (ci.yml + btb-gates) or a branch-protection required check.
• Treating a mid-walk read/parse error as a partial 0/1. An unreadable/corrupt AUTHORIZED contract hit during the walk is a hard stop (exit 2), never a silent skip.
• Substring matching in the spec-body fallback. The match is a whole-identifier token (\b-style, over [A-Za-z0-9_.:]) — a partial overlap (vehicles for vehicle) is never a hit.
• Opening a grounding source or doing git plumbing inside the engine. The sweep is host-side, snapshot-pair-in; obtaining the base/head pair is the caller's wiring concern.