feat(pipeline)!: validate and promote the exact tuned candidate

Author: fmind

.github/workflows/cd.yml

@@ -6,7 +6,24 @@ on:
 permissions:
   contents: read
 jobs:
+  checks:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Install mise toolchain
+        uses: jdx/mise-action@08ae2a091c038e1e05ec6f5115dc5c69d5a2a6b8 # v5.1.2
+        with:
+          cache: false
+      - name: Run release gate
+        run: mise run all
+      - name: Verify no generated changes
+        run: test -z "$(git status --porcelain)" || { git status --porcelain; git diff; exit 1; }
   pages:
+    needs: checks
     runs-on: ubuntu-24.04
     timeout-minutes: 20
     permissions:
@@ -18,54 +35,67 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false # no step pushes back to the repository
       - name: Install mise toolchain
-        uses: jdx/mise-action@v5
+        uses: jdx/mise-action@08ae2a091c038e1e05ec6f5115dc5c69d5a2a6b8 # v5.1.2
         with:
           cache: false # a poisoned tool cache must never reach published artifacts
       - name: Build API documentation
         run: mise run docs
       - name: Configure Pages
-        uses: actions/configure-pages@v6
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
       - name: Upload Pages artifact
-        uses: actions/upload-pages-artifact@v5
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
         with:
           path: docs/
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v5
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
   image:
+    needs: checks
     runs-on: ubuntu-24.04
     timeout-minutes: 30
     permissions:
       contents: read
       packages: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false # the registry login below carries its own token
+      - name: Install mise toolchain
+        uses: jdx/mise-action@08ae2a091c038e1e05ec6f5115dc5c69d5a2a6b8 # v5.1.2
+        with:
+          cache: false
       - name: Set lower-case image path
         # GitHub expands `${{ }}` before the shell runs, so repository references reach
         # the script through `env:` rather than being interpolated into the command.
         env:
           REPOSITORY: ${{ github.repository }}
         run: echo "IMAGE=$(echo "ghcr.io/$REPOSITORY" | tr '[:upper:]' '[:lower:]')" >> "$GITHUB_ENV"
       - name: Log in to GitHub Container Registry
-        uses: docker/login-action@v4
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4
-      - name: Build and push image
-        uses: docker/build-push-action@v7
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
+      - name: Build and push candidate image
+        id: build
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
         with:
           context: .
           push: true
-          tags: |
-            ${{ env.IMAGE }}:latest
-            ${{ env.IMAGE }}:${{ github.ref_name }}
+          tags: ${{ env.IMAGE }}:candidate-${{ github.sha }}
+      - name: Scan candidate image
+        env:
+          IMAGE_REF: ${{ env.IMAGE }}@${{ steps.build.outputs.digest }}
+        run: mise exec -- trivy --config trivy.yaml image --skip-dirs '' --platform linux/amd64 "$IMAGE_REF"
+      - name: Promote verified digest
+        env:
+          IMAGE_REF: ${{ env.IMAGE }}@${{ steps.build.outputs.digest }}
+          VERSION: ${{ github.ref_name }}
+        run: docker buildx imagetools create --tag "$IMAGE:$VERSION" --tag "$IMAGE:latest" "$IMAGE_REF"

.github/workflows/ci.yml

@@ -15,11 +15,11 @@ jobs:
     timeout-minutes: 20
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false # no step pushes back to the repository
       - name: Install mise toolchain
-        uses: jdx/mise-action@v5
+        uses: jdx/mise-action@08ae2a091c038e1e05ec6f5115dc5c69d5a2a6b8 # v5.1.2
         with:
           cache: true
       - name: Run canonical gate

.github/workflows/security.yml

@@ -19,12 +19,12 @@ jobs:
     timeout-minutes: 30
     steps:
       - name: Checkout complete history
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           persist-credentials: false # scanners only read the checkout
       - name: Install mise toolchain
-        uses: jdx/mise-action@v5
+        uses: jdx/mise-action@08ae2a091c038e1e05ec6f5115dc5c69d5a2a6b8 # v5.1.2
       - name: Scan complete Git history
         run: gitleaks git --redact=100 --verbose
       - name: Scan full checkout

.github/zizmor.yml

@@ -4,7 +4,7 @@ Context and rules for AI agents working in this repository. Humans should start
 
 ## Project overview
 
-- **Name**: bikes — a production-shaped MLOps package that predicts the number of bikes available.
+- **Name**: bikes — a production-shaped MLOps package that predicts hourly bike rental demand.
 - **Description**: reference implementation for the [MLOps Coding Course](https://mlops-coding-course.fmind.dev), generated from [cookiecutter-mlops-package](https://github.com/fmind/cookiecutter-mlops-package).
 - **Language**: Python 3.14+ (`pyproject.toml`), managed with `uv`.
 - **Stack**: MLflow (tracking, registry, projects, evaluation), scikit-learn, pandas, Pydantic + Pandera validation, OmegaConf YAML configs, loguru.
@@ -21,7 +21,12 @@ All work goes through `mise` (see `mise.toml`); git hooks (`lefthook.yml`) and C
 - Test: `mise run test` — `pytest` with coverage (fails under 100%); `mise run test:parallel` is a faster, coverage-free local loop.
 - Build: `mise run build` — `uv build` (wheel + sdist); `mise run build:image` builds the Docker image.
 - Docs: `mise run docs` — `pdoc` API reference into `docs/`.
-- MLflow jobs: `mise run project` runs every job; `mise run project:run <name>` runs one (`confs/<name>.yaml`).
+- MLflow jobs: `mise run project` runs the connected `PipelineJob` (tune → train → evaluate → promote → infer → explain); `mise run project:run <name>` runs one (`confs/<name>.yaml`).
+
+## Pipeline invariants
+
+- Training uses the full tuning model configuration plus validated selected parameters. Evaluation, promotion and downstream consumers use the exact registered candidate version. Failed evaluation preserves the champion alias. Standalone promotion requires a positive explicit version.
+- Input datasets and signatures exclude `casual` and `registered`; raw counts remain in `data/hour.csv` for analysis. Retrain historical registered models to adopt the new serving signature.
 
 ## Definition of done
 
@@ -38,9 +43,9 @@ A change is complete only when, locally, `mise run format` is clean, `mise run c
 
 ## Repository layout
 
-- `src/bikes/` — package: `core/` (metrics, models, schemas), `io/` (configs, datasets, registries, services), `jobs/` (tuning, training, promotion, inference, evaluations, explanations), `utils/` (searchers, signers, splitters), plus `settings.py`, `scripts.py`, `__main__.py`.
+- `src/bikes/` — package: `core/` (metrics, models, schemas), `io/` (configs, datasets, registries, services), `jobs/` (pipeline, tuning, training, promotion, inference, evaluations, explanations), `utils/` (searchers, signers, splitters), plus `settings.py`, `scripts.py`, `__main__.py`.
 - `confs/` — one OmegaConf YAML per MLflow job; `tests/` — `pytest` suite mirroring `src/` with fixtures in `conftest.py`.
 - `data/` — bike sharing datasets (Parquet splits and source CSV); `notebooks/` — exploration notebooks (plotly comes from the `notebook` dependency group); `.env.example` — MLflow URIs to copy into `.env`, which `mise.toml` sources.
 - `pyproject.toml` — dependencies and `ruff`/`ty`/`pytest` config; `mise.toml`/`mise.lock` — tasks and pinned, locked tools; `lefthook.yml` — git hooks; `dprint.jsonc`/`trivy.yaml`/`cliff.toml` — formatter, scanner, changelog config.
-- `.github/` — `workflows/` (`ci.yml` runs `mise run all`, `cd.yml` publishes docs and the image, `security.yml` rescans the full history weekly), `dependabot.yml`, `zizmor.yml`, `rulesets/main.json`.
+- `.github/` — `workflows/` (`ci.yml` runs `mise run all`, `cd.yml` runs the gate before publishing docs and promotes a scanned image digest, `security.yml` rescans the full history weekly), `dependabot.yml`, `rulesets/main.json`.
 - `Dockerfile`/`docker-compose.yml`/`MLproject` — container image, local MLflow server, and MLflow Projects reproducible runs (`--env-manager=local` reuses the uv environment, so there is no `python_env.yaml`).

AGENTS.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project are documented in this file.
 
+## [7.0.0] - 2026-10-12
+
+- **Breaking:** training and serving inputs exclude `casual` and `registered`. Retrain historical registered models before sending feature-only inputs.
+- **Breaking:** standalone promotion requires a positive explicit model version; it no longer selects the latest version implicitly.
+- Connect tuning, training, heldout evaluation, promotion, inference and explanations through one exact candidate version. Failed evaluation preserves the champion.
+- Validate strict schemas, row alignment and selected parameters; compute unsigned-target metrics safely.
+- Update locked tools and dependencies, documentation and notebooks. Gate documentation publication and scan immutable images before promoting release tags.
+
 ## [6.1.0] - 2026-10-06
 
 ### 🚀 Features

CHANGELOG.md

@@ -1,7 +1,7 @@
 # syntax=docker/dockerfile:1
 # Multi-stage, non-root image built with uv (https://docs.astral.sh/uv/guides/integration/docker/).
 
-FROM python:3.14-slim AS build
+FROM python:3.14-slim@sha256:a2b82f3c48559aa0a8446d9af49826b6e2b2016f4cd2afabfe6013ec53729170 AS build
 ENV UV_COMPILE_BYTECODE=1
 ENV UV_LINK_MODE=copy
 # Build the venv on the base image's interpreter: `.python-version` would otherwise make
@@ -10,7 +10,7 @@ ENV UV_PYTHON=/usr/local/bin/python3
 ENV UV_PYTHON_DOWNLOADS=never
 WORKDIR /app
 # Pinned, not `:latest` — a floating tag is invisible to Dependabot's docker ecosystem.
-COPY --from=ghcr.io/astral-sh/uv:0.12.23 /uv /uvx /bin/
+COPY --from=ghcr.io/astral-sh/uv:0.13.0 /uv /uvx /bin/
 RUN --mount=type=cache,target=/root/.cache/uv \
   --mount=type=bind,source=uv.lock,target=uv.lock \
   --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
@@ -19,9 +19,13 @@ COPY . /app
 RUN --mount=type=cache,target=/root/.cache/uv \
   uv sync --frozen --no-dev --no-editable
 
-FROM python:3.14-slim
+FROM python:3.14-slim@sha256:a2b82f3c48559aa0a8446d9af49826b6e2b2016f4cd2afabfe6013ec53729170
 ENV PYTHONUNBUFFERED=1
 WORKDIR /app
+# The runtime already contains its dependencies; remove unused pip and its bundled
+# bootstrap wheel so their vendored packages do not add a second dependency stack.
+RUN PIP_ROOT_USER_ACTION=ignore python -m pip uninstall --yes pip \
+  && python -c "import ensurepip, pathlib, shutil; shutil.rmtree(pathlib.Path(ensurepip.__file__).parent)"
 # Fixed numeric uid/gid: stable file ownership across rebuilds and bind mounts, and
 # resolvable by a host that does not share this image's /etc/passwd.
 RUN groupadd -g 10001 app && useradd -u 10001 -g app -m app