Extend preflight logic: less focus on pinned commit hashes

[jmsexton03]

Summary

• Implements state-aware ERF commit mismatch preflight behavior in src/first_run.py.
• ERF_COMMIT_MISMATCH is now non-blocking (warning) only when compatibility is verified (actual commit is indexed and schema is not stale); otherwise remains blocking (error).
• Adds payload fields to mismatch issues: compatibility_verified, indexed_for_actual_commit, schema_stale.
• Extracts helper seams for testability and robustness:
  • _find_schema_candidates(...)
  • _assess_erf_commit_compatibility(...)
• Adds defensive Path normalization in _erf_path.
• Updates ERF/demo docs for current preflight behavior and --force-rebuild setup guidance.

Related or overlapping functionality / DRY guidance

• Reuses existing schema staleness and indexed-commit provenance checks; avoids duplicating compatibility logic by centralizing in _assess_erf_commit_compatibility.
• No new non-optional node arguments; no graph-state canonical contract changes.
• Coverage was extended with targeted unit + integration tests for mismatch decision boundaries and fallback/error-handling seams.
• This embeds a significant architectural decision that needs an ADR.

Impact checklist

• fixes a bug or incorrect behavior
• adds new capabilities
• changes answers in the test suite to more than roundoff level
• likely affects downstream users or results
• includes docs updates (code/docs), if appropriate
• none of the above

Tests run (CI runs: pytest tests/unit, pytest tests/quality, pytest tests/integration -m "integration_l1 or integration_l2 or integration_l3 or integration_l4 or integration_full")

• tests/unit: pytest tests/unit
• tests/quality: pytest tests/quality
• integration ladder (CI): pytest tests/integration -m "integration_l1 or integration_l2 or integration_l3 or integration_l4 or integration_full"
• other (list):
  • pytest -q --cov=src.first_run --cov-branch tests/unit/test_first_run_preflight_state_aware.py tests/integration/test_first_run_main_hook_integration_state_aware_integration.py --cov-report=term-missing
  • pytest -q tests/unit/test_first_run_preflight_state_aware.py tests/integration/test_first_run_main_hook_integration_state_aware_integration.py
  • pytest -q tests/unit/ tests/integration/
• Output/summary:
  • Targeted preflight gate: 34 passed, 0 failed
  • Full regression: 1898 passed, 81 skipped, 11 xfailed, 0 failed
• If tests require repos/schemas/indices or real services, note markers used.
  • N/A for the targeted contract/integration tests used for this change.
• requires_solver(...) implies repo + schema + default indices are available locally.
• Use -k pelec|erf|amrex|warpx to filter solver-specific tests.

Tests not run in CI (required if any)

• CI runs tests/unit, tests/quality, and tests/integration with integration_l1..l4 + integration_full markers via micromamba; list anything else not covered by CI here.
• None
• tests/e2e
• other (list):
• Reason for skip:
• Risk/mitigation:

API-key/manual tests (optional, include steps)

• Env vars or credentials needed: N/A
• Manual steps/commands: N/A
• Results or logs: N/A

Integration/E2E markers (optional, manual, may require API key)

• Note: integration ladder runs in CI; tests/e2e runs only when selected by path or -m e2e.
• e2e demo (workflow_dispatch): pytest -m "e2e and demo" tests/e2e/test_demo_smoke.py
• other (markers: use_real_services, requires_repos, requires_schema):

Notes (optional)

• Manual output / logs (short):
  • Branch intentionally excludes net database/faiss/** artifact diffs.
• Known limitations:

Labels (optional)

• [] I will check auto-labels after submitting.
• Labels are okay if slightly off.

Maintainability note (optional)

• Compatibility decision and fallback paths were extracted into focused helpers to keep preflight behavior testable and reduce duplicated branching logic.