Merge chore/portfolio-hardening: CI, tooling, execution-based evaluation oracle, honest cross-model results

Portfolio-hardening pass across 5 workstreams:
- WS1: CI (GitHub Actions), LICENSE, ruff/mypy/pre-commit tooling, shared
  test fixtures, professional README + Makefile
- WS2: execution-based ground truth oracle replacing broken exact-string
  matching, real cross-model evaluation run (llama3.2 + qwen3:8b)
- WS3: unified DB base, non-blocking API threadpool config, documented
  in-memory store limitations
- WS4: verification scope reference doc
- WS5: case study + architecture diagram

Real cross-model run findings documented honestly in
docs/PHASE_3_METHODOLOGY.md and README: llama3.2 completed the full
benchmark with meaningful accuracy/precision/recall for the first time;
qwen3:8b was not reliably runnable on available hardware (timeouts,
one server crash) -- reported as a real finding, not hidden.

Author: Juanpacol

.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Lint, type-check, test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # 3.9 matches requires-python / the environment this project is
+        # actually developed against; 3.11 is checked too since several
+        # newer stdlib/typing features are used and assumed compatible.
+        python-version: ["3.9", "3.11"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint (ruff check)
+        run: ruff check src/ tests/
+
+      - name: Format check (ruff format)
+        run: ruff format --check src/ tests/
+
+      - name: Type check (mypy)
+        run: mypy src/verityai
+
+      - name: Test with coverage
+        run: pytest tests/ --cov=verityai --cov-report=term-missing --cov-report=xml --cov-fail-under=85
+
+      - name: Upload coverage
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-${{ matrix.python-version }}
+          path: coverage.xml
+          retention-days: 14
+
+  docker:
+    name: Docker build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build image
+        run: docker build -t verityai:ci .
+
+      - name: Smoke test the image
+        run: |
+          docker run -d --name verityai-ci-smoketest -p 18000:8000 verityai:ci
+          for i in $(seq 1 15); do
+            if curl -sf http://localhost:18000/health; then break; fi
+            sleep 1
+          done
+          curl -sf http://localhost:18000/health
+          curl -sf -o /dev/null http://localhost:18000/dashboard
+          docker logs verityai-ci-smoketest
+          docker stop verityai-ci-smoketest

.pre-commit-config.yaml

@@ -0,0 +1,41 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    # Pinned to match the mypy version this project's [tool.mypy] config is
+    # actually validated against (see pyproject.toml's dev deps) -- an
+    # older mypy here previously produced spurious errors on z3 arithmetic
+    # operators that the real (newer) mypy doesn't raise.
+    rev: v1.19.1
+    hooks:
+      - id: mypy
+        # mypy's pre-commit hook runs in an isolated venv with ONLY these
+        # packages -- it does not see the project's real dependencies
+        # unless listed here too. Missing z3-solver in particular causes
+        # spurious operator-type errors on Z3 expressions that a normal
+        # `mypy src/verityai` run (with the project's venv active) does
+        # not produce.
+        additional_dependencies:
+          - pydantic>=2.0.0
+          - types-requests
+          - z3-solver>=4.12.2
+          - sqlalchemy>=2.0.0
+          - fastapi>=0.100.0
+          - neo4j>=5.15.0
+        args: [src/verityai]
+        pass_filenames: false
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+        args: [--maxkb=1000]
+      - id: check-merge-conflict

CLAUDE.md

@@ -3,7 +3,7 @@
 ## Overview
 
 VerityAI is a neuro-symbolic code verification system that:
-1. Generates code using Ollama (llama2:13b) with dynamic context from a Knowledge Graph
+1. Generates code using Ollama (model-agnostic; `llama3.2` is the local default, `llama2:13b` the original aspirational target — see README's "Model-agnostic by design") with dynamic context from a Knowledge Graph
 2. Verifies it formally using Z3 Theorem Prover + symbolic reasoning
 3. Retries up to 3 times if verification fails (injecting the failure reason into the prompt)
 4. Returns code + reasoning trace + confidence score
@@ -26,7 +26,7 @@ VerityAI is a neuro-symbolic code verification system that:
 ├─────────────────────────────────────────────────────┤
 │ 2. KNOWLEDGE   → Neo4j (patterns, rules, examples)   │
 ├─────────────────────────────────────────────────────┤
-│ 1. NEURAL      → Ollama (llama2:13b) + prompts       │
+│ 1. NEURAL      → Ollama (model-agnostic) + prompts   │
 └─────────────────────────────────────────────────────┘
 ```
 
@@ -184,8 +184,10 @@ cp .env.example .env
 # 3. Start services
 docker-compose -f docker/docker-compose.yml up -d
 
-# 4. Pull the model (takes ~5-10 min, ~7.4GB)
-docker-compose -f docker/docker-compose.yml exec ollama ollama pull llama2:13b
+# 4. Pull a model -- llama3.2 is small/fast and needs no special hardware;
+#    swap for llama2:13b or any other Ollama model (this project is
+#    model-agnostic, see README)
+docker-compose -f docker/docker-compose.yml exec ollama ollama pull llama3.2
 
 # 5. Verify services are healthy
 docker-compose -f docker/docker-compose.yml ps
@@ -231,7 +233,7 @@ pytest tests/
 
 ## Contact / Questions
 
-Juan Pablo Botero Espinosa  
+Juan Pablo Botero Espinosa
 juanpabloboteroespinosa@gmail.com
 
 Generated with Claude Code (Claude Fable + Sonnet for architecture review)

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Juan Pablo Botero Espinosa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,29 @@
+.PHONY: test lint format typecheck docker-build serve clean
+
+# python3 -m ... rather than bare `ruff`/`mypy`/`pytest`: those tools land in
+# user site-packages (not necessarily on PATH) when installed via
+# `pip install -e ".[dev]"` without a venv, which is exactly how this
+# project's dev environment was set up.
+test:
+	python3 -m pytest tests/ --cov=verityai --cov-report=term-missing --cov-fail-under=85
+
+lint:
+	python3 -m ruff check src/ tests/
+	python3 -m ruff format --check src/ tests/
+
+format:
+	python3 -m ruff check --fix src/ tests/
+	python3 -m ruff format src/ tests/
+
+typecheck:
+	python3 -m mypy src/verityai
+
+docker-build:
+	docker build -t verityai:latest .
+
+serve:
+	python3 -m uvicorn verityai.api.rest:app --reload --host 0.0.0.0 --port 8000
+
+clean:
+	find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+	rm -rf .pytest_cache .mypy_cache .ruff_cache .coverage coverage.xml