fix(ci): repair broken gates and enforce CI contracts

.github/actions/setup-caches/action.yml

@@ -12,6 +12,16 @@ inputs:
 runs:
   using: "composite"
   steps:
+    - name: Validate cache type
+      shell: bash
+      env:
+        CACHE_TYPE: ${{ inputs.cache-type }}
+      run: |
+        case "$CACHE_TYPE" in
+          application-server-quality|application-server-verification|application-server-integration|server-contracts|webapp-e2e|webapp-storybook) ;;
+          *) echo "::error::Unknown cache type '$CACHE_TYPE'."; exit 1 ;;
+        esac
+
     - name: Compute generated-client cache identity
       id: generated-clients-identity
       if: startsWith(inputs.cache-type, 'application-server-') || contains(fromJSON('["webapp-e2e", "server-contracts"]'), inputs.cache-type)

.github/workflows/cd-docs-teardown.yml

@@ -10,6 +10,7 @@ permissions:
 jobs:
   teardown:
     name: Teardown Preview
+    timeout-minutes: 10
     runs-on: ubuntu-latest
     env:
       PREVIEW_URL: ls1intum-hephaestus-docs-pr-${{ github.event.number }}.surge.sh

.github/workflows/cd-docs.yml

@@ -28,6 +28,7 @@ jobs:
   build-preview:
     name: Build (preview)
     if: github.event_name == 'pull_request'
+    timeout-minutes: 15
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -54,6 +55,7 @@ jobs:
   build-production:
     name: Build (production)
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    timeout-minutes: 15
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -81,6 +83,7 @@ jobs:
     name: PR Preview
     needs: build-preview
     if: github.event_name == 'pull_request'
+    timeout-minutes: 10
     runs-on: ubuntu-latest
     env:
       PREVIEW_URL: ls1intum-hephaestus-docs-pr-${{ github.event.number }}.surge.sh
@@ -123,6 +126,7 @@ jobs:
     name: GitHub Pages
     needs: build-production
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    timeout-minutes: 10
     runs-on: ubuntu-latest
     environment:
       name: github-pages

.github/workflows/ci-compose-validate.yml

@@ -22,6 +22,7 @@ permissions:
 jobs:
   validate:
     name: "Render compose stacks"
+    timeout-minutes: 15
     runs-on: ubuntu-latest
     env:
       COMPOSE_ENV_FILES: .env,release-lock.env

.github/workflows/ci-docker-build.yml

@@ -187,6 +187,7 @@ jobs:
       (inputs.webapp_changed != 'true' || inputs.application_server_changed != 'true' ||
        inputs.agent_images_changed != 'true' ||
        inputs.postgres_image_changed != 'true')
+    timeout-minutes: 15
     runs-on: ubuntu-latest
     outputs:
       application-server-published: ${{ steps.tag.outputs.application-server-published }}

.github/workflows/ci-quality-gates.yml

@@ -79,46 +79,49 @@ jobs:
         if: steps.should_run.outputs.run == 'true'
         uses: ./.github/actions/setup-bun
 
-      - name: Setup caches
-        if: steps.should_run.outputs.run == 'true'
+      - name: Setup application-server caches
+        if: steps.should_run.outputs.run == 'true' && matrix.check == 'application-server-quality'
+        uses: ./.github/actions/setup-caches
+        with:
+          cache-type: application-server-quality
+          os: ${{ runner.os }}
+
+      - name: Setup server-contract caches
+        if: steps.should_run.outputs.run == 'true' && matrix.check == 'server-contracts'
         uses: ./.github/actions/setup-caches
         with:
-          cache-type: ${{ matrix.check }}
+          cache-type: server-contracts
           os: ${{ runner.os }}
 
       - name: Application-server formatting + agent runtime + contracts
         if: steps.should_run.outputs.run == 'true' && matrix.check == 'application-server-quality'
         run: |
           bun install --frozen-lockfile
           bun run check:package-manager
+          bun run check:agent-runtime-pins
 
           ISSUES_FOUND=()
-          FMT_OK=true; PMD_OK=true; NULLNESS_OK=true; LINT_OK=true; TESTS_OK=true; TYPES_OK=true; SCRIPT_TYPES_OK=true; CONTRACTS_OK=true; ENV_OK=true; DOCS_OK=true; DIAGRAMS_OK=true; INSTRUCTIONS_OK=true
+          SERVER_OK=true; PMD_CANARY_OK=true; NULLNESS_OK=true; TOOLING_OK=true; TESTS_OK=true; CONTRACTS_OK=true; ENV_OK=true; DOCS_OK=true; DIAGRAMS_OK=true; INSTRUCTIONS_OK=true
 
-          bun run format:java:check || { FMT_OK=false; ISSUES_FOUND+=("Java formatting failed. Run: bun run format:java"); }
+          bun run check:server || { SERVER_OK=false; ISSUES_FOUND+=("Server formatting or PMD failed. Run: bun run check:server"); }
           bun run check:java-nullness \
             || { NULLNESS_OK=false; ISSUES_FOUND+=("Java nullness policy failed. Run: bun run check:java-nullness"); }
-          bun run lint:java || { PMD_OK=false; ISSUES_FOUND+=("PMD found violations. Run: bun run lint:java:report"); }
-          if [ "$PMD_OK" = "true" ] && [ "${{ inputs.pmd_canary }}" = "true" ]; then
+          if [ "$SERVER_OK" = "true" ] && [ "${{ inputs.pmd_canary }}" = "true" ]; then
             PMD_CANARY=server/application/src/main/java/de/tum/cit/aet/hephaestus/Application.java
             cp "$PMD_CANARY" "$RUNNER_TEMP/Application.java"
             trap 'cp "$RUNNER_TEMP/Application.java" "$PMD_CANARY"' EXIT
             sed -i '/public class Application {/a\    private int deliberatelyUnusedPmdCanary;' "$PMD_CANARY"
             if bun run lint:java; then
-              PMD_OK=false
+              PMD_CANARY_OK=false
               ISSUES_FOUND+=("PMD accepted a planted UnusedPrivateField violation; the gate is not analyzing current main sources")
             fi
             cp "$RUNNER_TEMP/Application.java" "$PMD_CANARY"
             trap - EXIT
           fi
-          bun run ci:agents \
-            || { LINT_OK=false; ISSUES_FOUND+=("Lint or formatting failed outside the webapp. Run: bun run check:agents:fix"); }
+          bun run check:agents \
+            || { TOOLING_OK=false; ISSUES_FOUND+=("Repository tooling checks failed. Run: bun run check:agents"); }
           bun run test:agents \
             || { TESTS_OK=false; ISSUES_FOUND+=("Agent runtime test(s) failed. Run: bun run test:agents"); }
-          bun run typecheck:agents \
-            || { TYPES_OK=false; ISSUES_FOUND+=("Agent TypeScript errors. Run: bun run typecheck:agents"); }
-          bun run typecheck:scripts \
-            || { SCRIPT_TYPES_OK=false; ISSUES_FOUND+=("scripts/ TypeScript errors. Run: bun run typecheck:scripts"); }
           bun run check:contracts || { CONTRACTS_OK=false; ISSUES_FOUND+=("Artifact-source contract validation failed. Run: bun run check:contracts"); }
           # Reads server/application.yml against docker/compose.{app,core}.yaml — the deployment that
           # has to deliver each setting. Both sides are behind this job's path filter.
@@ -140,13 +143,11 @@ jobs:
             echo "### App Server Quality" >> $GITHUB_STEP_SUMMARY
             echo "| Check | Status | Fix |" >> $GITHUB_STEP_SUMMARY
             echo "|-------|--------|-----|" >> $GITHUB_STEP_SUMMARY
-            [[ "$FMT_OK" == "false" ]] && echo "| Java formatting | :x: Failed | \`bun run format:java\` |" >> $GITHUB_STEP_SUMMARY
-            [[ "$PMD_OK" == "false" ]] && echo "| Java lint (PMD) | :x: Failed | \`bun run lint:java:report\` |" >> $GITHUB_STEP_SUMMARY
+            [[ "$SERVER_OK" == "false" ]] && echo "| Server formatting and PMD | :x: Failed | \`bun run check:server\` |" >> $GITHUB_STEP_SUMMARY
+            [[ "$PMD_CANARY_OK" == "false" ]] && echo "| PMD canary | :x: Failed | Inspect the planted-violation check |" >> $GITHUB_STEP_SUMMARY
             [[ "$NULLNESS_OK" == "false" ]] && echo "| Java nullness policy | :x: Failed | \`bun run check:java-nullness\` |" >> $GITHUB_STEP_SUMMARY
-            [[ "$LINT_OK" == "false" ]] && echo "| Lint + format (outside webapp) | :x: Failed | \`bun run check:agents:fix\` |" >> $GITHUB_STEP_SUMMARY
+            [[ "$TOOLING_OK" == "false" ]] && echo "| Repository tooling | :x: Failed | \`bun run check:agents\` |" >> $GITHUB_STEP_SUMMARY
             [[ "$TESTS_OK" == "false" ]] && echo "| Agent runtime tests | :x: Failed | \`bun run test:agents\` |" >> $GITHUB_STEP_SUMMARY
-            [[ "$TYPES_OK" == "false" ]] && echo "| Agent typecheck | :x: Failed | \`bun run typecheck:agents\` |" >> $GITHUB_STEP_SUMMARY
-            [[ "$SCRIPT_TYPES_OK" == "false" ]] && echo "| scripts/ typecheck | :x: Failed | \`bun run typecheck:scripts\` |" >> $GITHUB_STEP_SUMMARY
             [[ "$CONTRACTS_OK" == "false" ]] && echo "| Artifact-source contracts | :x: Failed | \`bun run check:contracts\` |" >> $GITHUB_STEP_SUMMARY
             [[ "$ENV_OK" == "false" ]] && echo "| Env delivery by runtime role | :x: Failed | \`bun run check:env\` |" >> $GITHUB_STEP_SUMMARY
             [[ "$INSTRUCTIONS_OK" == "false" ]] && echo "| Agent instruction wiring | :x: Failed | \`bun run check:instructions\` |" >> $GITHUB_STEP_SUMMARY
@@ -165,8 +166,7 @@ jobs:
           cd webapp
 
           ISSUES_FOUND=()
-          LINT_OK=true
-          TYPES_OK=true
+          CLIENT_OK=true
           COMPONENTS_OK=true
           STORIES_OK=true
           SORT_OK=true
@@ -175,12 +175,14 @@ jobs:
           ROUTES_OK=true
           TESTS_OK=true
 
-          bun run check || { LINT_OK=false; ISSUES_FOUND+=("Lint or formatting failed. Run: cd webapp && bun run check:fix"); }
-          bun run typecheck || { TYPES_OK=false; ISSUES_FOUND+=("TypeScript errors found. Run: cd webapp && bun run typecheck"); }
-          bun ../scripts/check-presentational-components.ts || { COMPONENTS_OK=false; ISSUES_FOUND+=("Components must take data as props. Run: bun run check:components"); }
-          bun ../scripts/check-story-prose.ts || { STORIES_OK=false; ISSUES_FOUND+=("Story prose renders HTML paragraphs. Run: bun run check:stories"); }
-          bun ../scripts/check-story-sort.ts || { SORT_OK=false; ISSUES_FOUND+=("Storybook sidebar order is stale. Run: bun run check:story-sort"); }
-          bun ../scripts/check-docs-tokens.ts && bun test ../scripts/check-docs-tokens.test.ts || { TOKENS_OK=false; ISSUES_FOUND+=("The docs site copies a web app colour that has since changed. Run: bun run check:docs-tokens"); }
+          (cd .. && bun run check:client) || {
+            CLIENT_OK=false
+            ISSUES_FOUND+=("Webapp lint, formatting, or typecheck failed. Run: bun run check:client")
+          }
+          (cd .. && bun run check:components) || { COMPONENTS_OK=false; ISSUES_FOUND+=("Components must take data as props. Run: bun run check:components"); }
+          (cd .. && bun run check:stories) || { STORIES_OK=false; ISSUES_FOUND+=("Story prose renders HTML paragraphs. Run: bun run check:stories"); }
+          (cd .. && bun run check:story-sort) || { SORT_OK=false; ISSUES_FOUND+=("Storybook sidebar order is stale. Run: bun run check:story-sort"); }
+          (cd .. && bun run check:docs-tokens) || { TOKENS_OK=false; ISSUES_FOUND+=("The docs site copies a web app colour that has since changed. Run: bun run check:docs-tokens"); }
           timeout --kill-after=30s 10m bun run test \
             || { TESTS_OK=false; ISSUES_FOUND+=("Unit tests failed. Run: cd webapp && bun run test"); }
 
@@ -195,8 +197,7 @@ jobs:
             echo "### Webapp Quality" >> $GITHUB_STEP_SUMMARY
             echo "| Check | Status | Fix |" >> $GITHUB_STEP_SUMMARY
             echo "|-------|--------|-----|" >> $GITHUB_STEP_SUMMARY
-            [[ "$LINT_OK" == "false" ]] && echo "| Lint + format (oxlint + oxfmt) | :x: Failed | \`cd webapp && bun run check:fix\` |" >> $GITHUB_STEP_SUMMARY
-            [[ "$TYPES_OK" == "false" ]] && echo "| TypeScript | :x: Failed | \`cd webapp && bun run typecheck\` |" >> $GITHUB_STEP_SUMMARY
+            [[ "$CLIENT_OK" == "false" ]] && echo "| Lint, format, and TypeScript | :x: Failed | \`bun run check:client\` |" >> $GITHUB_STEP_SUMMARY
             [[ "$COMPONENTS_OK" == "false" ]] && echo "| Presentational components | :x: Failed | \`bun run check:components\` |" >> $GITHUB_STEP_SUMMARY
             [[ "$STORIES_OK" == "false" ]] && echo "| Story prose | :x: Failed | \`bun run check:stories\` |" >> $GITHUB_STEP_SUMMARY
             [[ "$SORT_OK" == "false" ]] && echo "| Storybook sidebar order | :x: Failed | \`bun run check:story-sort\` |" >> $GITHUB_STEP_SUMMARY

.github/workflows/ci-server-clean-reference.yml

@@ -77,7 +77,7 @@ jobs:
 
       - name: Upload phase profiles
         if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0 # v7.0.1
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: server-phase-reference-${{ github.run_id }}
           path: |

.github/workflows/cicd.yml

@@ -172,6 +172,7 @@ jobs:
 
   workflow-lint:
     name: "Workflow syntax"
+    timeout-minutes: 10
     runs-on: ubuntu-latest
     needs: [detect-changes]
     if: |
@@ -287,6 +288,7 @@ jobs:
 
   all-ci-passed:
     name: "CI Status Gate"
+    timeout-minutes: 10
     runs-on: ubuntu-latest
     permissions:
       actions: read

.github/workflows/cleanup-preview.yml

@@ -9,8 +9,8 @@ on:
 permissions: {}
 
 concurrency:
-  group: hephaestus-preview-lifecycle
-  queue: max
+  group: hephaestus-preview-lifecycle-${{ github.event.pull_request.number }}
+  cancel-in-progress: false
 
 jobs:
   cleanup:

.github/workflows/deploy-locked-compose.yml

@@ -12,6 +12,7 @@ on:
 
 jobs:
   deploy:
+    timeout-minutes: 20
     runs-on: ubuntu-latest
     environment: ${{ inputs.environment }}
     permissions:

.github/workflows/deploy-preview.yml

@@ -28,12 +28,9 @@ jobs:
     # Longer than the budgets inside the scripts (image wait, deploy, reachability), so a run that
     # exceeds them reports a deployment status instead of being cancelled without one.
     timeout-minutes: 40
-    # Serialized: admission counts the previews already holding a slot, so two concurrent runs would
-    # both see room. `queue: max` keeps the backlog instead of cancelling it; each queued run resolves
-    # the pull request's current head, so a burst of pushes collapses into one deployment.
     concurrency:
-      group: hephaestus-preview-lifecycle
-      queue: max
+      group: hephaestus-preview-admission
+      cancel-in-progress: false
     env:
       COOLIFY_URL: ${{ vars.COOLIFY_URL }}
       COOLIFY_APP_UUID: ${{ vars.COOLIFY_APP_UUID }}

.github/workflows/deploy-with-helios.yml

@@ -19,12 +19,15 @@ on:
         required: false
         type: string
 
-# Suggestion: Ensures only one workflow runs at a time for a given environment name
 concurrency: ${{ github.event.inputs.environment_name }}
 
+permissions:
+  contents: read
+  packages: read
+
 jobs:
   deploy-app:
-    uses: ls1intum/.github/.github/workflows/deploy-docker-compose.yml@main
+    uses: ls1intum/.github/.github/workflows/deploy-docker-compose.yml@5f645f96873d8b8b3a9b2e52d06626c71377f7ac # v1.2.0-24-g5f645f9
     with:
       environment: ${{ github.event.inputs.environment_name }}
       docker-compose-file: './docker/compose.app.yaml'

.github/workflows/openapi-autocommit.yml

@@ -25,7 +25,7 @@ jobs:
       - name: Setup caches
         uses: ./.github/actions/setup-caches
         with:
-          cache-type: openapi-validation
+          cache-type: application-server-quality
           os: ${{ runner.os }}
 
       - name: Install dependencies

.github/workflows/pull-request.yml

@@ -12,6 +12,7 @@ on:
 jobs:
   validate-title:
     name: "Validate title"
+    timeout-minutes: 5
     runs-on: ubuntu-latest
     if: ${{ !github.event.pull_request.draft }}
     permissions:
@@ -71,6 +72,7 @@ jobs:
 
   assign-author:
     name: "Assign author"
+    timeout-minutes: 5
     runs-on: ubuntu-latest
     permissions:
       pull-requests: write
@@ -80,6 +82,7 @@ jobs:
 
   labeler:
     name: "Apply labels"
+    timeout-minutes: 5
     runs-on: ubuntu-latest
     permissions:
       contents: read

.github/workflows/reconcile-previews.yml

@@ -1,8 +1,5 @@
 name: Preview reconcile
 
-# Event-driven cleanup can be missed — a run cancelled, a Coolify hiccup, a pull request closed while
-# the lifecycle queue was busy. This sweeps what the events left behind, and joins the same global
-# lifecycle group as deploy and close so admission cannot race reclamation.
 on:
   schedule:
     - cron: "0 4 * * *"
@@ -59,14 +56,12 @@ jobs:
       pull-requests: read
     strategy:
       fail-fast: false
-      # Every job below joins the global preview lifecycle group, so a higher value would only start
-      # runners that immediately queue.
-      max-parallel: 1
+      max-parallel: 5
       matrix:
         pr: ${{ fromJSON(needs.inventory.outputs.previews) }}
     concurrency:
-      group: hephaestus-preview-lifecycle
-      queue: max
+      group: hephaestus-preview-lifecycle-${{ matrix.pr }}
+      cancel-in-progress: false
     runs-on: ubuntu-latest
     timeout-minutes: 8
     env:

.github/workflows/release.yml

@@ -33,6 +33,7 @@ jobs:
       ${{ github.event.workflow_run.conclusion == 'success'
         && github.event.workflow_run.event == 'push'
         && github.event.workflow_run.head_repository.full_name == github.repository }}
+    timeout-minutes: 15
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -137,6 +138,7 @@ jobs:
   tag-images:
     needs: release
     if: needs.release.outputs.released == 'true'
+    timeout-minutes: 30
     runs-on: ubuntu-latest
     permissions:
       packages: write
@@ -411,6 +413,7 @@ jobs:
   publish-release:
     needs: [release, tag-images]
     if: needs.release.outputs.released == 'true'
+    timeout-minutes: 20
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -557,6 +560,7 @@ jobs:
   deploy-production:
     needs: [release, deploy-staging]
     if: needs.release.outputs.released == 'true'
+    timeout-minutes: 10
     runs-on: ubuntu-latest
     steps:
       - name: Trigger Production Deploy

.github/workflows/reusable-docker-build.yml

@@ -67,6 +67,7 @@ jobs:
     strategy:
       fail-fast: true
       matrix: ${{ fromJSON(inputs.single-arch && '{"include":[{"platform":"linux/amd64","runner":"ubuntu-24.04"}]}' || '{"include":[{"platform":"linux/amd64","runner":"ubuntu-24.04"},{"platform":"linux/arm64","runner":"ubuntu-24.04-arm"}]}') }}
+    timeout-minutes: 45
     runs-on: ${{ matrix.runner }}
     permissions:
       contents: read
@@ -307,6 +308,7 @@ jobs:
 
   merge:
     name: Create manifest
+    timeout-minutes: 30
     runs-on: ubuntu-latest
     needs: build
     if: ${{ !inputs.single-arch }}

.github/workflows/version-pr.yml

@@ -31,6 +31,7 @@ permissions: {}
 
 jobs:
   version-pr:
+    timeout-minutes: 15
     runs-on: ubuntu-latest
     permissions:
       contents: write