Add migration stage 1 contracts and AI harness

[anth-volk]

Fixes #3636

Summary

Adds stage 1 of the API v2 migration: a no-behavior-change preparation layer that makes later migration PRs safer to review and cut over incrementally. This stage establishes route/workflow contracts, source-selection flags, migration-context logging, baseline capture, and a broader model-agnostic AI harness for future engineering work.

What this stage includes

• Adds typed migration route metadata and no-op source/traffic flags.
• Adds structured migration-context request logging to the Flask app.
• Adds typed app-v2 workflow contract registry and API v1 contract tests.
• Adds current simulation gateway contract tests.
• Adds opt-in baseline capture tooling for API route request metrics and simulation completion metrics.
• Adds model-agnostic agent guidance adapters for Codex, Claude, and Copilot.
• Adds canonical AI-facing migration/testing/PR skills under docs/engineering/skills/.
• Adds generated migration contract artifacts in JSON and Markdown, plus a guard that fails when they drift from the registries.
• Adds a stage 1 baseline runbook and changelog entry.

What this stage does not include

• It does not shift production traffic.
• It does not add FastAPI routes.
• It does not add Cloud Run deployment.
• It does not migrate schema/storage to SQLAlchemy, Alembic, or Supabase.
• It does not change the public API contract.

Testing

• ruff format --check . -> passed
• python scripts/run_quality_guards.py -> passed
• python scripts/export_migration_contracts.py -> passed
• FLASK_DEBUG=1 python -m pytest tests/unit/test_migration_contract_artifacts.py tests/contract/test_app_v2_workflow_contracts.py -q -> 5 passed
• FLASK_DEBUG=1 python -m pytest tests/unit/test_migration_flags.py tests/unit/routes/test_migration_context_logging.py tests/unit/test_capture_migration_baseline.py tests/unit/test_migration_contract_artifacts.py tests/unit/libs/test_simulation_api_modal.py tests/contract -q -> 87 passed, 1 existing warning
• ruff check policyengine_api/migration_registry.py tests/unit/test_migration_flags.py scripts/__init__.py scripts/guards/__init__.py scripts/export_migration_contracts.py scripts/run_quality_guards.py scripts/guards/migration_contracts.py tests/unit/test_migration_contract_artifacts.py -> passed

Lint note

• ruff check . currently reports pre-existing lint issues across untouched modules; it is not part of the existing PR CI signal. This PR's new and changed files pass targeted Ruff lint, and full-repo Ruff format now passes.

[codecov]

Codecov Report

❌ Patch coverage is 87.82609% with 14 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.66%. Comparing base (9b249e5) to head (71b6a2c).
⚠️ Report is 10 commits behind head on master.

Files with missing lines	Patch %	Lines
policyengine_api/migration_flags.py	87.83%	5 Missing and 4 partials ⚠️
policyengine_api/migration_logging.py	88.88%	2 Missing and 1 partial ⚠️
policyengine_api/migration_registry.py	81.81%	0 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #3637      +/-   ##
==========================================
+ Coverage   78.01%   78.66%   +0.65%     
==========================================
  Files          67       70       +3     
  Lines        4071     4186     +115     
  Branches      759      776      +17     
==========================================
+ Hits         3176     3293     +117     
+ Misses        700      691       -9     
- Partials      195      202       +7     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.