W1---Opportunity-Intelligence/docs/MIGRATION-W1-017.md

W1-017 migration

This increment reorganizes source, tests, records and documentation without adding dependencies, services, source coverage or qualification rules.

Before and after

Previously, application scripts, tests, fixtures, documents and the pipeline were all at the root beside runs/. They now have the following destinations:

Previous path	Current path
discovery.py	src/opportunity_intelligence/collectors/usac.py
lrs_discovery.py	src/opportunity_intelligence/collectors/lrs.py
qualify_lrs.py	src/opportunity_intelligence/qualification/lrs.py
discover_test.py	tests/test_usac.py
discover_dates_test.py	tests/test_usac_dates.py
lrs_test.py	tests/test_lrs.py
qualify_lrs_test.py	tests/test_qualification.py
lrs-sample.html, lrs-listing-sample.html	tests/fixtures/
opportunities.json	data/opportunities.json
inspect_lrs.py	tools/inspect_lrs.py
LRS.md, QUALIFICATION.md	docs/
original README.md	archived as docs/SPRINT0.md
lrs-descriptions.json	runs/2026-09-17/lrs-inspection/lrs-descriptions.json

All original root files were also copied into runs/2026-09-17/w1-017/before/ before edits, since this workspace has no Git metadata. No historical run file was moved or removed. Byte hashes for the 107 existing run files are retained in runs/2026-09-17/w1-017/historical-hashes.json.

Compatibility

Use python w1.py usac, python w1.py lrs, and python w1.py qualify instead of the old root script names. Existing source-specific CLI options remain supported. Use python -m unittest discover -s tests -v instead of old test-module names. The diagnostic command is python tools/inspect_lrs.py.

No compatibility copies of the reviewed pipeline are left at the root. Code uses opportunity_intelligence.paths to locate the canonical file independent of cwd. For direct module use, add src/ to PYTHONPATH; the root runner and test bootstrap already do this without installation. Documentation assumes a source checkout, not an installed wheel. No third-party build or runtime dependencies were added.

Tests now use immutable copies of saved input under tests/fixtures/, rather than depending on the live pipeline or on historical directories being writable. Fixture provenance remains in the copied LRS manifest and original run snapshots.

Qualification output must be byte-equivalent for brief.md, shortlist.json and audit.json. Its summary's rules_sha256 changes because source changed; every other summary field must agree. The rule version remains W1-016-v1.

Readability and exceptions

Expanded compressed statements, added docstrings and explanatory comments, replaced dense ranking/rendering expressions with named helpers, and centralized checkout paths. Source evidence, uncertainty flags and ranking weights remain unchanged. Original files and one-time migration helpers are archived with the refactor evidence; archived historical code is not part of the active package.

Offline CLI replay exposed a pre-existing USAC error: plain UTF-8 decoding rejected the BOM in the reviewed pipeline. The small correction uses utf-8-sig; no records were rewritten. USAC's legacy same-day output overwrite behavior is unchanged and documented; no live USAC execution was performed over history.

git status --short and git rev-parse --show-toplevel reported that this is not a Git repository. No Git initialization or commit was performed.

Verification

python -m unittest discover -s tests -v
python tools/verify_refactor.py

The second command creates a new runs/2026-09-17/w1-017/verification/ directory and refuses to overwrite it. It runs the documented entry points, replays all 87 LRS details and both USAC fixtures against archived implementations, compares qualification artifacts and verifies the reviewed pipeline plus every original run hash. Logs and actual elapsed machine time are in its report.json and command-*.txt. For routine repeat checks after that one-time verification, use the unittest command; it creates temporary outputs and is repeatable.

No fresh network validation is claimed for this structural increment. Human working time is not measured. Completion timing and final test results are reported separately from the historical LRS live-run timing.

Completed verification

The final verification command exited 0. Its suite ran 23 tests, preserving all 20 prior regression cases and adding three refactor-specific checks for USAC CLI output isolation, complete LRS HTTP-response replay, and original brief bytes. The final suite reported 1.794 seconds; the verification process measured 3.875 seconds including command checks and comparisons.

• Both USAC fixtures match the original parser results.
• All 87 LRS detail extractions and index discovery match the original collector.
• LRS CLI offline replay collects 87 jobs: 84 new and 3 pipeline matches.
• Qualification remains 84 input, 47 relevant, 12 shortlisted, 35 deferred; exclusions remain 9 clearly unrelated and 28 outside scope.
• Brief, shortlist and audit bytes match the final W1-016 artifacts exactly.
• All 107 pre-existing run files remain at their original paths with matching SHA-256 hashes.
• Pipeline bytes match the original hash: b68aea9436f835375d4f08a46f09fcc06a13da9280a0de7f7faed63913247e00.
• Final Git status still reports no Git repository; no commit was created.

See verification/report.json for command exit codes, timings and preserved logs. Measured implementation wall-clock interval was approximately 24 minutes (16:59:51–17:23:43 UTC), including tool/approval waits; this is not a measure of human labor or CPU time. No new external dependencies or spending were introduced. W1-017 stops here.