docs(audit): correct the Python floor drift and record the 3.14 consistency audit

[mrveiss]

Thinking Path

Asked to "use 3.14 everywhere where possible". Before changing anything I enumerated every Python-version declaration in the repo — CI workflows, .python-version, tool configs, Dockerfiles, Ansible roles and playbooks, runtime sys.version_info checks — and re-measured wheel availability against PyPI rather than trusting the reason recorded in the tracking issue.

The finding that matters: the repo is already on 3.14 nearly everywhere. CI (15 workflows), .python-version, mypy, both Dockerfiles and every Ansible role except the NPU worker are 3.14. So the useful work was not a sweeping bump — it was finding the four places that disagree and the two exceptions whose justification has expired.

This PR carries the audit and the three items with no runtime risk. Everything with blast radius is filed under epic #13743 in dependency order.

The expired premise

#10877 (CLOSED) pinned black's target-version to py312 and the NPU worker to 3.11 because OpenVINO shipped no 3.14 wheels. Measured 2026-08-08:

Package	Latest	Python tags	3.14?
openvino	2026.3.0	cp310, cp311, cp312, cp313, cp314	✅
torch	2.13.0	cp310, cp311, cp312, cp313, cp314	✅
numpy	2.5.1	cp312, cp313, cp314	✅
openvino-dev	2024.6.0	py3-none-any	✅
onnxruntime-openvino	1.24.1	cp311, cp312, cp313	❌ no cp314

The Linux NPU worker needs openvino + torch + numpy and not onnxruntime-openvino. It can move. onnxruntime-openvino is used only by the Windows worker, which stays blocked. Nothing in this PR acts on that — it is recorded so #13747/#13748 start from a measurement instead of a stale assumption.

What Changed

docs/audit/python_314_consistency.md (new) — the full audit: every surface, its declared version, and a verdict. Seven findings, F1–F7, with the recommended order.

autobot-backend/startup_validator.py — the floor read 3.12 while CI, .python-version, mypy, both Dockerfiles and every backend Ansible role read 3.14. This is the only floor a running process enforces, so it is the one a reader trusts. Raised to 3.14. (It also has zero callers — filed separately as #13738; correcting the number and wiring the check are different fixes and both are needed.)

pyproject.toml — the comment justifying target-version = ["py312"] claimed the NPU worker "pins 3.12+". It pins 3.11, and #10877 says 3.11 throughout. The comment understated the very constraint it exists to explain. Corrected, plus the measurement above so the next reader does not re-derive it.

scripts/format.sh — said "project targets py3.12+" and told the user to install black on 3.12, one line after telling them to install it on 3.14. Now names 3.14 as what CI runs, separates running under from target-version (different things — the pin is about emitted syntax), and demotes 3.12/3.13 to a note instead of lumping them with 3.10.

No behaviour change to any shipped code path: one unreached validation constant, one comment, one developer script's messaging.

Verification

$ bash -n scripts/format.sh
format.sh syntax OK

$ python3.12 -c "import tomllib; d=tomllib.load(open('pyproject.toml','rb')); ..."
black target-version: ['py312']
mypy python_version: 3.14
pyproject parses OK

$ python3 -c "import ast; ast.parse(open('autobot-backend/startup_validator.py').read())"
parses OK; floor line: ['if sys.version_info < (3, 14):']

$ bash scripts/format.sh --check autobot-backend/startup_validator.py
1 file would be left unchanged.

format.sh's new branch exercised live — on this box it selects python3.12 and emits the new note rather than the old contradictory advice:

format.sh: NOTE — using Python 3.12; CI formats with 3.14.
  Parses cleanly, but if CI's format check disagrees with a local
  clean run, this gap is the first thing to rule out.

Wheel availability was measured against the PyPI JSON API, not inferred from release notes.

Follow-up, filed not fixed

Checking venv consistency across docker and native surfaced three live defects in deploy-native-services.yml — which SERVICE_MANAGEMENT.md and INFRASTRUCTURE_DEPLOYMENT.md document as the operator entry point, so none are theoretical:

• fix(ansible): NPU play installs from docker/npu-worker/requirements.txt, which does not exist #13744 — installs from docker/npu-worker/requirements.txt, which does not exist in the repo
• fix(ansible): deploy-native-services targets host groups the inventory does not define #13745 — targets host groups npu/aiml; the inventory defines npu_workers/ai_stack. A play matching nothing is skipped silently and reads as success
• fix(ansible): /opt/autobot/venv is built by three producers with two interpreters #13746 — builds the NPU venv into the shared /opt/autobot/venv with 3.11 while two other producers build the same path with 3.14, and the aiml play has no creates: guard

Then the actual moves, in order: #13747 (Linux NPU worker → 3.14), then #13748 (black → py314). Reversing those two writes PEP 758 syntax into shared code a still-3.11 worker cannot parse.

All tracked under epic #13743.

Model Used

Claude Opus 5 (1M context)

Part of #13743

[github-actions]

✅ SSOT Configuration Compliance: Passing

🎉 No hardcoded values detected that have SSOT config equivalents!

[mrveiss]

Review — pre-merge pass

Reviewed against origin/Dev_new_gui at 99c2b5a8. Self-review recorded as a comment (GitHub blocks self-approval).

Runtime effect today: none

The only executable change is one constant in startup_validator._validate_system_requirements, and that function still has zero callers repo-wide — confirmed by grep across .py/.sh/.yml. So this cannot change how anything behaves until #13738 wires the check. Everything else in the diff is comments, a docstring, one message string, and documentation.

Claims I verified rather than asserted

Claim in the diff	Check	Result
"The NPU worker runs its own venv and never imports this module" — the reason a 3.14 floor is safe	Grepped autobot-npu-worker/ and autobot-infrastructure/autobot-npu-worker/ for startup_validator	No hits — a 3.14 floor cannot break the 3.11 worker
install.sh installs 3.14, so GETTING_STARTED's "3.12" was wrong	Read install.sh:397	Installs python3.14 — the doc was wrong
openvino/torch/numpy ship cp314; onnxruntime-openvino does not	PyPI JSON API, per package	Confirmed; recorded with the date so it can be re-checked, not re-argued
format.sh still works after the rewrite	Ran --check on this box	Selects python3.12, emits the new NOTE branch, exits clean

Caught during this review

#13737 (merged earlier today) landed three comments and a user-visible skip-reason string reading "the platform floor is 3.12 (startup_validator._validate_system_requirements)" — citing the exact check this PR raises to 3.14. Merging without addressing it would leave two different floors asserted in the codebase, both citing the same source. That is the drift this PR exists to remove, so it is fixed here in 99c2b5a8 rather than deferred.

The skip reason is the one that mattered: it prints on every skipped test on a sub-floor interpreter, where a stale number reads as fact.

The audit doc's "F2 — The declared runtime floor is 3.12" heading is deliberately not changed — it describes the pre-fix finding.

Scope discipline

Three things were found and deliberately not fixed here, because each has a blast radius this PR does not:

• Three live defects in deploy-native-services.yml → fix(ansible): NPU play installs from docker/npu-worker/requirements.txt, which does not exist #13744, fix(ansible): deploy-native-services targets host groups the inventory does not define #13745, fix(ansible): /opt/autobot/venv is built by three producers with two interpreters #13746
• The Linux NPU worker's 3.11 pin and the black py314 target → build(python): move the Linux NPU worker to 3.14 — OpenVINO now ships cp314 wheels #13747, build(python): bump black target-version to py314 (after the NPU worker moves) #13748, in that order
• The Z-shim whose removal condition passed four minor versions ago → chore(time): the Z-shim migration waits on a Python upgrade that happened four versions ago #13755

Verification

• 23 passed on the 3.14 venv for the scheduler modules touched by the comment fix
• black --check, flake8 --max-line-length=120: clean
• 64 CI checks: 53 success, 10 skipped, 0 failures; all 10 required checks green or path-skipped; all 13 python-suite shards clean

Verdict

No blocking findings.