molecule-core/.gitea/workflows/lint-mask-pr-atomicity.yml

name: lint-mask-pr-atomicity

# Tier 2d hard-gate lint (per mc#1982) — blocks PRs that touch
# `.gitea/workflows/ci.yml` and modify ONLY ONE of {continue-on-error,
# all-required.sentinel.needs} without a `Paired: #NNN` reference in
# the PR body or in a commit message.
#
# Why this exists
# ---------------
# PR#665 (interim `continue-on-error: true` on `platform-build`) and
# PR#668 (sentinel-`needs` demotion of the same job) were designed as a
# pair but merged solo — #665 landed at 04:47Z 2026-05-12, #668 was
# still open at 05:07Z when the main-red watchdog (#674) fired. Result:
# ~20 minutes of `main` red and a cascade of false-positives on
# unrelated PRs. This lint structurally prevents that class.
#
# How the gate works
# ------------------
# 1. The workflow runs on every PR whose diff touches ci.yml (paths
#    filter). It is NOT a required check on `main` because the rule is
#    diff-based — running it on PRs that don't touch ci.yml would
#    produce a `pending` status forever (per
#    `feedback_path_filtered_workflow_cant_be_required`).
# 2. The script reads `BASE_SHA:ci.yml` and `HEAD_SHA:ci.yml`, parses
#    both via PyYAML AST (per `feedback_behavior_based_ast_gates` — no
#    grep, no regex on the raw text — so a YAML-shape refactor still
#    detects).
# 3. Walks `jobs.*.continue-on-error` on each side; flags any value
#    diff. Reads `jobs.all-required.needs` on each side; flags any
#    set diff (order-insensitive — `needs:` is engine-unordered).
# 4. If both predicates fired → atomic, OK. If neither → no risk, OK.
#    If exactly one fired → require `Paired: #NNN` in PR body OR in
#    any commit message between base..head; else fail.
#
# Phase contract (RFC internal#219 §1 ladder)
# -------------------------------------------
# This workflow lands at `continue-on-error: true` (Phase 3 — surface
# regressions without blocking PRs while the rule beds in).
# Follow-up PR flips to `false` once we have ≥3 days of clean runs on
# `main` and no false-positives. Tracking issue: mc#1982.
#
# Cross-links
# -----------
# - mc#1982 (the RFC that specs this lint)
# - PR#665 / PR#668 (the empirical split-pair)
# - mc#1982 (the main-red incident the split caused)
# - feedback_strict_root_only_after_class_a
# - feedback_behavior_based_ast_gates
#
# Auth: only needs the auto-injected GITHUB_TOKEN (read-only, repo
# scope). No DRIFT_BOT_TOKEN needed — Tier 2d does NOT call
# branch_protections (Tier 2g/f do).

on:
  pull_request:
    types: [opened, synchronize, reopened, edited]
    # `edited` is included because the rule depends on PR_BODY: a user
    # may add `Paired: #NNN` after first push to satisfy the lint. The
    # rerun on `edited` lets the PR turn green without an empty
    # commit. The repository webhook contract includes `edited` for body
    # changes; the original behavior was source-verified during the 1.22.6 era.
    paths:
      - '.gitea/workflows/ci.yml'
      - '.gitea/scripts/lint_mask_pr_atomicity.py'
      - '.gitea/workflows/lint-mask-pr-atomicity.yml'
      - 'tests/test_lint_mask_pr_atomicity.py'

env:
  # Belt-and-suspenders against the runner-default trap
  # (feedback_act_runner_github_server_url). Runners are configured
  # with this env in runner configuration, but pinning it at the workflow
  # level protects against a runner regenerated without that setting.
  GITHUB_SERVER_URL: https://git.moleculesai.app

permissions:
  contents: read
  pull-requests: read

# Per-PR concurrency — re-pushes cancel previous runs to keep the
# queue short. The lint is cheap (one git show + log + a YAML parse).
concurrency:
  group: lint-mask-pr-atomicity-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

jobs:
  # bp-exempt: meta-lint advisory during mask burn-down; CI / all-required gates merges.
  scan:
    name: lint-mask-pr-atomicity
    runs-on: ubuntu-latest
    timeout-minutes: 5
    # UNMASKED 2026-09-03. Was `continue-on-error: true` under tracker mc#4959.
    #
    # The mask's only stated justification was the pre-flip catch-22 of mc#4344:
    # this workflow is paths-filtered, so it never fires on a push to main, and
    # lint_pre_flip_continue_on_error.py accepted main-PUSH run logs as the only
    # proof that a flip is safe. That gate was fixed on 2026-07-20 by fb426286
    # ("pre-flip gate paginates statuses + accepts PR evidence for paths-filtered
    # workflows"), whose body names this workflow and mc#4344 and states it
    # "unblocks core#4521 (mask-elimination)". The blocker was therefore already
    # gone when mc#4959 renewed the mask on 2026-07-30; that renewal restated it
    # without re-checking, and the same text had been carried forward through
    # mc#774 -> mc#1982 -> mc#2654 -> mc#3436 -> mc#4344 -> mc#4959.
    #
    # Evidence behind the flip (governance review, 2026-09-03):
    #   - 45 runs of this workflow in the sampled window (2026-08-10..2026-09-03).
    #     The job is green in every completed run but one.
    #   - The exception, run 652757 (PR #5168 @cb5265ff), is not a lint verdict:
    #     that PR's ci.yml diff changes neither `continue-on-error` nor
    #     `all-required.needs`, so both predicates are false and the script
    #     returns 0. The job died in its own setup and its log has since been
    #     garbage-collected.
    #   - The mask was not suppressing what it was renewed to suppress. With it
    #     in place, run 652757 still posted the commit status
    #     `lint-mask-pr-atomicity / lint-mask-pr-atomicity (pull_request)
    #     = failure`, exactly as `publish-canvas-image / Build & push canvas
    #     image (push)` posted `failure` on 2026-07-18 (recorded in mc#4391).
    #     Job-level continue-on-error does not suppress the posted context on
    #     this Gitea, so the mask bought a 14-day renewal treadmill and no
    #     actual masking.
    #
    # No tracker comment belongs here now: with no truthy `continue-on-error`,
    # Tier 2e has nothing to require.
    continue-on-error: false
    steps:
      - name: Check out PR head with full history (need base SHA blobs)
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
        with:
          # `git show <base-sha>:<path>` needs the base SHA's blobs.
          # Shallow=1 would miss it. Same rationale as PR#673 and
          # check-migration-collisions.yml.
          fetch-depth: 0
      - name: Set up Python (PyYAML for AST parsing)
        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5.6.0
        with:
          python-version: '3.12'
      - name: Install PyYAML
        # Same pin as ci-required-drift.yml + the rest of the Tier 2
        # lint family — keep runner-cache hits uniform.
        run: python -m pip install --quiet 'PyYAML==6.0.2'
      - name: Ensure base ref is reachable locally
        # fetch-depth=0 usually pulls the base too, but explicit-fetch
        # is cheap insurance against runner-version drift (matches the
        # comment in check-migration-collisions.yml and PR#673).
        run: |
          git fetch origin "${{ github.event.pull_request.base.ref }}" || true
      - name: Run lint-mask-pr-atomicity
        env:
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          # PR body — the script greps for `Paired: #NNN`.
          PR_BODY: ${{ github.event.pull_request.body }}
          CI_WORKFLOW_PATH: .gitea/workflows/ci.yml
          SENTINEL_JOB_KEY: all-required
        run: python3 .gitea/scripts/lint_mask_pr_atomicity.py
      - name: Run lint-mask-pr-atomicity unit tests
        # Run the test suite in-CI so the lint's own behaviour is
        # verified on every change. Matches lint-workflow-yaml.yml.
        run: |
          python -m pip install --quiet pytest
          python3 -m pytest tests/test_lint_mask_pr_atomicity.py -v