diff --git a/justfile b/justfile
new file mode 100644
index 0000000..2e654a2
--- /dev/null
+++ b/justfile
@@ -0,0 +1,87 @@
+# harness-python-react — task runner. Run `just` to list recipes.
+#
+# Why a justfile: the README and DEVELOPMENT.md document the same commands
+# in prose; a justfile makes them executable. `just check` is the canonical
+# pre-push gate — it runs the same suite the CI `Lint & Format`, `Type Check`,
+# `Architecture (import-linter)`, and `Unit tests` jobs do, in the same order,
+# so a green local run is a high-confidence predictor of a green PR.
+#
+# Conventions:
+# - Recipes wrap shell commands; no Python in here.
+# - Backend recipes live at the top; frontend recipes at the bottom; release
+#   tooling (image build, tag) is kept out — see .github/workflows/release.yml.
+# - All recipes echo a one-line banner so a long `just check` run is readable.
+# - `uv run --frozen` everywhere — bare `uv run` silently re-resolves when
+#   pyproject.toml drifts from uv.lock. `--frozen` aborts loudly instead.
+
+# Default: list available recipes.
+default:
+    @just --list
+
+# Start the full dev stack (app + Jaeger + frontend) via docker compose.
+dev:
+    @echo "==> docker compose up"
+    docker compose up
+
+# Ruff lint + format check (matches the `Lint & Format` CI job).
+lint:
+    @echo "==> ruff check ."
+    uv run --frozen ruff check .
+    @echo "==> ruff format --check ."
+    uv run --frozen ruff format --check .
+
+# Auto-fix ruff lint and reformat in place.
+fmt:
+    @echo "==> ruff check --fix"
+    uv run --frozen ruff check --fix .
+    @echo "==> ruff format"
+    uv run --frozen ruff format .
+
+# Mypy strict (matches the `Type Check` CI job).
+typecheck:
+    @echo "==> mypy src/ tests/"
+    uv run --frozen mypy src/ tests/
+
+# Fast unit tests (matches the `Unit tests` CI job).
+test:
+    @echo "==> pytest tests/ -m 'not integration'"
+    uv run --frozen pytest tests/ -m "not integration"
+
+# Integration tests against real external systems (matches `Integration tests` CI).
+test-integration:
+    @echo "==> pytest tests/ -m integration"
+    uv run --frozen pytest tests/ -m integration
+
+# Coverage on the full suite (matches the `Coverage` CI job).
+coverage:
+    @echo "==> pytest tests/ --cov=src --cov-report=term-missing"
+    uv run --frozen pytest tests/ --cov=src --cov-report=term-missing
+
+# Eval harness against the configured LLM provider (NOT a CI gate — requires API credentials).
+eval:
+    @echo "==> pytest eval/"
+    uv run --frozen pytest eval/
+
+# Boundary contract enforcement (matches `Architecture (import-linter)` CI).
+architecture:
+    @echo "==> lint-imports"
+    uv run --frozen lint-imports
+
+# Run the pre-commit suite against every file.
+pre-commit:
+    @echo "==> pre-commit run --all-files"
+    uv run --frozen pre-commit run --all-files
+
+# One-command pre-push gate — lint + typecheck + architecture + test, in CI order.
+check: lint typecheck architecture test
+    @echo "==> all checks passed"
+
+# Frontend quality gate (matches `Frontend Quality` CI: eslint + prettier + tsc + vitest).
+frontend-check:
+    @echo "==> npm run lint / format:check / check / test"
+    cd frontend && npm run lint && npm run format:check && npm run check && npm run test
+
+# Build the production Docker image locally (Dockerfile sanity check).
+docker-build:
+    @echo "==> docker build -t harness-python-react:dev ."
+    docker build -t harness-python-react:dev .