build: verification scaffolding — ruff + pytest via make check

.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+# CI runs exactly what `make check` runs locally — no CI-only logic
+# (ADR-0003 in predev-brain). Ruff is pinned inside scripts/lint_changed.sh.
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      # Full history: the changed-files diff needs the merge-base with main.
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v10.0.1
+
+      - run: make check

.tool-versions

@@ -0,0 +1,2 @@
+python 3.12
+uv 0.12.3

AGENTS.md

@@ -0,0 +1,23 @@
+# Agent instructions — predev-api
+
+For AI coding agents and humans alike. Two SDKs: `predev-api-python/` and
+`predev-api-node/`. Verification follows ADR-0003 (predev-brain); this
+contract currently covers the python side (node gets its own when touched).
+
+## Verify your changes
+
+- `make check` — before pushing or opening a PR. CI runs exactly this:
+  ruff (lint + format) **only on python files you changed** vs origin/main
+  (the repo is not ruff-clean — 228 findings at baseline — and legacy files
+  are deliberately not your problem), plus the python SDK's pytest suite
+  (24 tests, fast, offline).
+- `make fix` — autofix + format the same changed set.
+- Requires `uv` (`brew install uv` or `mise use uv`); ruff and pytest are
+  fetched automatically, versions pinned in the scripts.
+
+## House rules
+
+- Never push to `main`. Every change is a feature branch + PR.
+- Conventional Commits v1.0.0; one logical change per commit.
+- Do not weaken, skip, or reconfigure checks to get green — fix the code, or
+  stop and escalate to a human.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

Makefile

@@ -0,0 +1,21 @@
+# Verification contract (ADR-0003 in predev-brain). CI runs exactly
+# `make check`, so a local green is a CI green. Requires uv
+# (https://docs.astral.sh/uv/ — `brew install uv` or `mise use uv`); ruff is
+# version-pinned in scripts/lint_changed.sh, pytest deps are declared inline
+# below — nothing else to install.
+.PHONY: check check-changed lint fix test
+
+check: lint test
+
+check-changed: check
+
+lint:
+	bash scripts/lint_changed.sh
+
+fix:
+	bash scripts/lint_changed.sh --fix
+
+# The python SDK's suite (fast, no network). --no-project because the SDK is
+# a setup.py package, not a uv project; requests is its one runtime dep.
+test:
+	cd predev-api-python && uv run --no-project --with pytest --with requests -- pytest tests/ -q

scripts/lint_changed.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Changed-files ruff (ADR-0003 in predev-brain): the repo is not ruff-clean
+# (measured 2026-09-02: 228 lint findings, 10/17 files misformatted), so lint
+# + format are enforced only on python files touched relative to origin/main.
+# Violations in files you touch get fixed in that PR; untouched legacy files
+# are not your problem. `--fix` applies autofixes + formatting to the same set.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+RUFF="uvx ruff@0.16.5"
+
+base=$(git merge-base HEAD origin/main 2>/dev/null || echo "")
+files=$(git diff --name-only --diff-filter=d ${base:+"$base"} -- '*.py')
+if [ -z "$files" ]; then
+  echo "lint: no changed python files"
+  exit 0
+fi
+
+# shellcheck disable=SC2086  # word splitting is intended; no spaces in paths
+if [ "${1:-}" = "--fix" ]; then
+  $RUFF check --fix $files
+  $RUFF format $files
+else
+  $RUFF check $files
+  $RUFF format --check $files
+fi