Story (D): full-file on:/permissions drift guard in compliance-audit [#604] #607

Activity

1. don-petry

   added

   dev-leadFor dev-lead agent pickupFor dev-lead agent pickup

   on Jul 13, 2026
2. don-petry commented on Jul 13, 2026

   

   don-petry

   on Jul 13, 2026

   ContributorAuthor

   More actions

   Dev-Lead Implementation Plan

   Issue: #607 — Story (D): full-file on:/permissions drift guard in compliance-audit [#604]

   Scope

   Add a tier-normalized surface-drift guard to compliance-audit.sh that flags a dev-lead / RING caller stub whose on: triggers, permissions: grants, or (per-stub) concurrency: block have drifted from the canonical standards/workflows/<name>.yml, while never flagging a stub that differs only by its correct tier channel pin.

   Design notes

   • The three guarded surfaces (on:, permissions:, concurrency:) carry no channel pin — the tier pin lives only on the jobs.<id>.uses / agent_ref lines (already guarded by check_centralized_workflow_stubs / check_dev_lead_stub). So the surface comparison is tier-invariant by construction: a stub differing only by its correct tier pin has identical surfaces → not flagged (AC2). This is the "explicit sub-checks" branch Story (D): full-file on:/permissions drift guard in compliance-audit [#604] #607 authorizes, chosen over a full-file byte guard because agent-shield / feature-ideation document legitimate per-repo with: liberties (and feature-ideation a per-repo cron) that a byte guard would false-positive on.
   • feature-ideation's legit per-repo cron retune is tolerated by normalizing - cron: values before comparison; a trimmed trigger still drifts.
   • To avoid duplicate findings, dev-lead's existing dedicated permissions (statuses: read) and concurrency checks in check_dev_lead_stub stay as-is; the new check owns dev-lead's previously-unguarded on: surface plus all three surfaces for the 8 RING shims (whose permissions:/concurrency: were entirely unguarded).

   Implementation Checklist

   • Add pure helpers to scripts/compliance-audit.sh: stub_extract_blocks, stub_normalize_surface, stub_surface_drift
   • Add check_stub_surface_drift(repo) (reads canonical from standards/workflows/, deployed via gh API) + STANDARDS_WF_DIR
   • Wire check_stub_surface_drift "$repo" into the per-repo driver loop

   Tests to Write

   • test/scripts/compliance-audit/stub-surface-drift.bats exercising the real pure helpers:
     • trimmed trigger (removed on: event / narrowed types) → flagged
     • added permission → flagged; removed permission → flagged
     • injected per-stub concurrency: → flagged
     • correctly-tiered stub (differs only by tier channel pin) → clean
     • feature-ideation cron retune → clean; canonical concurrency: retained → clean

   Test Command

   node_modules/.bin/bats test/scripts/compliance-audit/ (CI: bats test/scripts/compliance-audit/)
3. don-petry commented on Jul 13, 2026

   

   don-petry

   on Jul 13, 2026

   ContributorAuthor

   More actions

   ✅ Issue #607 — full-file on:/permissions drift guard in compliance-audit

   Implemented the tier-normalized surface-drift guard for the centralized caller stubs (dev-lead + all RING shims). Chose the explicit sub-checks branch of the two authorized options: guard the three tier-invariant surfaces (on:, permissions:, concurrency:) rather than a full-file byte guard — a byte guard would false-positive on the documented per-repo with: liberties (agent-shield, feature-ideation) and feature-ideation's documented per-repo cron retune. Because those three surfaces carry no channel pin, the comparison is tier-invariant by construction, which satisfies AC2 automatically.

   Changes

   • scripts/compliance-audit.sh
     • STANDARDS_WF_DIR — points the guard at the on-disk canonical templates in standards/workflows/.
     • Three pure, unit-tested helpers (org standard "decision logic lives in a pure, tested script"):
       • stub_extract_blocks <content> <key> — awk indentation extractor; captures every block for a key at any depth (so dev-lead's top-level permissions: {} + job-level permissions: are both compared), never treats a # concurrency: comment as the key.
       • stub_normalize_surface — strips comments/blank lines and collapses schedule cron: values (so a legitimate per-repo cron retune is not flagged).
       • stub_surface_drift <canonical> <deployed> <key> — success-means-drift (returns 0 on drift, 1 on clean).
     • check_stub_surface_drift <repo> — for each enrolled shim, re-derives the canonical surface and compares against the deployed stub via the contents API. Skips .github (source of truth) and .github-private (runs inline). dev-lead's permissions/concurrency already have dedicated higher-signal checks in check_dev_lead_stub(), so this check owns dev-lead's previously-unguarded on: only, plus all three surfaces for the 8 RING shims. on:/permissions: drift → error; concurrency: → warning. Shim list is in lockstep with RING_REUSABLES in lib/ring-pins.sh.
     • Wired into the driver loop after check_dev_lead_stub.
   • test/scripts/compliance-audit/stub-surface-drift.bats (new, 16 tests) — AC1 (trimmed trigger / narrowed types / dropped discussion → flagged), AC2 (ring1-repinned stub clean on every surface), permissions add/remove flagged, dev-lead statuses: read removal flagged, concurrency injection flagged, feature-ideation canonical concurrency retained clean / changed flagged, cron retune NOT flagged, plus stub_extract_blocks multi-block / absent-key / comment-not-key coverage.

   Acceptance

   • AC1 — a dev-lead.yml (or any RING shim) with a trimmed on: block is flagged ✔ (tests 118–120)
   • AC2 — a stub differing from canonical only by its correct tier channel pin is not flagged ✔ (tests 115–117)

   Verification

   • bats test/scripts/compliance-audit/ → 130 / 130 pass (16 new)
   • shellcheck --severity=warning -x scripts/compliance-audit.sh → clean
   • bash .dev-lead/scripts/dev-lead-lint.sh → all checks passed

   No commit/push/PR performed — leaving git operations to CI.
4. don-petry

   added a commit that references this issue on Jul 13, 2026

   feat: implement issue #607 — Story (D): full-file on:/permissions dri…

   ...

   83926b1
5. don-petry

   closed this as completedin #692on Jul 13, 2026
6. don-petry

   added a commit that references this issue on Aug 7, 2026

   feat: implement issue #607 — Story (D): full-file on:/permissions dri…

   ...

   d1cf9b1