W1---Opportunity-Intelligence/README.md

W1 — Opportunity Intelligence

Public-source USAC and LRS collection, with deterministic offline qualification. Research only: no applications, outreach, purchases or external commitments. Ken reviews candidates and approves any promotion or subsequent external action.

Python 3.10+; standard library only. No installation or dependencies are required. Run the commands below from the repository root. On this Windows workstation, python is not on PATH; use the installed interpreter:

$w1Python = 'C:\Users\Gharke\AppData\Roaming\uv\python\cpython-3.12.11-windows-x86_64-none\python.exe'
& $w1Python -m unittest discover -s tests -v
& $w1Python w1.py --help
& $w1Python tools/inspect_lrs.py

On a machine with Python on PATH, the equivalent commands start with python. w1.py adds this checkout's src/ to its import path; it does not install a package or alter the machine's environment.

Layout

AGENTS.md                         Persistent engineering/authority instructions
w1.py                             Checkout command entry point
src/opportunity_intelligence/
  paths.py                        Canonical checkout/data paths
  collectors/usac.py               Independent USAC collector
  collectors/lrs.py                Independent LRS collector
  qualification/lrs.py             Offline qualification and brief rendering
tests/
  test_*.py                       Regression and offline CLI tests
  fixtures/                       Saved HTML, seed records and expected brief
docs/                             Source procedures and migration notes
data/opportunities.json            Canonical reviewed pipeline
runs/                             Preserved execution outputs and raw evidence
tools/                            Offline inspection and verification utilities

Commands

python -m unittest discover -s tests -v
python w1.py usac --help
python w1.py lrs --help
python w1.py qualify --help
python tools/inspect_lrs.py
python w1.py qualify --run runs/2026-09-17/lrs-162640 --output runs/2026-09-17/qualification-review-new

Choose a new qualification output directory for each run. The last command uses saved source evidence and requires no network access.

Live collection, when needed:

python w1.py usac
python w1.py lrs

USAC retains its original runs/YYYY-MM-DD/usac.json and new_candidates.json convention; a repeat on the same day overwrites those two outputs. Do not rerun it over evidence that must be retained. Offline tests isolate its output in a temporary directory. LRS creates a fresh timestamped directory and refuses an existing output target. Neither collector modifies reviewed pipeline records.

Procedures and evidence

• LRS access, extraction defects and live-run evidence
• Qualification rules and audit outputs
• USAC procedure
• W1-017 migration and verification
• Initial Sprint 0 operating record
• Local Git baseline and historical evidence policy

The reviewed pipeline is now data/opportunities.json; its bytes are unchanged. Historical run paths remain valid. Records retain original links, provenance, source conflicts and human decisions. HTTP availability is not confirmed hiring status; candidate outputs remain unreviewed until Ken approves promotion.

W1-019 adds python w1.py practical --help for saved-evidence practical eligibility. See profile editing, rules and replay.