genshin-assistant/docs/MERGE_READINESS.md

Merge Readiness

Current branch: codex/ik-scanner-progress

This checklist records the evidence needed before merging this scanner branch into main. It separates merge-relevant proof from optional follow-up work.

Merge-Relevant Evidence

Area	Status	Evidence
TypeScript/lint gate	Passed	npm run lint
Unit/regression suite	Passed	npm test with 207 tests, including equipped footer, lock detection, and PNG lock-crop regression coverage
Production build	Passed	npm run build
Whitespace check	Passed	git diff --check
OCR eval gate	Passed	npm run eval with 23/23 exact-match cases and 100% critical fields
Scan assessment self-test	Passed	npm run scan:assessment:test; the fixture intentionally expects ik-traineddata to win its synthetic limit=100 case while real live-winner claims stay tied to archived live assessments
Live runtime preflight	Passed	npm run scan:live:preflight; signature 2026-07-08-direct-gdi-reviewfix, elevated yes, Genshin found
Safe visible-inventory scan path	Passed	2026-07-09 live run: /scanner/start?entry=visible-inventory&limit=20&engine=current completed 20/20 verified and parsed, 19 stored, 1 duplicate, 0 review, 0 misses, 8047 ms elapsed
Equipped character OCR/persist path	Passed for live smoke	2026-07-09 live captures read equipped footers for Citlali and Linnea; parser regression covers Equipped: Linnea l -> Linnea
Unlocked lock state	Passed for live smoke	2026-07-09 Smart Capture reported locked: false on an unlocked artifact; after restart, lockSignal.ratio: 0 with threshold 0.06
Positive locked lock state	Passed	2026-07-09 Smart Capture on a visibly locked artifact reported locked: true, lockSignal.ratio: 0.14797913950456323, threshold 0.06
Lock-state persistence	Passed	2026-07-09 /scanner/start?entry=visible-inventory&limit=1&engine=current stored A Note in Spring's Leich with equipped: "Citlali" and locked: true
Lock-state diagnostics	Passed	Capture results include lockSignal.ratio, lockSignal.threshold, and the lock crop rect. Detection uses decoded PNG crop pixels to avoid native bitmap channel-order ambiguity
Unsafe auto-entry default	Mitigated	Normal guided Auto-Scan now blocks when no artifact detail card is visible instead of falling back to auto-entry
Review-to-eval export	Passed by tests	npm run eval:review-candidates script is covered by src/eval/reviewEvalCandidatesScript.test.ts and output is Git-ignored

Final Gate

npm run lint
npm test
npm run build
git diff --check

Latest run after the lock-state fix: passed with 207 tests. npm run eval and npm run scan:assessment:test also passed after the lock-state fix.

Explicitly Not Merge-Blocking

• auto-entry, direct-inventory, and paimon-menu are still experimental Dev-Control entry modes. They can be tested later with low limits, but they are no longer the normal merge path.
• The optional 3 artifacts/second target is not proven. The stable current path is closer to 2.5 to 2.75 artifacts/second on clean 20-artifact live runs.
• Native Tesseract/IK-traineddata is not the default. The latest documented qualified live 100-artifact comparison in this environment had current as winner; the assessment self-test is a synthetic validator fixture, not a live winner claim.

Merge Recommendation

Ready for final human diff review and then merge into main. The previously open locked: true proof now passes for both Smart Capture and auto-scan persistence.