RFC: visa-phase-3 - E-Verify, STEM detection, H-1B salary, risk scoring

[minwoo-data]

This is the third and final phase of the visa sponsorship module for F-1 international job seekers.

Visa Module Overview

Phase	PR	What it adds
visa-phase-1	#288	Sponsorship signal detection, H-1B employer history, composite visa score
visa-phase-2	#200	OPT timeline tracking, unemployment counter, H-1B cap season calendar
visa-phase-3	this RFC	E-Verify lookup, STEM detection, salary benchmarks, risk scoring

Problem Statement

After visa-phase-1 and visa-phase-2, users know whether a company might sponsor and when their OPT expires. But they still lack:

• Is this employer E-Verify registered? — Required for STEM OPT employment
• Is this role STEM-eligible? — Determines 24-month extension eligibility
• What's the prevailing wage? — H-1B salary floor for negotiation
• How risky is this company? — Layoffs, denial rates, funding stage

Without this, users waste time on companies that can't legally employ them under STEM OPT, or accept below-market offers.

High-Level Solution

Four standalone enrichment scripts integrated into Block G + Block D:

Script	What it does	Tests
everify-lookup.mjs	E-Verify registration check (YAML pre-seed + Playwright + 30-day cache)	18
stem-detect.mjs	STEM job classification (47 positive + 23 negative keywords)	16
h1b-salary.mjs	H-1B prevailing wage lookup (Playwright scraping + cache)	13
risk-assess.mjs	Company risk rating — 7 weighted factors → LOW/MEDIUM/HIGH	15

All follow existing conventions: standalone .mjs, --test flag, --json output, batch-mode degradation.

Affected Files

New (7 scripts + 3 configs)

• everify-lookup.mjs, stem-detect.mjs, h1b-salary.mjs, risk-assess.mjs
• config/everify-known.yml, config/stem-keywords.yml, config/risk-watchlist.yml

Modified (7)

• modes/oferta.md — Block G.2 visa analysis, Block D salary benchmarks
• batch/batch-prompt.md — Batch-safe degradation
• modes/deep.md — Risk assessment section
• DATA_CONTRACT.md — Register new files
• update-system.mjs — SYSTEM_PATHS + USER_PATHS
• test-all.mjs — Sections 15-18
• config/visa.example.yml — Phase 3 config docs

NOT modified

• modes/_shared.md
• .planning/
• READMEs

Data Contract Impact

File	Layer	Rationale
everify-lookup.mjs, stem-detect.mjs, h1b-salary.mjs, risk-assess.mjs	System	Auto-updatable scripts
config/everify-known.yml, config/stem-keywords.yml	System	Pre-seeded data
config/risk-watchlist.yml	User	User customizes watchlist
config/everify-known.local.yml	User	User-layer E-Verify override

Security

• SHA-256 cache key hashing (not MD5)
• SSRF domain validation on all Playwright URLs
• Prototype pollution guard on YAML parsing
• Path traversal protection on cache operations
• stdin JSON wrapped in try-catch

Implementation Status

Code is ready on branch feat/visa-enrichment — 62 tests passing.
PR will follow after RFC feedback.

Depends on: #288 (visa-phase-1) → #200 (visa-phase-2) → this
Code is ready on branch feat/visa-enrichment — Draft PR: #292

Open Questions

1. Should config/everify-known.yml accept community PRs to add employers, or stay system-curated?
2. Risk scoring weights are hardcoded — should they be configurable via config/visa.yml?
3. H-1B salary lookup depends on H1Bdata.info — need a fallback data source?

---

First RFC under the process established in Discussion #284.
Related: #182 (closed, superseded by #288), #288 (visa-phase-1), #200 (visa-phase-2)