annotations/.cursor/skills/test-spec/phases/hardware-assessment.md

Hardware-Dependency & Execution Environment Assessment (BLOCKING)

Runs between Phase 3 and Phase 4.

Docker is the preferred test execution environment (reproducibility, isolation, CI parity). However, hardware-dependent projects may require local execution to exercise the real code paths. This assessment determines the right execution strategy by scanning both documentation and source code.

Step 1 — Documentation scan

Check the following files for mentions of hardware-specific requirements:

File	Look for
_docs/00_problem/restrictions.md	Platform requirements, hardware constraints, OS-specific features
_docs/01_solution/solution.md	Engine selection logic, platform-dependent paths, hardware acceleration
_docs/02_document/architecture.md	Component diagrams showing hardware layers, engine adapters
_docs/02_document/components/*/description.md	Per-component hardware mentions
TESTS_OUTPUT_DIR/environment.md	Existing environment decisions

Step 2 — Code scan

Search the project source for indicators of hardware dependence. The project is hardware-dependent if ANY of the following are found:

Category	Code indicators (imports, APIs, config)
GPU / CUDA	import pycuda, import tensorrt, import pynvml, torch.cuda, nvidia-smi, CUDA_VISIBLE_DEVICES, runtime: nvidia
Apple Neural Engine / CoreML	import coremltools, CoreML, MLModel, ComputeUnit, MPS, sys.platform == "darwin", platform.machine() == "arm64"
OpenCL / Vulkan	import pyopencl, clCreateContext, vulkan headers
TPU / FPGA	import tensorflow.distribute.TPUStrategy, FPGA bitstream loaders
Sensors / Cameras	import cv2.VideoCapture(0) (device index), serial port access, GPIO, V4L2
OS-specific services	Kernel modules (modprobe), host-level drivers, platform-gated code (sys.platform branches selecting different backends)

Also check dependency files (requirements.txt, setup.py, pyproject.toml, Cargo.toml, *.csproj) for hardware-specific packages.

Step 3 — Classify the project

Based on Steps 1–2, classify the project:

• Not hardware-dependent: no indicators found → use Docker (preferred default), skip to Step 5 "Record the decision"
• Hardware-dependent: one or more indicators found → proceed to Step 4

Step 4 — Present execution environment choice

Present the findings and ask the user using Choose format:

══════════════════════════════════════
 DECISION REQUIRED: Test execution environment
══════════════════════════════════════
 Hardware dependencies detected:
 - [list each indicator found, with file:line]
══════════════════════════════════════
 Running in Docker means these hardware code paths
 are NOT exercised — Docker uses a Linux VM where
 [specific hardware, e.g. CoreML / CUDA] is unavailable.
 The system would fall back to [fallback engine/path].
══════════════════════════════════════
 A) Local execution only (tests the real hardware path)
 B) Docker execution only (tests the fallback path)
 C) Both local and Docker (tests both paths, requires
    two test runs — recommended for CI with heterogeneous
    runners)
══════════════════════════════════════
 Recommendation: [A, B, or C] — [reason]
══════════════════════════════════════

Step 5 — Record the decision

Write or update a "Test Execution" section in TESTS_OUTPUT_DIR/environment.md with:

1. Decision: local / docker / both
2. Hardware dependencies found: list with file references
3. Execution instructions per chosen mode:
   • Local mode: prerequisites (OS, SDK, hardware), how to start services, how to run the test runner, environment variables
   • Docker mode: docker-compose profile/command, required images, how results are collected
   • Both mode: instructions for each, plus guidance on which CI runner type runs which mode

The decision is consumed by Phase 4 to choose between local scripts/run-tests.sh and docker-compose.test.yml.