.gitea/workflows/cicd-checks.yaml

@@ -1,493 +0,0 @@
-name: CICD Checks
-
-on:
-  workflow_dispatch:
-    inputs:
-      head_sha:
-        description: Commit SHA to process
-        required: false
-      source_workflow:
-        description: Upstream workflow name
-        required: false
-      trace_id:
-        description: Correlation id propagated across CICD dispatch chain
-        required: false
-
-env:
-  GITEA_REGISTRY: kankali.darkhelm.lan:3001
-  GITEA_REGISTRY_IP: 10.18.75.2
-  GITEA_REGISTRY_HOST: kankali.darkhelm.lan
-
-concurrency:
-  group: checks-${{ github.sha }}
-  cancel-in-progress: true
-
-jobs:
-  setup:
-    name: Setup Checks Context
-    # Use the same stable runner label as the check matrix jobs.
-    runs-on: ubuntu-act
-    timeout-minutes: 8
-    outputs:
-      head_sha: ${{ steps.meta.outputs.head_sha }}
-      trace_id: ${{ steps.meta.outputs.trace_id }}
-    steps:
-      - name: Identify runner
-        run: |
-          echo "=== Runner Identity ==="
-          echo "runner_name=${RUNNER_NAME:-}"
-          echo "runner_name_hint=${GITEA_RUNNER_NAME:-${ACT_RUNNER_NAME:-${RUNNER_NAME:-unknown}}}"
-          echo "runner_hostname_env=${HOSTNAME:-unknown}"
-          echo "runner_uname_n=$(uname -n 2>/dev/null || echo unknown)"
-          echo "runner_etc_hostname=$(cat /etc/hostname 2>/dev/null || echo unknown)"
-          echo "runner_os=${RUNNER_OS:-unknown}"
-          echo "runner_arch=${RUNNER_ARCH:-unknown}"
-          echo "timestamp_utc=$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-
-      - name: Audit trigger context
-        env:
-          EVENT_NAME: ${{ github.event_name }}
-          SOURCE_WORKFLOW: ${{ github.event.inputs.source_workflow }}
-          HEAD_SHA_INPUT: ${{ github.event.inputs.head_sha }}
-          HEAD_SHA_FALLBACK: ${{ github.sha }}
-          REF: ${{ github.ref }}
-          REF_NAME: ${{ github.ref_name }}
-          HEAD_REF: ${{ github.head_ref }}
-          TRACE_ID_INPUT: ${{ github.event.inputs.trace_id }}
-        run: |
-          RESOLVED_HEAD_SHA="${HEAD_SHA_INPUT:-${HEAD_SHA_FALLBACK}}"
-          TRACE_ID="${TRACE_ID_INPUT:-cicd-checks-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}-${RESOLVED_HEAD_SHA:0:8}}"
-          echo "=== Dispatch Audit: CICD Checks ==="
-          echo "event_name=${EVENT_NAME}"
-          echo "source_workflow=${SOURCE_WORKFLOW}"
-          echo "head_sha_input=${HEAD_SHA_INPUT}"
-          echo "head_sha=${RESOLVED_HEAD_SHA}"
-          echo "ref=${REF}"
-          echo "ref_name=${REF_NAME}"
-          echo "head_ref=${HEAD_REF}"
-          echo "trace_id=${TRACE_ID}"
-
-      - name: Resolve head SHA
-        id: meta
-        env:
-          HEAD_SHA_INPUT: ${{ github.event.inputs.head_sha }}
-          HEAD_SHA_FALLBACK: ${{ github.sha }}
-          TRACE_ID_INPUT: ${{ github.event.inputs.trace_id }}
-        run: |
-          RESOLVED_HEAD_SHA="${HEAD_SHA_INPUT:-${HEAD_SHA_FALLBACK}}"
-          TRACE_ID="${TRACE_ID_INPUT:-cicd-checks-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}-${RESOLVED_HEAD_SHA:0:8}}"
-          echo "head_sha=${RESOLVED_HEAD_SHA}" >> "$GITHUB_OUTPUT"
-          echo "trace_id=${TRACE_ID}" >> "$GITHUB_OUTPUT"
-
-      - &failure_diagnostics_step
-        name: Failure diagnostics
-        if: failure()
-        run: |
-          echo "=== Failure Diagnostics ==="
-          date -u '+timestamp_utc=%Y-%m-%dT%H:%M:%SZ'
-          echo "runner_name=${RUNNER_NAME:-unknown}"
-          echo "runner_hostname=${HOSTNAME:-unknown}"
-          uname -a || true
-          cat /etc/os-release 2>/dev/null || true
-          df -h || true
-          free -h || true
-          ps aux --sort=-%mem | head -n 30 || true
-
-          if command -v docker >/dev/null 2>&1; then
-            echo "=== Docker Diagnostics ==="
-            docker version || true
-            docker info || true
-            docker ps -a || true
-            docker images --digests | head -n 50 || true
-          else
-            echo "docker not available on this runner"
-          fi
-
-          echo "=== Kernel Tail ==="
-          dmesg | tail -n 120 || true
-
-  dockerfile-boundary-check:
-    name: Dockerfile Runtime Boundary Check
-    runs-on: ubuntu-act
-    timeout-minutes: 10
-    needs: setup
-    steps:
-      - name: Configure registry host resolution
-        run: |
-          if ! grep -q "${GITEA_REGISTRY_HOST}" /etc/hosts; then
-            echo "${GITEA_REGISTRY_IP} ${GITEA_REGISTRY_HOST}" >> /etc/hosts
-          fi
-
-      - name: Ensure CICD image is available
-        env:
-          HEAD_SHA: ${{ needs.setup.outputs.head_sha }}
-        run: |
-          IMAGE="${GITEA_REGISTRY}/darkhelm.org/plex-playlist-cicd:${HEAD_SHA}"
-          if docker image inspect "${IMAGE}" >/dev/null 2>&1; then
-            echo "Using cached CICD image: ${IMAGE}"
-          else
-            echo "${{ secrets.PACKAGE_ACCESS_TOKEN }}" | docker login "http://${GITEA_REGISTRY}" -u "${{ github.actor }}" --password-stdin
-            pulled=false
-            for i in 1 2 3; do
-              echo "Pull attempt ${i}/3 for ${IMAGE}"
-              if docker pull "${IMAGE}"; then
-                pulled=true
-                break
-              fi
-              if [ "${i}" -lt 3 ]; then
-                sleep_seconds=$((5 * i))
-                echo "Pull failed; retrying in ${sleep_seconds}s"
-                sleep "${sleep_seconds}"
-              fi
-            done
-
-            if [ "${pulled}" != "true" ]; then
-              echo "❌ Failed to pull CICD image after 3 attempts: ${IMAGE}"
-              exit 1
-            fi
-          fi
-
-      - name: Validate runtime Dockerfile boundaries in validation environment
-        env:
-          HEAD_SHA: ${{ needs.setup.outputs.head_sha }}
-        run: |
-          set -e
-          docker run --rm --entrypoint /bin/bash "${GITEA_REGISTRY}/darkhelm.org/plex-playlist-cicd:${HEAD_SHA}" -c "
-            cd /workspace &&
-            bash scripts/check-dockerfile-boundaries.sh
-          "
-
-      - *failure_diagnostics_step
-
-  run-check:
-    name: ${{ matrix.name }}
-    # Run checks across the full act runner pool for maximum parallelism.
-    runs-on: ubuntu-act
-    timeout-minutes: 20
-    needs: setup
-    strategy:
-      fail-fast: false
-      max-parallel: 6
-      matrix:
-        include:
-          - name: Trailing Whitespace Check
-            hook: trailing-whitespace
-          - name: YAML Syntax Check
-            hook: check-yaml
-          - name: End of File Check
-            hook: end-of-file-fixer
-          - name: TOML Syntax Check
-            hook: check-toml
-          - name: Mixed Line Ending Check
-            hook: mixed-line-ending
-          - name: TOML Formatting Check
-            hook: pretty-format-toml
-          - name: Ruff Linting
-            hook: ruff
-          - name: Ruff Format Check
-            hook: ruff-format
-          - name: Pyright Type Check
-            hook: pyright
-          - name: Pydoclint Docstring Check
-            hook: pydoclint
-          - name: No Docstring Types Check
-            hook: no-docstring-types
-          - name: ESLint Check
-            hook: eslint
-          - name: Prettier Format Check
-            hook: prettier
-          - name: Markdownlint Check
-            hook: markdownlint
-          - name: TSDoc Lint Check
-            hook: tsdoc-lint
-          - name: TypeScript Type Check
-            hook: typescript-check
-    steps:
-      - name: Runner assignment audit
-        env:
-          TRACE_ID: ${{ needs.setup.outputs.trace_id }}
-          HOOK: ${{ matrix.hook }}
-        run: |
-          echo "=== Runner Assignment Audit ==="
-          echo "trace_id=${TRACE_ID}"
-          echo "hook=${HOOK}"
-          echo "run_id=${GITHUB_RUN_ID}"
-          echo "run_attempt=${GITHUB_RUN_ATTEMPT}"
-          echo "job=${GITHUB_JOB}"
-          echo "runner_name=${RUNNER_NAME:-}"
-          echo "runner_name_hint=${GITEA_RUNNER_NAME:-${ACT_RUNNER_NAME:-${RUNNER_NAME:-unknown}}}"
-          echo "runner_hostname_env=${HOSTNAME:-unknown}"
-          echo "runner_uname_n=$(uname -n 2>/dev/null || echo unknown)"
-          echo "runner_etc_hostname=$(cat /etc/hostname 2>/dev/null || echo unknown)"
-          echo "runner_os=${RUNNER_OS:-unknown}"
-          echo "runner_arch=${RUNNER_ARCH:-unknown}"
-          echo "timestamp_utc=$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-
-      - name: Configure registry host resolution
-        run: |
-          if ! grep -q "${GITEA_REGISTRY_HOST}" /etc/hosts; then
-            echo "${GITEA_REGISTRY_IP} ${GITEA_REGISTRY_HOST}" >> /etc/hosts
-          fi
-
-      - name: Ensure CICD image is available
-        env:
-          HEAD_SHA: ${{ needs.setup.outputs.head_sha }}
-        run: |
-          IMAGE="${GITEA_REGISTRY}/darkhelm.org/plex-playlist-cicd:${HEAD_SHA}"
-          if docker image inspect "${IMAGE}" >/dev/null 2>&1; then
-            echo "Using cached CICD image: ${IMAGE}"
-          else
-            echo "${{ secrets.PACKAGE_ACCESS_TOKEN }}" | docker login "http://${GITEA_REGISTRY}" -u "${{ github.actor }}" --password-stdin
-            pulled=false
-            for i in 1 2 3; do
-              echo "Pull attempt ${i}/3 for ${IMAGE}"
-              if docker pull "${IMAGE}"; then
-                pulled=true
-                break
-              fi
-              if [ "${i}" -lt 3 ]; then
-                sleep_seconds=$((5 * i))
-                echo "Pull failed; retrying in ${sleep_seconds}s"
-                sleep "${sleep_seconds}"
-              fi
-            done
-
-            if [ "${pulled}" != "true" ]; then
-              echo "❌ Failed to pull CICD image after 3 attempts: ${IMAGE}"
-              exit 1
-            fi
-          fi
-
-      - name: Validate CICD image provenance
-        env:
-          HEAD_SHA: ${{ needs.setup.outputs.head_sha }}
-        run: |
-          IMAGE="${GITEA_REGISTRY}/darkhelm.org/plex-playlist-cicd:${HEAD_SHA}"
-          SOURCE_SHA=$(docker run --rm --entrypoint /bin/sh "${IMAGE}" -c 'cat /workspace/.cicd-source-sha 2>/dev/null || true')
-
-          echo "requested_head_sha=${HEAD_SHA}"
-          echo "image=${IMAGE}"
-          echo "embedded_source_sha=${SOURCE_SHA:-missing}"
-
-          if [ -z "${SOURCE_SHA}" ]; then
-            echo "❌ Missing /workspace/.cicd-source-sha in ${IMAGE}"
-            exit 1
-          fi
-
-          case "${SOURCE_SHA}" in
-            ${HEAD_SHA}*)
-              ;;
-            *)
-              echo "❌ Source SHA mismatch: requested=${HEAD_SHA} actual=${SOURCE_SHA}"
-              exit 1
-              ;;
-          esac
-
-      - name: Run pre-commit hook
-        env:
-          HEAD_SHA: ${{ needs.setup.outputs.head_sha }}
-          HOOK: ${{ matrix.hook }}
-        run: |
-          set -o pipefail
-          echo "=== Pre-commit Hook Start ==="
-          echo "hook=${HOOK}"
-          echo "head_sha=${HEAD_SHA}"
-
-          if [ "${HOOK}" = "prettier" ]; then
-            echo "=== Host Workspace Debug (prettier) ==="
-            echo "host_head_sha=${HEAD_SHA}"
-            git rev-parse --short HEAD || true
-            if [ -d frontend ]; then
-              (cd frontend && corepack yarn prettier --version && corepack yarn prettier --check src/main.test.ts src/main.ts src/test-setup.ts src/validation.test.ts src/validation.ts) || true
-              (cd frontend && sha256sum src/main.test.ts src/main.ts src/test-setup.ts src/validation.test.ts src/validation.ts) || true
-            else
-              echo "host_frontend_dir_missing=frontend"
-            fi
-          fi
-
-          LOG_FILE="$(mktemp)"
-
-          docker run --rm -e CI=true --entrypoint /bin/sh "${GITEA_REGISTRY}/darkhelm.org/plex-playlist-cicd:${HEAD_SHA}" -c "
-            export HOME=/root &&
-            export PRE_COMMIT_HOME=/root/.cache/pre-commit &&
-            mkdir -p "\$PRE_COMMIT_HOME" &&
-            echo 'running_hook=${HOOK}' &&
-            echo 'pre_commit_home='"\$PRE_COMMIT_HOME" &&
-            echo 'container_shells=' && ls -l /bin/sh /bin/bash 2>/dev/null || true &&
-            echo 'tool_paths=' && command -v git /workspace/backend/.venv/bin/pre-commit python3 python 2>/dev/null || true &&
-            /workspace/backend/.venv/bin/pre-commit --version &&
-            cd /workspace &&
-            if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-              echo 'No git repository found in /workspace; bootstrapping for pre-commit' &&
-              git config --global user.email 'ci@cicd' &&
-              git config --global user.name 'CICD' &&
-              git init /workspace &&
-              git -C /workspace config core.autocrlf false &&
-              git -C /workspace config core.eol lf &&
-              git -C /workspace add -A
-            fi &&
-            case "${HOOK}" in
-              eslint|prettier|tsdoc-lint|typescript-check)
-                echo 'JS hook detected; preparing frontend dependencies' &&
-                if [ ! -d /workspace/frontend ]; then
-                  echo '❌ Missing /workspace/frontend for JS hook execution' &&
-                  exit 1
-                fi &&
-                cd /workspace/frontend &&
-                install_ok=false &&
-                for i in 1 2 3; do
-                  echo 'yarn install attempt' "\$i"'/3' &&
-                  if timeout 1200 corepack yarn install --immutable --mode=skip-build; then
-                    install_ok=true
-                    break
-                  fi
-                  if [ "\$i" -lt 3 ]; then
-                    echo 'yarn install failed; cleaning and retrying in 20s' &&
-                    rm -rf node_modules .yarn/install-state.gz .yarn/cache &&
-                    corepack yarn cache clean --all 2>/dev/null || true &&
-                    sleep 20
-                  fi
-                done &&
-                if [ "\$install_ok" != 'true' ]; then
-                  echo '❌ Unable to prepare frontend dependencies for JS pre-commit hooks' &&
-                  exit 1
-                fi &&
-                if [ "${HOOK}" = "prettier" ]; then
-                  echo '=== Container Workspace Debug (prettier) ===' &&
-                  corepack yarn prettier --version || true &&
-                  sha256sum src/main.test.ts src/main.ts src/test-setup.ts src/validation.test.ts src/validation.ts || true &&
-                  corepack yarn prettier --check src/main.test.ts src/main.ts src/test-setup.ts src/validation.test.ts src/validation.ts || true
-                fi &&
-                cd /workspace
-                ;;
-            esac &&
-            /workspace/backend/.venv/bin/pre-commit run ${HOOK} --all-files --show-diff-on-failure
-          " 2>&1 | tee "${LOG_FILE}"
-
-          HOOK_STATUS=${PIPESTATUS[0]}
-          if [ "${HOOK_STATUS}" -ne 0 ]; then
-            echo "❌ Pre-commit hook failed: ${HOOK} (exit=${HOOK_STATUS})"
-            echo "--- Last 200 lines of hook output ---"
-            tail -n 200 "${LOG_FILE}" || true
-
-            if [ "${HOOK}" = "pydoclint" ]; then
-              echo "=== Additional pydoclint diagnostics ==="
-              docker run --rm -e CI=true --entrypoint /bin/sh "${GITEA_REGISTRY}/darkhelm.org/plex-playlist-cicd:${HEAD_SHA}" -c "
-                set -e
-                cd /workspace/backend
-                echo 'python_version=' && python3 --version
-                echo 'uv_version=' && uv --version
-                echo 'pydoclint_version=' && uv run pydoclint --version
-                echo 'backend_py_count=' && find src -name '*.py' | wc -l
-                echo 'running_direct_pydoclint='
-                uv run pydoclint --config=pyproject.toml src/
-              " || true
-            fi
-
-            exit "${HOOK_STATUS}"
-          fi
-
-          echo "=== Pre-commit Hook End (success) ==="
-
-      - *failure_diagnostics_step
-
-  dispatch-tests:
-    name: Dispatch CICD Tests
-    # Keep dispatch on the same runner pool as setup/check jobs.
-    runs-on: ubuntu-act
-    timeout-minutes: 15
-    needs: [setup, run-check]
-    steps:
-      - name: Dispatch tests workflow
-        env:
-          ACTIONS_TRIGGER_TOKEN: ${{ secrets.ACTIONS_TRIGGER_TOKEN }}
-          PACKAGE_ACCESS_TOKEN: ${{ secrets.PACKAGE_ACCESS_TOKEN }}
-          HEAD_SHA: ${{ needs.setup.outputs.head_sha }}
-          REPO_FULL: ${{ github.repository }}
-          HEAD_REF: ${{ github.head_ref }}
-          REF_NAME: ${{ github.ref_name }}
-          TRACE_ID_INPUT: ${{ github.event.inputs.trace_id }}
-        run: |
-          set -e
-
-          DISPATCH_TOKEN="${ACTIONS_TRIGGER_TOKEN:-${PACKAGE_ACCESS_TOKEN:-}}"
-
-          if [ -z "${DISPATCH_TOKEN}" ]; then
-            echo "❌ Missing dispatch token. Set ACTIONS_TRIGGER_TOKEN (repo write scope) or ensure PACKAGE_ACCESS_TOKEN has Actions workflow-dispatch permissions."
-            exit 1
-          fi
-
-          if ! grep -q "${GITEA_REGISTRY_HOST}" /etc/hosts; then
-            echo "${GITEA_REGISTRY_IP} ${GITEA_REGISTRY_HOST}" >> /etc/hosts
-          fi
-
-          REPO_OWNER="${REPO_FULL%/*}"
-          REPO_NAME="${REPO_FULL#*/}"
-          TARGET_REF="${HEAD_REF:-${REF_NAME}}"
-          TRACE_ID="${TRACE_ID_INPUT:-cicd-checks-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}-${HEAD_SHA:0:8}}"
-
-          echo "trace_id=${TRACE_ID}"
-          echo "target_ref=${TARGET_REF}"
-
-          CANDIDATE_API_BASES=()
-          if [ -n "${GITHUB_SERVER_URL:-}" ]; then
-            CANDIDATE_API_BASES+=("${GITHUB_SERVER_URL%/}/api/v1")
-          fi
-          CANDIDATE_API_BASES+=("http://${GITEA_REGISTRY_IP}:3001/api/v1")
-          CANDIDATE_API_BASES+=("http://${GITEA_REGISTRY_HOST}:3001/api/v1")
-
-          ensure_curl() {
-            if command -v curl >/dev/null 2>&1; then
-              return 0
-            fi
-            if command -v apt-get >/dev/null 2>&1; then
-              export DEBIAN_FRONTEND=noninteractive
-              apt-get update -qq
-              apt-get install -y -qq curl ca-certificates
-            fi
-            command -v curl >/dev/null 2>&1
-          }
-
-          ensure_curl || { echo "❌ curl unavailable for dispatch"; exit 1; }
-
-          HELPER_PATH="/tmp/dispatch-workflow.sh"
-
-          fetch_dispatch_helper() {
-            local helper_ref="$1"
-            local api_base
-            for api_base in "${CANDIDATE_API_BASES[@]}"; do
-              helper_url="${api_base}/repos/${REPO_OWNER}/${REPO_NAME}/raw/scripts/dispatch-workflow.sh?ref=${helper_ref}"
-              if curl -fsS --connect-timeout 5 --max-time 20 \
-                -H "Authorization: token ${DISPATCH_TOKEN}" \
-                -H "User-Agent: plex-playlist-cicd-checks" \
-                -o "${HELPER_PATH}" \
-                "${helper_url}"; then
-                chmod +x "${HELPER_PATH}"
-                return 0
-              fi
-            done
-            return 1
-          }
-
-          if ! fetch_dispatch_helper "${TARGET_REF}" && ! fetch_dispatch_helper "${HEAD_SHA}"; then
-            echo "❌ Failed to fetch scripts/dispatch-workflow.sh from repository"
-            exit 1
-          fi
-
-          DISPATCH_ARGS=(
-            --token "${DISPATCH_TOKEN}"
-            --repo "${REPO_FULL}"
-            --workflow "cicd-tests.yaml"
-            --ref "${TARGET_REF}"
-            --head-sha "${HEAD_SHA}"
-            --source-workflow "CICD Checks"
-            --trace-id "${TRACE_ID}"
-          )
-
-          for API_BASE in "${CANDIDATE_API_BASES[@]}"; do
-            DISPATCH_ARGS+=(--api-base "${API_BASE}")
-          done
-
-          "${HELPER_PATH}" "${DISPATCH_ARGS[@]}"
-
-      - *failure_diagnostics_step

.gitea/workflows/cicd-source-checks.yaml

@@ -0,0 +1,380 @@
+name: CICD Source Checks
+
+on:
+  workflow_dispatch:
+    inputs:
+      head_sha:
+        description: Commit SHA to process
+        required: false
+      source_workflow:
+        description: Upstream workflow name
+        required: false
+      trace_id:
+        description: Correlation id propagated across CICD dispatch chain
+        required: false
+      base_needed:
+        description: Whether base rebuild is required downstream
+        required: false
+      base_hash:
+        description: Immutable base hash to pass downstream
+        required: false
+
+env:
+  GITEA_SSH_HOST: kankali.darkhelm.lan
+  GITEA_SSH_PORT: "2222"
+  GITEA_REPO_SSH_URL: ssh://git@kankali.darkhelm.lan:2222/DarkHelm.org/plex-playlist.git
+  GITEA_REGISTRY: kankali.darkhelm.lan:3001
+  GITEA_REGISTRY_IP: 10.18.75.2
+  GITEA_REGISTRY_HOST: kankali.darkhelm.lan
+
+concurrency:
+  group: source-checks-${{ github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  setup:
+    name: Setup Source Checks Context
+    runs-on: ubuntu-act
+    timeout-minutes: 10
+    outputs:
+      head_sha: ${{ steps.meta.outputs.head_sha }}
+      trace_id: ${{ steps.meta.outputs.trace_id }}
+      base_needed: ${{ steps.meta.outputs.base_needed }}
+      base_hash: ${{ steps.meta.outputs.base_hash }}
+    steps:
+      - name: Identify runner
+        run: |
+          echo "=== Runner Identity ==="
+          echo "runner_name=${RUNNER_NAME:-}"
+          echo "runner_name_hint=${GITEA_RUNNER_NAME:-${ACT_RUNNER_NAME:-${RUNNER_NAME:-unknown}}}"
+          echo "runner_hostname_env=${HOSTNAME:-unknown}"
+          echo "runner_uname_n=$(uname -n 2>/dev/null || echo unknown)"
+          echo "runner_etc_hostname=$(cat /etc/hostname 2>/dev/null || echo unknown)"
+          echo "runner_os=${RUNNER_OS:-unknown}"
+          echo "runner_arch=${RUNNER_ARCH:-unknown}"
+          echo "timestamp_utc=$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+      - name: Audit trigger context
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          SOURCE_WORKFLOW: ${{ github.event.inputs.source_workflow }}
+          HEAD_SHA_INPUT: ${{ github.event.inputs.head_sha }}
+          HEAD_SHA_FALLBACK: ${{ github.sha }}
+          BASE_NEEDED_INPUT: ${{ github.event.inputs.base_needed }}
+          BASE_HASH_INPUT: ${{ github.event.inputs.base_hash }}
+          REF: ${{ github.ref }}
+          REF_NAME: ${{ github.ref_name }}
+          HEAD_REF: ${{ github.head_ref }}
+          TRACE_ID_INPUT: ${{ github.event.inputs.trace_id }}
+        run: |
+          RESOLVED_HEAD_SHA="${HEAD_SHA_INPUT:-${HEAD_SHA_FALLBACK}}"
+          RESOLVED_BASE_NEEDED="${BASE_NEEDED_INPUT:-true}"
+          TRACE_ID="${TRACE_ID_INPUT:-cicd-source-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}-${RESOLVED_HEAD_SHA:0:8}}"
+          echo "=== Dispatch Audit: CICD Source Checks ==="
+          echo "event_name=${EVENT_NAME}"
+          echo "source_workflow=${SOURCE_WORKFLOW}"
+          echo "head_sha_input=${HEAD_SHA_INPUT}"
+          echo "head_sha=${RESOLVED_HEAD_SHA}"
+          echo "base_needed=${RESOLVED_BASE_NEEDED}"
+          echo "base_hash=${BASE_HASH_INPUT:-deferred}"
+          echo "ref=${REF}"
+          echo "ref_name=${REF_NAME}"
+          echo "head_ref=${HEAD_REF}"
+          echo "trace_id=${TRACE_ID}"
+
+      - name: Resolve source check metadata
+        id: meta
+        env:
+          HEAD_SHA_INPUT: ${{ github.event.inputs.head_sha }}
+          HEAD_SHA_FALLBACK: ${{ github.sha }}
+          TRACE_ID_INPUT: ${{ github.event.inputs.trace_id }}
+          BASE_NEEDED_INPUT: ${{ github.event.inputs.base_needed }}
+          BASE_HASH_INPUT: ${{ github.event.inputs.base_hash }}
+        run: |
+          RESOLVED_HEAD_SHA="${HEAD_SHA_INPUT:-${HEAD_SHA_FALLBACK}}"
+          RESOLVED_TRACE_ID="${TRACE_ID_INPUT:-cicd-source-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}-${RESOLVED_HEAD_SHA:0:8}}"
+          RESOLVED_BASE_NEEDED="${BASE_NEEDED_INPUT:-true}"
+          RESOLVED_BASE_HASH="${BASE_HASH_INPUT:-deferred}"
+
+          echo "head_sha=${RESOLVED_HEAD_SHA}" >> "$GITHUB_OUTPUT"
+          echo "trace_id=${RESOLVED_TRACE_ID}" >> "$GITHUB_OUTPUT"
+          echo "base_needed=${RESOLVED_BASE_NEEDED}" >> "$GITHUB_OUTPUT"
+          echo "base_hash=${RESOLVED_BASE_HASH}" >> "$GITHUB_OUTPUT"
+
+      - &failure_diagnostics_step
+        name: Failure diagnostics
+        if: failure()
+        run: |
+          echo "=== Failure Diagnostics ==="
+          date -u '+timestamp_utc=%Y-%m-%dT%H:%M:%SZ'
+          echo "runner_name=${RUNNER_NAME:-unknown}"
+          echo "runner_hostname=${HOSTNAME:-unknown}"
+          uname -a || true
+          cat /etc/os-release 2>/dev/null || true
+          df -h || true
+          free -h || true
+          ps aux --sort=-%mem | head -n 30 || true
+
+          if command -v docker >/dev/null 2>&1; then
+            echo "=== Docker Diagnostics ==="
+            docker version || true
+            docker info || true
+            docker ps -a || true
+            docker images --digests | head -n 50 || true
+          else
+            echo "docker not available on this runner"
+          fi
+
+          echo "=== Kernel Tail ==="
+          dmesg | tail -n 120 || true
+
+  source-precommit-checks:
+    name: Source Pre-commit Checks (backend+frontend)
+    runs-on: ubuntu-act
+    timeout-minutes: 40
+    needs: setup
+    steps:
+      - name: Identify runner
+        run: |
+          echo "=== Runner Identity ==="
+          echo "runner_name=${RUNNER_NAME:-}"
+          echo "runner_name_hint=${GITEA_RUNNER_NAME:-${ACT_RUNNER_NAME:-${RUNNER_NAME:-unknown}}}"
+          echo "runner_hostname_env=${HOSTNAME:-unknown}"
+          echo "runner_uname_n=$(uname -n 2>/dev/null || echo unknown)"
+          echo "runner_etc_hostname=$(cat /etc/hostname 2>/dev/null || echo unknown)"
+          echo "runner_os=${RUNNER_OS:-unknown}"
+          echo "runner_arch=${RUNNER_ARCH:-unknown}"
+          echo "timestamp_utc=$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+      - name: Configure registry host resolution
+        run: |
+          if ! grep -q "${GITEA_REGISTRY_HOST}" /etc/hosts; then
+            echo "${GITEA_REGISTRY_IP} ${GITEA_REGISTRY_HOST}" >> /etc/hosts
+          fi
+
+      - name: Checkout source snapshot
+        env:
+          SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
+          HEAD_SHA: ${{ needs.setup.outputs.head_sha }}
+        run: |
+          set -e
+          umask 022
+          trap 'rm -f ~/.ssh/id_rsa' EXIT
+
+          mkdir -p ~/.ssh
+          echo "${SSH_PRIVATE_KEY}" > ~/.ssh/id_rsa
+          chmod 600 ~/.ssh/id_rsa
+          ssh-keyscan -p "${GITEA_SSH_PORT}" "${GITEA_SSH_HOST}" >> ~/.ssh/known_hosts 2>/dev/null
+
+          GIT_SSH_COMMAND="ssh -i ~/.ssh/id_rsa -o IdentitiesOnly=yes -o StrictHostKeyChecking=no" \
+            git clone --depth 1 --no-checkout "${GITEA_REPO_SSH_URL}" .
+
+          if GIT_SSH_COMMAND="ssh -i ~/.ssh/id_rsa -o IdentitiesOnly=yes -o StrictHostKeyChecking=no" \
+            git fetch --depth 1 origin "${HEAD_SHA}" >/dev/null 2>&1; then
+            git checkout FETCH_HEAD -- .
+            echo "Using fetched HEAD_SHA checkout: ${HEAD_SHA}"
+          else
+            git checkout HEAD -- .
+            echo "Falling back to default branch HEAD for source checks checkout"
+          fi
+
+          test -f .pre-commit-config.yaml || {
+            echo "❌ Missing .pre-commit-config.yaml after checkout"
+            exit 1
+          }
+
+          test -f backend/pyproject.toml || {
+            echo "❌ Missing backend/pyproject.toml after checkout"
+            exit 1
+          }
+
+          test -f frontend/package.json || {
+            echo "❌ Missing frontend/package.json after checkout"
+            find . -maxdepth 3 -type f | sort | head -n 80
+            exit 1
+          }
+
+      - name: Bootstrap source-check toolchain
+        run: |
+          set -euo pipefail
+
+          if ! command -v curl >/dev/null 2>&1; then
+            apt-get update -qq
+            apt-get install -y -qq curl ca-certificates
+          fi
+
+          # Install uv if missing and expose it for subsequent steps.
+          if ! command -v uv >/dev/null 2>&1; then
+            curl -LsSf https://astral.sh/uv/install.sh | sh
+          fi
+          export PATH="$HOME/.local/bin:$PATH"
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+
+          # Ensure node/corepack is available for frontend and pre-commit hooks.
+          if ! command -v node >/dev/null 2>&1; then
+            apt-get update -qq
+            apt-get install -y -qq nodejs npm
+          fi
+          if ! command -v corepack >/dev/null 2>&1; then
+            npm install -g corepack
+          fi
+
+          corepack enable
+
+      - name: Install backend and frontend dependencies
+        run: |
+          set -euo pipefail
+          export PATH="$HOME/.local/bin:$PATH"
+
+          cd backend
+          uv sync --dev
+          cd ../frontend
+          yarn install --immutable || yarn install
+
+      - name: Run pre-commit source checks
+        env:
+          CI: "true"
+        run: |
+          set -euo pipefail
+          export PATH="$HOME/.local/bin:$PATH"
+          cd backend
+          uv run pre-commit run --all-files --show-diff-on-failure --config ../.pre-commit-config.yaml
+
+      - *failure_diagnostics_step
+
+  dispatch-build:
+    name: Dispatch Downstream Build
+    runs-on: ubuntu-act
+    timeout-minutes: 10
+    needs: [setup, source-precommit-checks]
+    steps:
+      - name: Identify runner
+        run: |
+          echo "=== Runner Identity ==="
+          echo "runner_name=${RUNNER_NAME:-}"
+          echo "runner_name_hint=${GITEA_RUNNER_NAME:-${ACT_RUNNER_NAME:-${RUNNER_NAME:-unknown}}}"
+          echo "runner_hostname_env=${HOSTNAME:-unknown}"
+          echo "runner_uname_n=$(uname -n 2>/dev/null || echo unknown)"
+          echo "runner_etc_hostname=$(cat /etc/hostname 2>/dev/null || echo unknown)"
+          echo "runner_os=${RUNNER_OS:-unknown}"
+          echo "runner_arch=${RUNNER_ARCH:-unknown}"
+          echo "timestamp_utc=$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+      - name: Configure registry host resolution
+        run: |
+          if ! grep -q "${GITEA_REGISTRY_HOST}" /etc/hosts; then
+            echo "${GITEA_REGISTRY_IP} ${GITEA_REGISTRY_HOST}" >> /etc/hosts
+          fi
+
+      - name: Dispatch downstream workflow
+        env:
+          ACTIONS_TRIGGER_TOKEN: ${{ secrets.ACTIONS_TRIGGER_TOKEN }}
+          PACKAGE_ACCESS_TOKEN: ${{ secrets.PACKAGE_ACCESS_TOKEN }}
+          BASE_NEEDED: ${{ needs.setup.outputs.base_needed }}
+          BASE_HASH: ${{ needs.setup.outputs.base_hash }}
+          HEAD_SHA: ${{ needs.setup.outputs.head_sha }}
+          TRACE_ID: ${{ needs.setup.outputs.trace_id }}
+          REPO_FULL: ${{ github.repository }}
+          HEAD_REF: ${{ github.head_ref }}
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          set -e
+
+          DISPATCH_TOKEN="${ACTIONS_TRIGGER_TOKEN:-${PACKAGE_ACCESS_TOKEN:-}}"
+
+          if [ -z "${DISPATCH_TOKEN}" ]; then
+            echo "❌ Missing dispatch token. Set ACTIONS_TRIGGER_TOKEN (repo write scope) or ensure PACKAGE_ACCESS_TOKEN has Actions workflow-dispatch permissions."
+            exit 1
+          fi
+
+          REPO_OWNER="${REPO_FULL%/*}"
+          REPO_NAME="${REPO_FULL#*/}"
+          TARGET_REF="${HEAD_REF:-${REF_NAME}}"
+
+          if [ "${BASE_NEEDED}" = "true" ]; then
+            TARGET_WORKFLOW="docker-build-base.yaml"
+          else
+            TARGET_WORKFLOW="docker-build-main.yaml"
+          fi
+
+          echo "route_decision workflow=${TARGET_WORKFLOW} head_sha=${HEAD_SHA} base_needed=${BASE_NEEDED} trace_id=${TRACE_ID}"
+
+          CANDIDATE_API_BASES=()
+          if [ -n "${GITHUB_SERVER_URL:-}" ]; then
+            CANDIDATE_API_BASES+=("${GITHUB_SERVER_URL%/}/api/v1")
+          fi
+          if [ -n "${GITEA_SSH_HOST:-}" ]; then
+            CANDIDATE_API_BASES+=("http://${GITEA_SSH_HOST}:3001/api/v1")
+          fi
+          if [ -n "${GITEA_REGISTRY_HOST:-}" ]; then
+            CANDIDATE_API_BASES+=("http://${GITEA_REGISTRY_HOST}:3001/api/v1")
+          fi
+          if [ -n "${GITEA_REGISTRY_IP:-}" ]; then
+            CANDIDATE_API_BASES+=("http://${GITEA_REGISTRY_IP}:3001/api/v1")
+          fi
+
+          ensure_curl() {
+            if command -v curl >/dev/null 2>&1; then
+              return 0
+            fi
+
+            if command -v apt-get >/dev/null 2>&1; then
+              export DEBIAN_FRONTEND=noninteractive
+              apt-get update -qq
+              apt-get install -y -qq curl ca-certificates
+            fi
+
+            if command -v curl >/dev/null 2>&1; then
+              return 0
+            fi
+
+            echo "❌ curl is required for dispatch and could not be installed"
+            return 1
+          }
+
+          ensure_curl
+
+          HELPER_PATH="/tmp/dispatch-workflow.sh"
+
+          fetch_dispatch_helper() {
+            local helper_ref="$1"
+            local api_base
+            for api_base in "${CANDIDATE_API_BASES[@]}"; do
+              helper_url="${api_base}/repos/${REPO_OWNER}/${REPO_NAME}/raw/scripts/dispatch-workflow.sh?ref=${helper_ref}"
+              if curl -fsS --connect-timeout 5 --max-time 20 \
+                -H "Authorization: token ${DISPATCH_TOKEN}" \
+                -H "User-Agent: plex-playlist-cicd-source-checks" \
+                -o "${HELPER_PATH}" \
+                "${helper_url}"; then
+                chmod +x "${HELPER_PATH}"
+                return 0
+              fi
+            done
+            return 1
+          }
+
+          if ! fetch_dispatch_helper "${TARGET_REF}" && ! fetch_dispatch_helper "${HEAD_SHA}"; then
+            echo "❌ Failed to fetch scripts/dispatch-workflow.sh from repository"
+            exit 1
+          fi
+
+          DISPATCH_ARGS=(
+            --token "${DISPATCH_TOKEN}"
+            --repo "${REPO_FULL}"
+            --workflow "${TARGET_WORKFLOW}"
+            --ref "${TARGET_REF}"
+            --head-sha "${HEAD_SHA}"
+            --source-workflow "CICD Source Checks"
+            --trace-id "${TRACE_ID}"
+            --base-needed "${BASE_NEEDED}"
+            --base-hash "${BASE_HASH}"
+          )
+
+          for API_BASE in "${CANDIDATE_API_BASES[@]}"; do
+            DISPATCH_ARGS+=(--api-base "${API_BASE}")
+          done
+
+          echo "✅ Source checks passed; dispatching ${TARGET_WORKFLOW}"
+          "${HELPER_PATH}" "${DISPATCH_ARGS[@]}"
+
+      - *failure_diagnostics_step

.gitea/workflows/cicd-start.yaml

@@ -2,7 +2,7 @@ name: CICD Start
 
 on:
   push:
-    branches: [ main, develop ]
+    branches: [ '**' ]
   pull_request:
     branches: [ main, develop ]
   workflow_dispatch:
@@ -120,11 +120,9 @@ jobs:
           echo "trace_id=${TRACE_ID}"
           echo "target_ref=${TARGET_REF}"
 
-          if [ "${BASE_NEEDED}" = "true" ]; then
-            TARGET_WORKFLOW="docker-build-base.yaml"
-          else
-            TARGET_WORKFLOW="docker-build-main.yaml"
-          fi
+          TARGET_WORKFLOW="cicd-source-checks.yaml"
+
+          echo "route_decision workflow=${TARGET_WORKFLOW} head_sha=${HEAD_SHA} base_needed=${BASE_NEEDED} trace_id=${TRACE_ID}"
 
           CANDIDATE_API_BASES=()
           if [ -n "${GITHUB_SERVER_URL:-}" ]; then

.gitea/workflows/docker-build-main.yaml

@@ -335,14 +335,14 @@ jobs:
 
       - *failure_diagnostics_step
 
-  dispatch-checks:
-    name: Dispatch CICD Checks
+  dispatch-tests:
+    name: Dispatch CICD Tests
     runs-on: ubuntu-act
     timeout-minutes: 15
     needs: build
     if: needs.build.result == 'success'
     steps:
-      - name: Dispatch checks workflow
+      - name: Dispatch tests workflow
         env:
           ACTIONS_TRIGGER_TOKEN: ${{ secrets.ACTIONS_TRIGGER_TOKEN }}
           PACKAGE_ACCESS_TOKEN: ${{ secrets.PACKAGE_ACCESS_TOKEN }}
@@ -421,7 +421,7 @@ jobs:
           DISPATCH_ARGS=(
             --token "${DISPATCH_TOKEN}"
             --repo "${REPO_FULL}"
-            --workflow "cicd-checks.yaml"
+            --workflow "cicd-tests.yaml"
             --ref "${TARGET_REF}"
             --head-sha "${HEAD_SHA}"
             --source-workflow "CICD Main Build"

.gitea/workflows/renovate.yml

@@ -230,27 +230,75 @@ jobs:
 
       - name: Run Renovate
         env:
-          # RENOVATE_TOKEN is the primary auth mechanism — set via repo secret.
-          RENOVATE_TOKEN: ${{ secrets.RENOVATE_TOKEN }}
+          # Prefer dedicated Renovate token, then fall back to existing CI tokens.
+          RENOVATE_TOKEN_SECRET: ${{ secrets.RENOVATE_TOKEN }}
+          ACTIONS_TRIGGER_TOKEN: ${{ secrets.ACTIONS_TRIGGER_TOKEN }}
+          PACKAGE_ACCESS_TOKEN: ${{ secrets.PACKAGE_ACCESS_TOKEN }}
           RENOVATE_DRY_RUN: ${{ inputs.dry_run }}
           RENOVATE_CONFIG_FILE: renovate-config.js
+          RENOVATE_PLATFORM: gitea
+          RENOVATE_ENDPOINT: https://dogar.darkhelm.org/api/v1
+          RENOVATE_ALLOW_INSECURE_TLS: "true"
           LOG_LEVEL: info
         run: |
           echo "=== Running Renovate Bot ==="
 
-          # Verify token is available
-          if [ -z "${RENOVATE_TOKEN}" ]; then
-            echo "❌ RENOVATE_TOKEN secret not configured"
-            echo "Please add a Gitea API token to repository secrets"
+          select_token() {
+            if [ -n "${RENOVATE_TOKEN_SECRET:-}" ]; then
+              echo "${RENOVATE_TOKEN_SECRET}"
+              return 0
+            fi
+            if [ -n "${ACTIONS_TRIGGER_TOKEN:-}" ]; then
+              echo "${ACTIONS_TRIGGER_TOKEN}"
+              return 0
+            fi
+            if [ -n "${PACKAGE_ACCESS_TOKEN:-}" ]; then
+              echo "${PACKAGE_ACCESS_TOKEN}"
+              return 0
+            fi
+            return 1
+          }
+
+          if ! SELECTED_TOKEN="$(select_token)"; then
+            echo "❌ No token available for Renovate authentication"
+            echo "Configure one of: RENOVATE_TOKEN, ACTIONS_TRIGGER_TOKEN, PACKAGE_ACCESS_TOKEN"
             exit 1
           fi
 
+          export RENOVATE_TOKEN="${SELECTED_TOKEN}"
+          unset SELECTED_TOKEN
+
+          CURL_INSECURE_FLAG=""
+          if [ "${RENOVATE_ALLOW_INSECURE_TLS:-false}" = "true" ]; then
+            echo "⚠ Renovate insecure TLS mode enabled for self-signed certificate endpoint"
+            CURL_INSECURE_FLAG="--insecure"
+            export NODE_TLS_REJECT_UNAUTHORIZED=0
+          fi
+
+          # Validate token before starting Renovate to fail with actionable diagnostics.
+          AUTH_CHECK_STATUS=$(curl -sS -o /tmp/renovate-auth-check.json -w "%{http_code}" \
+            ${CURL_INSECURE_FLAG} \
+            -H "Authorization: token ${RENOVATE_TOKEN}" \
+            "${RENOVATE_ENDPOINT}/user" || true)
+
+          if [ "${AUTH_CHECK_STATUS}" != "200" ]; then
+            echo "❌ Renovate token authentication preflight failed (HTTP ${AUTH_CHECK_STATUS})"
+            echo "Expected a personal access token with repo/issue read-write permissions."
+            if [ -s /tmp/renovate-auth-check.json ]; then
+              echo "Response body:"
+              cat /tmp/renovate-auth-check.json || true
+            fi
+            exit 1
+          fi
+
+          echo "✓ Renovate auth preflight passed"
+
           # Run Renovate with configuration
           if [ "${RENOVATE_DRY_RUN}" = "true" ]; then
             echo "🔍 Running in DRY-RUN mode (no changes will be made)"
           fi
 
-          renovate DarkHelm.org/plex-playlist
+          renovate --platform "${RENOVATE_PLATFORM}" --endpoint "${RENOVATE_ENDPOINT}" DarkHelm.org/plex-playlist
 
           echo "✓ Renovate execution completed"
 

.pre-commit-config.yaml

@@ -18,7 +18,7 @@ repos:
     rev: v0.45.0
     hooks:
       - id: markdownlint
-        args: [--fix]
+        entry: bash -c 'if [ "${CI:-}" = "true" ]; then markdownlint "$@"; else markdownlint --fix "$@"; fi' --
         files: \.(md|markdown)$
 
   # TOML linting
@@ -26,7 +26,7 @@ repos:
     rev: v2.14.0
     hooks:
       - id: pretty-format-toml
-        args: [--autofix]
+        entry: bash -c 'if [ "${CI:-}" = "true" ]; then pretty-format-toml "$@"; else pretty-format-toml --autofix "$@"; fi' --
 
   # Python backend linting and formatting with ruff
   - repo: local
@@ -34,7 +34,7 @@ repos:
       # Linter
       - id: ruff
         name: ruff-lint
-        entry: bash -c 'cd backend && uv run ruff check --fix . --config=pyproject.toml'
+        entry: bash -c 'cd backend && if [ "${CI:-}" = "true" ]; then uv run ruff check . --config=pyproject.toml; else uv run ruff check --fix . --config=pyproject.toml; fi'
         language: system
         files: ^backend/
         types: [python]
@@ -42,7 +42,7 @@ repos:
       # Formatter
       - id: ruff-format
         name: ruff-format
-        entry: bash -c 'cd backend && uv run ruff format . --config=pyproject.toml'
+        entry: bash -c 'cd backend && if [ "${CI:-}" = "true" ]; then uv run ruff format --check . --config=pyproject.toml; else uv run ruff format . --config=pyproject.toml; fi'
         language: system
         files: ^backend/
         types: [python]

docs/CICD_MULTI_STAGE_BUILD.md

@@ -142,10 +142,13 @@ jobs:
 
 ### Responsibility Split
 
+- `.gitea/workflows/cicd-start.yaml` owns startup routing and trace propagation.
+- `.gitea/workflows/cicd-source-checks.yaml` owns early source-level
+  format/lint/type gating before any promotion dispatch.
 - `.gitea/workflows/docker-build-base.yaml` owns base publication and verification.
 - `.gitea/workflows/docker-build-main.yaml` owns complete-image publication.
-- `.gitea/workflows/cicd-start.yaml`, `.gitea/workflows/cicd-checks.yaml`, and
-  `.gitea/workflows/cicd-tests.yaml` own CI validation and checks.
+- `.gitea/workflows/cicd-checks.yaml` and `.gitea/workflows/cicd-tests.yaml`
+  own post-build CI validation and tests.
 - Main CI never rebuilds the base image locally.
 
 ### Runtime Boundary Enforcement

docs/DEVELOPMENT.md

@@ -390,8 +390,9 @@ pre-commit run end-of-file-fixer --all-files
 
 The CI/CD pipeline uses a **multi-stage build architecture** for optimal performance:
 
-- **Stage 1**: Build base image (system dependencies, Python, Node.js) - **cached across runs**
-- **Stage 2**: Build complete image (project code and dependencies) - **rebuilt every time**
+- **Stage 1**: Source-level fast checks (format, lint, type-check) - **hard promotion gate**
+- **Stage 2**: Build base image (system dependencies, Python, Node.js) - **cached across runs**
+- **Stage 3**: Build complete image (project code and dependencies) - **rebuilt every time**
 
 Pipeline triggers:
 
@@ -425,26 +426,19 @@ For detailed technical information, see [CI/CD Multi-Stage Build Architecture](C
 
 All jobs run in parallel after the setup phases:
 
-1. **Setup Base**: Builds and pushes base Docker image (conditional)
-2. **Setup Complete**: Builds and pushes complete CI/CD Docker image
-3. **Code Quality**:
-   - Trailing whitespace check
-   - End-of-file formatting
-   - YAML syntax validation
-   - TOML syntax validation
-4. **Backend Validation**:
-   - Ruff formatting check
-   - Ruff linting
-   - Pyright type checking
-   - Darglint docstring validation
-   - Unit tests with coverage
-   - Integration tests
-   - Doctests (xdoctest)
-5. **Frontend Validation**:
-   - Prettier formatting check
-   - ESLint linting
-   - TypeScript compilation
-   - Unit tests with coverage
+1. **Source Fast Gate**:
+   Backend source checks (Ruff format/lint, Pyright), frontend source checks (Prettier, ESLint, TypeScript), and dispatches downstream build only on success.
+
+2. **Setup Base**: Builds and pushes base Docker image (conditional)
+3. **Setup Complete**: Builds and pushes complete CI/CD Docker image
+4. **Code Quality**:
+   Trailing whitespace check, end-of-file formatting, YAML syntax validation, and TOML syntax validation.
+
+5. **Backend Validation**:
+   Ruff formatting check, Ruff linting, Pyright type checking, Darglint docstring validation, unit tests with coverage, integration tests, and doctests (xdoctest).
+
+6. **Frontend Validation**:
+   Prettier formatting check, ESLint linting, TypeScript compilation, and unit tests with coverage.
    - E2E tests (Playwright)
 
 ### Local CI/CD Testing