[#1052 B] Stub-freeze drift guard for ring-0 caller stubs (blocked on #1253)

[don-petry]

Split 3 of 4 of #1052 (channel-skew prevention). Part B — stub-freeze drift guard. Backstops Part A for the specific self-host caller stubs.

Blocked on Part A (#1253): this part also wires a job into .github/workflows/lint.yml. Implement it after #1253 merges so it rebases cleanly on A's lint.yml (avoids an add/add conflict). The dev-lead label is intentionally withheld until then.

Deliverable

• Treat the ring-0 caller stubs' trigger/with: forwarding blocks like the template stubs — reuse the ALIGNED/DRIFTED byte-identity model from scripts/template_stub_drift.sh / scripts/fleet_stub_drift.sh: the forwarding block must match a committed baseline (tests/fixtures/caller-stub-freeze/*.block), so any edit fails CI unless it is an intentional, reviewed channel change.
• scripts/caller_stub_freeze.sh + bats (tests/caller_stub_freeze.bats).
• Wire as a job in .github/workflows/lint.yml.

Acceptance

• Editing a frozen stub's forwarding block fails CI; an intentional baseline update passes. shellcheck clean; existing suites green.

Parent: #1052.

[don-petry]

Released. Part A (#1253) merged in PR #1257 at 06:09Z — its lint.yml validate-caller-inputs job is now on main, so this Part B (stub-freeze drift guard) will rebase cleanly on top. Flipped dev-lead:hands-off → dev-lead to implement. Part D (#1256) stays held until this merges.

[don-petry]

Dev-Lead Implementation Plan

Issue: #1255 — [#1052 B] Stub-freeze drift guard for ring-0 caller stubs (blocked on #1253)

Scope

Add a byte-identity freeze guard for the ring-0 / self-host caller stubs' trigger (on:) + uses:/with: forwarding blocks, backstopping the #1253 validate-caller-inputs check. Any edit to a frozen block fails CI unless the committed baseline is intentionally updated in the same reviewed diff.

Ring-0 / self-host stubs covered

• .github/workflows/dev-lead.yml (@dev-lead/v1-next)
• .github/workflows/pr-review-trigger.yml (@pr-review/next)
• .github/workflows/ci-failure-analyst.lock.yml (@ci-failure-analyst/v1-stable)

Implementation Checklist

• scripts/caller_stub_freeze.sh — reuse the ALIGNED/DRIFTED byte-identity model from scripts/fleet_stub_drift.sh (classify_stub_drift/stub_drift_row). Pure helpers: extract_forwarding_block, blob-SHA compare vs baseline, caller_freeze_annotate; CLI main (check) + --update (regenerate baselines).
• tests/fixtures/caller-stub-freeze/*.block — committed frozen baselines (one per stub), generated from the current stubs.
• .github/workflows/lint.yml — add a caller-stub-freeze job (PR-triggered on the existing Lint workflow, no new cron) and add tests/caller_stub_freeze.bats to the bats job list.

Tests to Write (tests/caller_stub_freeze.bats)

• classify_stub_drift reused: identical block → ALIGNED; edited block → DRIFTED; missing → MISSING.
• extract_forwarding_block yields the on: + uses:/with: region only (no leaked comments/blanks).
• caller_freeze_annotate: DRIFTED emits ::error:: naming both SHAs and fails; all-ALIGNED passes; MISSING warns only.
• Live regression: each real stub's extracted block is byte-identical to its committed .block baseline (ALIGNED).
• Acceptance: editing a frozen block fails; regenerating the baseline (--update) passes.

Test Command

scripts/run-bats.sh tests/caller_stub_freeze.bats (full suite via lint.yml bats job); lint via bash .dev-lead/scripts/dev-lead-lint.sh + shellcheck --severity=warning -x scripts/caller_stub_freeze.sh

[don-petry]

Dev-Lead: Implementation Complete

Plan Execution

• scripts/caller_stub_freeze.sh — freezes each ring-0/self-host caller stub's on: trigger + uses:/with: forwarding block against a committed baseline, reusing the ALIGNED/DRIFTED byte-identity model from scripts/fleet_stub_drift.sh (classify_stub_drift/stub_drift_row). Pure helpers (extract_forwarding_block, caller_freeze_current_sha, caller_freeze_baseline_sha, caller_freeze_annotate, caller_freeze_build_tsv) + CLI main with --check (default) and --update (regenerate baselines).
• tests/fixtures/caller-stub-freeze/{dev-lead,pr-review-trigger,ci-failure-analyst}.block — committed frozen baselines generated from the current stubs.
• .github/workflows/lint.yml — added the caller-stub-freeze job (PR-triggered on the existing Lint workflow, no new cron) and added tests/caller_stub_freeze.bats to the bats job list.
• AGENTS.md — documented the job as a repo-specific exception (sibling to Part A's validate-caller-inputs) so template syncs don't remove it.

Stubs frozen (ring-0 / self-host, channel-pinned)

• .github/workflows/dev-lead.yml — @dev-lead/v1-next
• .github/workflows/pr-review-trigger.yml — @pr-review/next
• .github/workflows/ci-failure-analyst.lock.yml — @ci-failure-analyst/v1-stable

Test Results

$ bats tests/caller_stub_freeze.bats
1..15
ok 1 classify_stub_drift is available (sourced from fleet_stub_drift.sh)
ok 2 caller stub set: a byte-identical block is ALIGNED
ok 3 caller stub set: an edited forwarding block is DRIFTED
ok 4 caller stub set: a missing/empty block is MISSING
ok 5 covered set: lists the three ring-0 self-host caller stubs
ok 6 extract: dev-lead block has the on trigger, the channel-pinned uses, and with
ok 7 extract: pr-review-trigger keeps the with-forwarding but drops the permissions header comment
ok 8 extract: ci-failure-analyst (no with) yields just the on block and the channel-pinned uses
ok 9 annotate: a DRIFTED row emits a ::error:: naming the stub and both SHAs, and fails
ok 10 annotate: an all-ALIGNED set passes (exit 0, no error annotation)
ok 11 annotate: an absent TSV passes (nothing to check)
ok 12 annotate: MISSING alone does not fail the job (only DRIFTED fails)
ok 13 stub_drift_row: classifies a drifted caller stub into a 4-field TSV row
ok 14 live: every ring-0 caller stub is ALIGNED with its committed baseline
ok 15 acceptance: editing a frozen block fails, regenerating the baseline passes

$ bash scripts/caller_stub_freeze.sh
Ring-0 caller-stub freeze check — forwarding blocks vs committed baselines:
.github/workflows/dev-lead.yml            ALIGNED  102a21a…  102a21a…
.github/workflows/pr-review-trigger.yml   ALIGNED  14797ef…  14797ef…
.github/workflows/ci-failure-analyst.lock.yml  ALIGNED  00834b7…  00834b7…

$ shellcheck --severity=warning -x scripts/caller_stub_freeze.sh   # clean
$ bash .dev-lead/scripts/dev-lead-lint.sh                          # [lint] all checks passed
$ bats tests/fleet_stub_drift.bats tests/template_stub_drift.bats tests/caller_stub_freeze.bats  # 45/45 ok

Files Changed

• scripts/caller_stub_freeze.sh (new): the freeze guard.
• tests/caller_stub_freeze.bats (new): 15 tests incl. the acceptance case (edit fails, baseline update passes) and a live ALIGNED regression.
• tests/fixtures/caller-stub-freeze/*.block (new): 3 committed baselines.
• .github/workflows/lint.yml: new caller-stub-freeze job + test added to bats list.
• AGENTS.md: documented the new lint job.

Notes

• The guard is pure/local (git blob-SHA of the extracted block vs the committed baseline) — no network, no GH_TOKEN, no new scheduled workload.
• Acceptance met: editing a frozen forwarding block flips it DRIFTED and fails CI; scripts/caller_stub_freeze.sh --update regenerates the baseline so an intentional, reviewed channel change passes. shellcheck clean; existing drift suites green.
• ci-failure-analyst.lock.yml is a gh-aw compiled lock; its on:/uses: forwarding is frozen too, so a recompile that changes the channel/trigger surfaces as a reviewable baseline diff (consistent with the existing gh-aw-compile gate).