develop -> main

.claude/commands/headers.md

@@ -0,0 +1,66 @@
+---
+description: Add the Apache 2.0 copyright header to new/changed source files that are missing it
+allowed-tools: Bash(git:*), Read, Edit, Grep
+---
+
+CLAUDE.md requires every source file to carry the Apache 2.0 copyright header, but **nothing
+in CI or pre-commit enforces it**. This command finds source files missing the header and adds it.
+
+The canonical header for FLIP-authored files uses this exact owner string. **Match the
+year convention already used by neighbouring files in the same directory**: the predominant
+existing style is the **dateless** form shown below (`Copyright (c) Guy's and St Thomas' ...`),
+so default to dateless; only include a year if the surrounding files in that directory
+consistently carry one, and in that case copy their year rather than stamping the current
+year. Do not "correct" the year on files that already have a header — leave existing headers
+untouched (see step 2).
+
+**Hash-comment languages** (`.py`, `.sh`, `.yml`, `.yaml`, `Dockerfile`, `Makefile`, `.toml`):
+```
+# Copyright (c) Guy's and St Thomas' NHS Foundation Trust & King's College London
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#     http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+```
+
+**C-style block-comment languages** (`.ts`, `.js`, `.vue`, `.css`):
+```
+/*
+ * Copyright (c) Guy's and St Thomas' NHS Foundation Trust & King's College London
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+```
+
+Steps:
+
+1. **Determine the file set.** Default to files this branch actually added/changed. Diff
+   against the **merge-base** (not `develop` directly) so files changed on `develop` since
+   the branch was cut are excluded:
+   ```
+   git diff --name-only --diff-filter=ACMR "$(git merge-base HEAD origin/develop)"
+   git status --porcelain
+   ```
+   If the user passed paths in `$ARGUMENTS`, use those instead. Restrict to source files in the languages above; skip vendored/generated files (e.g. anything carrying a `Copyright (c) 2026 Flower Labs GmbH` header — leave third-party headers untouched), lockfiles, JSON, Markdown, and `required_files.json`.
+
+2. **Check each file** for an existing copyright header (Grep for `Copyright (c)` in the first ~15 lines). Skip files that already have one.
+
+3. **Insert the matching header** for files that are missing it, using Edit:
+   - Preserve any shebang (`#!/usr/bin/env ...`) or encoding line as the **first** line — insert the header immediately after it.
+   - For `.vue` files, the header goes at the very top of the file (before `<template>`/`<script>`).
+   - Otherwise insert at the very top.
+
+4. **Report** the list of files you added headers to, and any you skipped (already had one / vendored / unsupported type). Do not commit — leave staging to the user.

.claude/commands/migration.md

@@ -0,0 +1,38 @@
+---
+description: Generate a flip-api Alembic migration for model changes and verify the drift guard
+argument-hint: "<short description of the schema change>"
+allowed-tools: Bash(make:*), Bash(git:*), Read, Edit
+---
+
+You are creating a database migration for **flip-api**. CLAUDE.md makes this a hard rule:
+any schema-affecting change to `flip-api/src/flip_api/db/models/*.py` **must** ship an
+Alembic revision in the same change, or the integration drift guard
+(`flip-api/tests/integration/test_migrations.py`) fails.
+
+The change description is: **$ARGUMENTS**
+
+Do the following, stopping to report if any step fails:
+
+1. **Confirm there is a model change to capture.** Diff against the **merge-base** (not `develop` directly) so model changes merged into `develop` after this branch was cut don't show up as false positives: `git diff --stat "$(git merge-base HEAD origin/develop)" -- flip-api/src/flip_api/db/models/` (also check the unstaged working tree). If nothing under `db/models/` changed, warn the user that a migration may not be needed and ask whether to continue anyway.
+
+2. **Generate the revision.** Run:
+   ```
+   make -C flip-api migration MESSAGE="$ARGUMENTS"
+   ```
+   This requires `flip-db` to be up (it runs alembic inside the service container). If it fails because the DB isn't running, tell the user to `make central-hub` (or `make up`) first.
+
+3. **Review the generated revision.** Find the new file under `flip-api/src/flip_api/db/migrations/versions/` (the most recently created one) and Read it. Check that:
+   - the autogenerated `upgrade()` / `downgrade()` match the intended change and nothing spurious was captured (e.g. unrelated type changes from a stale DB),
+   - the `down_revision` chains onto the current head,
+   - the Apache 2.0 copyright header is present (run `/headers` if not).
+   Summarise what the migration does for the user.
+
+4. **Run the drift guard** to prove models and migrations agree:
+   ```
+   make -C flip-api integration_test
+   ```
+   (or, if you want to scope it, run just `tests/integration/test_migrations.py`). Report pass/fail.
+
+5. **Remind** the user to `git add` both the model change and the new revision together, and to commit with `-s` (DCO sign-off).
+
+Do not edit the migration's logic unless the user asks — Alembic autogenerate is the source of truth; only fix the header or obviously wrong autogen artifacts after confirming with the user.

.claude/commands/test-both-backends.md

@@ -0,0 +1,40 @@
+---
+description: Run the full e2e smoke lifecycle on both FL backends (flower then nvflare), reusing the project to pull DICOM only once
+allowed-tools: Bash(make:*), Bash(docker:*), Read
+---
+
+Drive the end-to-end smoke test (`make e2e_smoke`) across **both** FL backends in one go.
+This is the scripted full-lifecycle check (create project → cohort query → image pull → FL
+training → download results) and is **not** run in CI. It is heavy and long-running, so run
+the smoke steps in the **background** and report each backend's result.
+
+Use the documented backend-switch trick so the ~6-min DICOM image pull happens only **once**:
+pull on the first backend, then reuse the same approved project on the second.
+
+**Preconditions (check first, do not skip):**
+- The stack must be running: `make up` (central hub + trusts + XNAT), trusts registered, Orthanc seeded. If it's not up, stop and tell the user to start it — do not try to `make up` yourself (it needs AWS access and is slow).
+- If the user is testing branch code, the running containers must carry it. Remind them that the stack serves published images unless rebuilt (`make build-fl FL_BACKEND=<backend>` or the fast fl-api-only path), and they can confirm with `docker exec flip-fl-api-net-1 cat fl_api/utils/upload.py`.
+
+**Steps:**
+
+1. **Backend 1 — Flower (does the image pull).** Run in the background:
+   ```
+   make e2e_smoke FL_BACKEND=flower
+   ```
+   Watch the output for the `project_id=<UUID>` printed near the start — **capture it**; you need it for step 3. Wait for completion and report pass/fail. (Tutorial files default to `fl-tutorials/flower/xray_classification/` for this backend.)
+
+2. **Switch the stack to NVFLARE** without disturbing the pulled DICOM (`restart-fl` leaves Orthanc/XNAT untouched):
+   ```
+   make restart-fl FL_BACKEND=nvflare DOCKER_FL_REGISTRY= DOCKER_FL_TAG=dev
+   ```
+   (Drop `DOCKER_FL_REGISTRY=`/`DOCKER_FL_TAG=dev` if the user is running published images rather than locally-built `:dev` images — ask if unsure.)
+
+3. **Backend 2 — NVFLARE (reuses the project, skips re-pull).** Run in the background:
+   ```
+   make e2e_smoke FL_BACKEND=nvflare EXTRA_ARGS="--project-id <UUID-from-step-1>"
+   ```
+   The `--project-id` override skips cohort submission + approval and the image-pull wait returns immediately because the studies are already pulled. Report pass/fail.
+
+4. **Summarise**: a clear PASS/FAIL line per backend, and surface any error output from a failed run. If the user passed extra flags in `$ARGUMENTS` (e.g. `--abort-midway`, custom `MODEL_FILES_DIR`/`QUERY_FILE`), thread them into the `EXTRA_ARGS`/make vars of both runs.
+
+Note: if the first run fails before printing a `project_id`, stop and report — don't proceed to the switch.

.claude/hooks/session-start.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Copyright (c) 2026 Guy's and St Thomas' NHS Foundation Trust & King's College London
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#     http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+#
+# FLIP SessionStart hook: make a fresh Claude Code session (especially on the web)
+# ready to test/lint. Best-effort only — it must never fail the session, so every
+# step is guarded and the script always exits 0. Output is surfaced to Claude as
+# session context.
+
+set +e
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$REPO_ROOT" || exit 0
+
+echo "== FLIP session bootstrap =="
+
+# 1. Install pre-commit hooks (TruffleHog, detect-secrets, uv-lock, header/env checks).
+if command -v pre-commit >/dev/null 2>&1; then
+  if [ ! -f .git/hooks/pre-commit ]; then
+    pre-commit install >/dev/null 2>&1 && echo "pre-commit: hooks installed" || echo "pre-commit: install skipped"
+  else
+    echo "pre-commit: already installed"
+  fi
+else
+  echo "pre-commit: not on PATH (run 'pip install pre-commit' to enable commit-time guards)"
+fi
+
+# 2. Sync uv environments for the Python services this branch touched, so tests/linters
+#    (ruff + mypy + pytest) can run immediately. Bounded + quiet; never blocks on network.
+BASE="$(git merge-base HEAD origin/develop 2>/dev/null || echo develop)"
+CHANGED_DIRS="$(git diff --name-only "$BASE" 2>/dev/null | grep -E '\.(py|toml)$' \
+  | sed -E 's#/[^/]+$##' | sort -u)"
+
+declare -A SYNCED
+if command -v uv >/dev/null 2>&1; then
+  for d in $CHANGED_DIRS; do
+    # walk up to the nearest dir containing a pyproject.toml
+    p="$d"
+    while [ -n "$p" ] && [ "$p" != "." ]; do
+      if [ -f "$p/pyproject.toml" ]; then
+        if [ -z "${SYNCED[$p]}" ]; then
+          SYNCED[$p]=1
+          ( cd "$p" && timeout 120 uv sync --quiet >/dev/null 2>&1 ) \
+            && echo "uv sync: $p ✓" || echo "uv sync: $p (skipped/timeout)"
+        fi
+        break
+      fi
+      p="$(dirname "$p")"
+    done
+  done
+  [ ${#SYNCED[@]} -eq 0 ] && echo "uv sync: no changed Python projects on this branch"
+else
+  echo "uv: not on PATH"
+fi
+
+# 3. Report uv.lock drift so a forgotten 'make lock' surfaces before CI blocks the PR.
+DRIFT="$(git status --porcelain '*uv.lock' 2>/dev/null)"
+if [ -n "$DRIFT" ]; then
+  echo "uv.lock drift detected (run 'make lock' and stage the changes):"
+  echo "$DRIFT" | sed 's/^/  /'
+fi
+
+echo "== bootstrap done =="
+exit 0

.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.sh\"",
+            "timeout": 180
+          }
+        ]
+      }
+    ]
+  }
+}