chore(ci): add Makefile, README test docs, run ruff in CI; remove .venv_ci

Author: SDLC Bot

.github/workflows/python-test.yml

@@ -34,6 +34,10 @@ jobs:
           python -m pip install --upgrade pip
           pip install -r requirements.txt
           pip install pytest pytest-cov mypy
+      - name: Run ruff (lint)
+        run: |
+          python -m pip install ruff
+          python -m ruff check src/
       - name: Run unit tests with coverage
         run: |
           PYTHONPATH=. pytest --cov=src/ --cov-report=xml

Makefile

@@ -0,0 +1,16 @@
+.PHONY: test lint clean
+
+# Run tests using the reproducible script (creates .venv_ci)
+test:
+	./scripts/run-tests.sh
+
+# Run lint and static checks
+lint:
+	# Fast lint with ruff and type check with mypy
+	python3 -m pip install --upgrade pip
+	pip install ruff mypy
+	python3 -m ruff check src/
+	python3 -m mypy src/ --ignore-missing-imports
+
+clean:
+	rm -rf .venv_ci

README.md

@@ -145,6 +145,29 @@ Documentation](https://github.com/SoftwareDevLabs).
 - `README.md` – Project overview and usage  
 - `Dockerfile` – Container build instructions  
 
+## Running tests
+
+We provide a small helper script that creates an isolated virtualenv and runs the test suite.
+
+Run the full test suite locally:
+
+```bash
+./scripts/run-tests.sh
+```
+
+Or run just the deepagent tests (fast):
+
+```bash
+./scripts/run-tests.sh test/unit -k deepagent
+```
+
+You can also use the Makefile targets:
+
+```bash
+make test
+make lint
+```
+
 ---
 
 ## Contributing