# 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:

```powershell
$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

```text
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

```powershell
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:

```powershell
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](docs/LRS.md)
- [Qualification rules and audit outputs](docs/QUALIFICATION.md)
- [USAC procedure](docs/USAC.md)
- [W1-017 migration and verification](docs/MIGRATION-W1-017.md)
- [Initial Sprint 0 operating record](docs/SPRINT0.md)
- [Local Git baseline and historical evidence policy](docs/VERSION-CONTROL.md)

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](docs/PRACTICAL-QUALIFICATION.md).

[W1-021 owner profile calibration and offline comparison](docs/OWNER-PROFILE-CALIBRATION.md).