molecule-core/.gitea/workflows/lint-phantom-gate.yml

# lint-phantom-gate — Guard F (regression-prevention-guards.md §Guard F),
# plus Guard G (disabled PR emitters) and Guard S (skippable enforced gates).
#
# The three answer three different ways an ENFORCED required context stops
# being a gate while the board still reads green:
#   Guard F — its producer WORKFLOW is toggled off, so it never posts.
#   Guard G — a DISABLED workflow still fires on PR events, posting statuses
#             that cannot be rerun (wedge).
#   Guard S — its producer JOB is gone, or the job can be `skipped` because
#             something in its `needs:` closure carries a job-level `if:`.
#             `["*"]` branch protection treats `skipped` as PASSING.
#
# The META-guard that guards the gates. A `.gitea/required-contexts.txt` entry
# declared ENFORCED (merge-blocking) whose PRODUCER workflow is toggled off
# (`disabled_manually` / `disabled`) is a PHANTOM GATE: under the `[*]` all-green
# branch protection the disabled workflow never posts its status, so the gate is
# required-on-paper but silently enforces NOTHING. This is the blind spot that
# let the mgmt-MCP / provision regressions reach prod uncaught (the enforced
# `E2E Staging SaaS ... Concierge Creates Workspace` gate's producer had been
# disabled since the 2026-06-27 AWS toggle-off).
#
# This lint reads the SAME enforced set the merge queue enforces
# (`load_enforced_file_contexts`, everything above the first `# pending-#NNNN`
# marker) and, for each entry, asserts its producer workflow's Gitea Actions
# state is `active`. It FAILS RED on a phantom.
#
# TRIGGERS — PROMOTED to a PR-time gate (regression-prevention-guards.md + #3467):
#   - `pull_request` — the promotion. Under the `[*]` all-green branch protection
#     a red status on the PR head blocks the merge, so running Guard F on PRs
#     makes a phantom (an ENFORCED required-context whose producer is disabled /
#     missing) RED-BLOCK the PR BEFORE it lands, instead of only being detected
#     post-merge on push:[main]. This was gated behind "phantom must be resolved
#     first" (a live phantom would RED-block every open PR = repo-wide wedge);
#     that precondition now HOLDS — e2e-staging-saas was re-enabled (Guard B /
#     #3464 landed, task #231/#232) so all ENFORCED producers are `active` and
#     Guard F is GREEN on main. It is safe to run on every relevant PR because it
#     PASSES on a clean main and only goes red on a REAL phantom — which SHOULD
#     block merges until the producer is re-enabled or the context is parked
#     below a `# pending-#NNNN` marker. Scoped with `paths:` to the files that
#     can INTRODUCE a phantom in a PR diff (required-contexts.txt SSOT, any
#     workflow file, the detector script, this test) so it does not run on every
#     unrelated PR; the out-of-band "producer toggled off via the Actions API"
#     case (not a file change) stays covered by the push:[main] detector below.
#   - `push: [main]` — regression detector on the branch where a workflow
#     toggle-off actually lands. A red on main is TRUE signal surfaced to
#     main-red-watchdog.
#   - `workflow_dispatch` — on-demand audit.
#
# NOT-A-WEDGE contract: Guard F is NOT listed in `.gitea/required-contexts.txt`
# and NOT an individual BP context, so the merge queue never WAITS for it; under
# `[*]` only POSTED statuses are required, so a `paths`-skipped PR (no status
# posted) is not blocked. A green Guard F is the common case; a red one is a real
# phantom that SHOULD hold the queue. (The `bp-required: pending #3467` directive
# stays `pending` — the literal context can never be individually listed while BP
# is the `[*]` wildcard; the wildcard itself provides the enforcement.)
#
# FAIL-BEFORE proof (verified live, HTTPS = CI path): flags
# `E2E Staging SaaS (full lifecycle) / E2E Staging Concierge Creates Workspace`
# (producer disabled_manually) RED while the re-enabled hermetic gate PASSES.
# TRIGGER regression is covered by test_phantom_gate_lint.py
# (`test_guard_f_runs_on_pull_request` / `test_guard_f_keeps_push_main_and_dispatch`).
#
# Behaviour-based gate: the decision logic lives in ci-required-drift.py
# (`--phantom-gate-lint`) with fail-before/pass-after unit tests in
# .gitea/scripts/tests/test_phantom_gate_lint.py.
#
# IMPORTANT — repository flat-dispatch policy: do NOT add an `inputs:` block
# to `workflow_dispatch:` without a coordinated policy/caller migration.

name: lint-phantom-gate

on:
  # PR-time gate (#3467 promotion). Scoped to the files that can INTRODUCE a
  # phantom in a PR diff: the enforced-contexts SSOT, any workflow file (a
  # rename/delete of a producer is a P2 phantom), the detector itself, and this
  # regression test. Under the `[*]` all-green BP a red here blocks the PR.
  # PATHS FILTER REMOVED 2026-07-14.
  #
  # Guards F and G do not read the PR's diff — they read repo-GLOBAL state: the
  # enforced-contexts SSOT and, critically, the Gitea Actions **workflow states**
  # (active / disabled_manually), which are changed through the API or the web UI
  # and therefore change WITHOUT ANY COMMIT AT ALL.
  #
  # A paths filter on a guard whose input is out-of-band state is a guard that
  # cannot fire when it matters. Someone disables a workflow in the UI; every open
  # PR is now wedgeable by an unrerunnable status; and this lint stays silent until
  # somebody happens to touch a file under .gitea/. The condition it detects is
  # global, so its trigger must be global.
  #
  # Cost is one fast Actions-API read per PR. That is the correct price for a gate
  # that tells a PR it is about to be wedged BEFORE it is wedged.
  pull_request:
    types: [opened, synchronize, reopened]
  push:
    branches: [main]
  workflow_dispatch:

# Read the Actions API (workflow states) + local SSOT file. No writes.
permissions:
  contents: read

concurrency:
  group: lint-phantom-gate-${{ github.ref }}
  cancel-in-progress: true

jobs:
  # REAL gate (not bp-exempt). It now emits on pull_request, so under the `[*]`
  # wildcard BP its status is merge-blocking. The directive stays `pending` — not
  # `yes` — because Tier 2g (lint-required-context-exists-in-bp) validates
  # `bp-required: yes` by requiring the LITERAL context in
  # branch_protections.status_check_contexts, which is `['*']` here; the wildcard
  # already enforces it, so the literal listing is intentionally never added.
  # Directive must stay within 3 lines of the job key:
  # bp-required: pending #3467
  lint-phantom-gate:
    name: lint-phantom-gate
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - name: Check out repo (we read required-contexts.txt locally)
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
      - name: Set up Python
        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5.6.0
        with:
          python-version: '3.12'
      # PyYAML is imported at module top of ci-required-drift.py; install it even
      # though the phantom-lint path itself does not parse YAML, so the import
      # succeeds.
      - name: Install PyYAML
        run: python -m pip install --quiet 'PyYAML==6.0.2'

      # Guard S — runs FIRST and needs NO credentials.
      #
      # Guard F proves an ENFORCED context's producer WORKFLOW is active.
      # Guard S proves the context can actually REACH A TERMINAL, NON-SKIPPED
      # status: its producer JOB still exists, and no job in that job's
      # transitive `needs:` closure carries a job-level `if:` (a false `if:`
      # makes the job `skipped`, and Gitea does not start a dependent whose
      # `needs:` was skipped — the skip propagates to the enforced context).
      #
      # Why that matters: branch protection here is
      # `status_check_contexts: ["*"]`, which treats `skipped` as PASSING and
      # cannot require a context that never posts. gitea-merge-queue.py is the
      # only thing that fail-closes on `skipped` — and it performs a small
      # minority of merges; everything merged through the UI/API is gated by
      # `["*"]` alone. So a skippable required gate is a gate that enforces
      # nothing on most merges.
      #
      # Placed BEFORE the Infisical fetch on purpose: Guard S reads only
      # checked-in files, so an Infisical/KMS outage must not be able to stop
      # it from running.
      - name: Run Guard S — enforced gates must not be able to post `skipped`
        env:
          ENFORCED_CONTEXTS_FILE: .gitea/required-contexts.txt
        run: python3 .gitea/scripts/ci-required-drift.py --skippable-gate-lint
      # KMS consolidation (mirrors ci-required-drift.yml / lint-required-no-paths.yml):
      # fetch the consolidated DRIFT_BOT_TOKEN from the Infisical SSOT (prod
      # /shared/drift-bot) via the CI machine identity. Reading the Actions API
      # workflow-state list requires an authenticated token; the auto GITHUB_TOKEN
      # is 401 on this endpoint. molecule-core PRs are same-repo (not forks), so
      # the INFISICAL_CI_* machine-identity secrets are present on pull_request.
      - name: Fetch DRIFT_BOT_TOKEN from Infisical SSOT
        env:
          INFISICAL_CI_CLIENT_ID: ${{ secrets.INFISICAL_CI_CLIENT_ID }}
          INFISICAL_CI_CLIENT_SECRET: ${{ secrets.INFISICAL_CI_CLIENT_SECRET }}
          INFISICAL_PROJECT_ID: ${{ secrets.INFISICAL_CI_PROJECT_ID }}
        run: |
          set -uo pipefail
          BASE="https://key.moleculesai.app"
          TOK=$(curl -fsS -X POST "$BASE/api/v1/auth/universal-auth/login" \
            -H 'Content-Type: application/json' \
            -d "{\"clientId\":\"$INFISICAL_CI_CLIENT_ID\",\"clientSecret\":\"$INFISICAL_CI_CLIENT_SECRET\"}" \
            | python3 -c 'import sys,json; v=json.load(sys.stdin).get("accessToken"); sys.stdout.write(v if isinstance(v,str) else "")')
          if [ -z "$TOK" ]; then echo "::error::Infisical accessToken empty - failing closed"; exit 1; fi
          read_secret() {
            curl -fsS "$BASE/api/v3/secrets/raw/$1?workspaceId=$INFISICAL_PROJECT_ID&environment=prod&secretPath=$2" \
              -H "Authorization: Bearer $TOK" \
              | python3 -c 'import sys,json; v=json.load(sys.stdin).get("secret",{}).get("secretValue"); sys.stdout.write(v if isinstance(v,str) else "")'
          }
          DRIFT_BOT_TOKEN=$(read_secret DRIFT_BOT_TOKEN %2Fshared%2Fdrift-bot)
          echo "::add-mask::$DRIFT_BOT_TOKEN"
          if [ -z "$DRIFT_BOT_TOKEN" ]; then
            echo "::error::Infisical returned empty DRIFT_BOT_TOKEN at prod /shared/drift-bot — failing closed."
            exit 1
          fi
          echo "DRIFT_BOT_TOKEN=$DRIFT_BOT_TOKEN" >> "$GITHUB_ENV"
          echo "DRIFT_BOT_TOKEN loaded from Infisical (len=${#DRIFT_BOT_TOKEN})"
      - name: Run Guard F phantom-gate lint
        env:
          # DRIFT_BOT_TOKEN reads the Actions API (workflow states). Same
          # least-privilege persona as ci-required-drift.yml.
          GITEA_TOKEN: ${{ env.DRIFT_BOT_TOKEN }}
          GITEA_HOST: git.moleculesai.app
          REPO: ${{ github.repository }}
          ENFORCED_CONTEXTS_FILE: .gitea/required-contexts.txt
        run: python3 .gitea/scripts/ci-required-drift.py --phantom-gate-lint

      # Guard G — the INVERSE of Guard F, and the one that actually wedges.
      #
      # Guard F: an ENFORCED context whose producer is disabled → required on
      #          paper, silently unenforced. (Nothing blocks; protection is a lie.)
      # Guard G: a DISABLED workflow that still fires on PR events → it keeps
      #          posting statuses Gitea will not let you rerun
      #          (400 "workflow is disabled"), so under the `[*]` branch
      #          protection the PR is stuck with no API path out.
      #
      # Runs in the same job to reuse the DRIFT_BOT_TOKEN fetched above — the
      # Actions API workflow-state read is the same call both guards need.
      - name: Run Guard G — disabled workflows must not still fire on PR events
        env:
          GITEA_TOKEN: ${{ env.DRIFT_BOT_TOKEN }}
          GITEA_HOST: git.moleculesai.app
          REPO: ${{ github.repository }}
        run: python3 .gitea/scripts/ci-required-drift.py --disabled-pr-emitter-lint