# Checklists ## Scanner Change - [ ] The expected crop or capture behavior is clear. - [ ] Genshin is not accessed through memory reads, hooks, injection, or game files. - [ ] Auto-scan starts only from confirmed artifact inventory plus visible detail card, or blocks with a reason. - [ ] Native Artifact scan resets the inventory to the top with a bounded grid-anchor scroll and stabilization wait. - [ ] A user-facing full-inventory run resolves its target from the OCR-confirmed current owned Artifact count, never from inventory capacity; missing or invalid current count blocks safely before native start. - [ ] Artifact and row limits both clamp to the owned count and the 2,400 target safety bound; row conversion uses the detected grid column count. - [ ] A `B` plus Artifact-tab reopen is not promoted over the bounded wheel reset without a guarded live A/B test for state safety, targeting, and timing. - [ ] Native automated clicks and wheel events require Genshin to remain foreground; focus loss stops without refocusing. - [ ] Stop, ESC, Enter, and F9 remain active during native reset, capture, and scrolling. - [ ] Capture failures are shown to the user. - [ ] OCR uncertainty remains inspectable in Details. - [ ] Parser output does not silently trust low-confidence text. - [ ] Current native capture jobs preserve direct visual `starCount`, `starConfidence`, and `starSource`; an absent, invalid, or conflicting star field is never silently assumed to be 5★. - [ ] Direct visual rarity ambiguity enters `Review` before value evaluation. - [ ] Scanner controls contain no automatic in-game salvage, Quick Select, deletion, feed, enhance, lock/unlock, or resource-spending action. - [ ] Any Inventory local-result removal is explicitly confirmed, tombstones the result before crop cleanup, preserves raw `scan-results.json` evidence, remains contained to app-local files, and never invokes game input. An optional Store-record removal is limited to the exact linked local record. - [ ] A native-result deletion is blocked while capture or processing is active, remains idempotent after its tombstone, and cannot remove a crop outside the selected run directory. - [ ] `npm run lint` passes. - [ ] `npm run helper:test` passes when native input safety changed. - [ ] `npm test` passes when parser/scoring logic changed. - [ ] `npm run build` passes. - [ ] Manual Smart Capture is tested when possible. ## Live Scan Timing Claim - [ ] `/health.appBuild.signature` matches the current `APP_RUNTIME_SIGNATURE`. - [ ] `npm run scan:live:preflight` passes, or use the validated command that runs it first. - [ ] During manual UAC startup, `npm run scan:live:preflight:wait` may be used before the scan chain. - [ ] `npm run scan:assessment:test` passes. - [ ] Use `npm run scan:iterate:validated` or `npm run scan:iterate:validated:wait` for short 20-artifact tuning loops. - [ ] Prefer `npm run scan:goal:validated` or `npm run scan:goal:validated:wait` for the final live run because it runs preflight, scan, and assessment validation in sequence. - [ ] The run includes `scan-performance-assessment.json`. - [ ] `npm run scan:assessment:validate -- --latest` or explicit `--input=\scan-performance-assessment.json` passes. - [ ] If claiming the current scanner path, the validator is run with `--expect-winner=current`. - [ ] Final report cites the validator JSON or `--summary` output, including the assessment path. - [ ] For iteration claims, the 20-artifact run finishes cleanly and is validated with `--limit=20`. - [ ] For final claims, the 100-artifact run finishes cleanly. - [ ] Parsed count is at least the requested count. - [ ] Miss rate is at or below 2%. - [ ] Review rate is at or below 15%. - [ ] Capture rate, processing rate, and end-to-end rate are reported as separate metrics. - [ ] A streaming end-to-end claim records native start, capture start/end, processing start/end, and final result reconciliation on one shared wall clock. - [ ] `run-timing.json` is present, uses `native-scanner-run-timing-v1`, and contains valid ordered first-observed lifecycle markers through durable result reconciliation. - [ ] The smoke report validates target/capture/queue/parse/durable-result reconciliation together with the timing record; a historical timing report is not reused for a current-build claim. - [ ] Overlapping capture and processing durations are never added to derive an end-to-end rate. - [ ] Speed reporting uses quality gates, not click count alone. ## Revised Scope Live Acceptance - [x] Current elevated-dev 50-artifact smoke `20260711-154827`: target/captured/ clicked/queued/processed/parsed/loaded `50/50`, 2 pages, 0 Review, 0 errors, 0 Store writes, `persist=false`, and 50 jobs/non-empty PNGs. A valid `native-scanner-run-timing-v1` record reconciled at `28,022 ms`; it is not a 3/s performance claim. - [x] Real Settings-UI Artifact limit 5: Genshin/detail/grid preflight passed; target/captured/processed/parsed `5/5`, Review/errors `0`, `persist=false`, and five current-session result rows. - [x] Complete packaged full-inventory baseline resolves OCR-owned target 2,211, captures 2,211 crops over 70 pages, reprocesses all 2,211 with the current package at 136 Review (6.15%), 0 errors, `persist=false`, and passes saved-run validation with 0 issues. - [x] Real packaged Settings-UI row limit 1 resolves the detected eight-column grid to target 8 and finishes captured/processed/parsed `8/8`, Review/errors `0`, `persist=false`; foreground loss is proven to block with zero clicks. - [ ] Any `B`-reopen candidate is benchmarked separately and does not replace the accepted wheel reset without stronger reliability and timing evidence. ## UI Change - [ ] Scanner, Artifacts, Review, and Builds preview follow the primary user journey; Overlay and Diagnostics remain secondary tools. - [ ] The Scanner page shows app/Genshin readiness and one unambiguous primary start/stop action before advanced controls. - [ ] The main workflow remains visible without unnecessary scrolling. - [ ] Debug or secondary information is moved behind buttons/modals where appropriate. - [ ] Builds stays visibly labeled as a preview until Build-Fit is implemented; roll efficiency is not presented as character/build suitability. - [ ] Review describes extraction correction and never implies trash, feed, deletion, or an in-game mutation. - [ ] Disabled states prevent actions without required data. - [ ] Initial content loading reserves layout with a skeleton; bounded actions use a spinner; scan progress remains durable view state. - [ ] During scanning, the left main work surface shows phase, processed-versus-target progress, and read/parsed/stored/review/duplicate/error outcomes without a duplicate standalone progress card. - [ ] Toasts confirm explicit mutations and failures without replacing durable progress, review, blocked, or error state. - [ ] Status meaning is available through text/icons and not color or animation alone. - [ ] Keyboard focus is visible for navigation, buttons, disclosures, fields, dialogs, and toast dismissal. - [ ] `prefers-reduced-motion: reduce` disables non-essential motion without hiding state changes or feedback. - [ ] Text fits in controls and panels. - [ ] The Scanner, Artifacts, Review, Builds preview, Overlay, and Diagnostics views are checked at the packaged desktop viewport for clipping, overflow, accidental page-level scroll, nested-scroll traps, and empty/loading/error states. - [ ] Primary scanner controls remain usable at the smallest supported desktop window; narrower layouts reflow instead of clipping cards or action labels. - [ ] Before/after screenshots or equivalent current-build visual evidence are inspected for the changed views. - [ ] A fresh/missing/invalid app locale starts in English, German can be selected in Settings, and the preference persists locally without changing the English-only Genshin scanner contract. - [ ] Localized UI acceptance uses stable semantic hooks where possible and verifies that translated labels do not cause clipping, focus, or overflow. - [ ] The artifact detail local-delete control states its app-local scope, requires confirmation, and remains unavailable for an active native run. - [ ] `npm run lint` and relevant renderer tests pass. - [ ] `npm run build` passes. ## Scan Results And Inventory UX - [ ] The scan page keeps preview, Stop/status, and the live result rail visible without page-level scrolling. - [ ] The result rail is empty on a fresh app launch, contains only results from the current app scan session, and leaves persisted history in Artifacts. - [ ] Progress and completion use the resolved owned-inventory target or the selected Artifact/row limit consistently. - [ ] Capture and evaluation progress advance independently: the left bar uses captured/target while the right result panel uses evaluated/target. - [ ] Processing starts once when the native run first exposes `runDir`, keeps waiting across temporary JSONL EOF, and finishes only after producer terminal plus queue drain. - [ ] The live rail shows fully evaluated artifact rows only, not intermediate OCR/debug state, and appends every current-session row in capture order. - [ ] Result delta polling deduplicates stable IDs/sequences and a final full load reconciles captured, processed, and durable-result counts. - [ ] Newly inserted result rows use a left-to-right mount cue; reduced-motion users receive the same content and status without the animation. - [ ] Each live row has scan number, artifact name or compact fallback, value score, and a short status pill. - [ ] Extraction confidence and artifact value remain separate in the data model. - [ ] Native post-capture runs write `scan-results.json` with extraction status and deferred/review value status. - [ ] Native post-capture reports include bounded queue evidence such as `queueConcurrency` when OCR/parse workers run. - [ ] Native artifact post-processing records IK/GOOD match metadata and sends IK set/piece/slot conflicts to review. - [ ] Native scan result details preserve parser field confidence for review instead of hiding uncertainty. - [ ] Native inventory promotion is previewed as a dry-run decision before any artifact-store write path is enabled. - [ ] Weapon, character, and material IK matching claims are backed by category-specific capture evidence, not just catalog availability. - [ ] Native `supportedCategories` distinguishes `catalogAvailable` from `nativeCaptureSupported`. - [ ] Native scan start, run manifest, status, and capture jobs carry an explicit scan category. - [ ] Native preflight and post-capture processing block catalog-only categories before OCR/parsing. - [ ] Native preflight blocks blank or too-uniform Genshin captures before any click is sent. - [ ] Native crop previews are loaded only through the Electron bridge and stay constrained to PNG files inside the selected run directory. - [ ] Native live smoke uses `npm run scan:native:smoke` before broad native timing or store-promotion claims. - [ ] Artifact-only scope is visible in the UI; weapons, materials, and character details are not presented as active scanner features while they are not scanned. - [ ] Low-confidence or conflicting reads show `Review` instead of a normal weak/strong value decision. - [ ] Explicit visual 1–4★ native results use `excluded`, receive no score, projection, or store promotion, and remain visible for manual inspection. - [ ] The separate read-only `Nicht 5★` filter contains only explicitly recognized 1–4★ entries and retains screenshot/crop plus parsed details. - [ ] The `Nicht 5★` view does not call entries safe to salvage and exposes no automatic salvage or Quick Select control. - [ ] Duplicate state is represented separately from artifact quality. - [ ] The artifact inventory view can browse stored scan results without opening diagnostics. - [ ] Inventory filters/sorting cover review, score, set, slot, equipped, locked, and newest scan where data exists. - [ ] Artifact detail shows screenshot/crop, parsed fields, OCR confidence, parser notes, value reasons, and review state. - [ ] Upgrade projection, if shown, is labeled as a projection and includes worst/middle/best cases. - [ ] Unit tests cover score/status derivation and projection edge cases when those modules change. - [ ] Scanner safety rules and existing quality gates are unchanged. ## Parser Or Scoring Change - [ ] Known-good OCR samples still parse correctly. - [ ] Ambiguous data becomes unknown or review, not false certainty. - [ ] Character, set, stat, and slot dictionaries are updated deliberately. - [ ] Tests cover changed behavior when practical. ## Artifact Roll Evaluation - [ ] Extraction status and value status remain separate fields. - [ ] Clean legal results become `evaluated`; Review receives no normal score. - [ ] Only explicitly confirmed 5★ evidence enters `roll-efficiency-v1` for current native jobs. - [ ] Explicit visual 1–4★ evidence becomes `excluded`, not a weak score; missing, invalid, or conflicting direct star evidence becomes `Review`. - [ ] Incomplete or inconsistent clean data becomes `unknown`, not a guessed score. - [ ] Score is labeled as roll efficiency, not universal Artifact or build value. - [ ] Build fit stays explicitly deferred without character/build context. - [ ] Locked and equipped state do not change roll efficiency. - [ ] Rarity-specific legal values and total roll counts are enforced. - [ ] Reason codes and per-substat roll breakdown explain the result. - [ ] Legacy saved scan results are enriched on load without requiring a rescan. - [ ] Unit tests cover evaluated, review, unknown, ambiguity, and rarity edges. ## Build-Fit Contract - [x] Input, contract, and assessment schemas are explicitly versioned. - [x] Contracts require character/target identity, revision, game-versioned provenance, explained Set/Main-Stat/Substat rules, aggregate targets, and explicit conflict behavior. - [x] V1 safety floors cannot be lowered below 80% overall extraction and 70% for every required identity/value field. - [x] Review, non-parsed, incomplete, low-confidence, or non-canonical Set data blocks before downstream fit work. - [x] Native Artifact results map into the contract without guessing a Set key; non-Artifact categories are rejected. - [x] Roll-Efficiency is recorded only as separate context and is never used as Build-Fit eligibility or presented as a fit score. - [x] V1 assessments retain `score: null` and deferred recommendations even when the separate evidence-ranking layer is available. - [x] Real local account snapshots do not call the legacy demo scorer. - [x] Four current profiles (Furina, Neuvillette, Raiden Hyperbloom, Nahida Deepwood) are source-bound, game-versioned, IK-6.7.0-key validated, have explicit expiry, and are covered by Golden plus Review/low-confidence or pending-context adversarial fixtures. - [ ] Every further character/build profile is sourced, game-versioned, reviewed, expiry-bound, and covered by Golden/adversarial fixtures before product use. - [x] Five-piece evaluation verifies unique slots, Set shape, sourced aggregate targets, nested extraction gates, and cross-character/build conflicts together; missing non-Artifact context remains `pending` rather than guessed. - [x] The Builds UI reads only the newest complete native run and exposes at most three non-overlapping, read-only suggestions with profile, source, Set/Main-Stat/Substat evidence, conflicts, uncertainty, and selection reason. - [x] The ranker never uses `roll-efficiency-v1`, roll magnitude, or OCR confidence as a rank weight; confidence stays a hard gate. - [x] Required aggregate targets accept only explicit, user-confirmed, session-only local context and otherwise defer the profile. - [x] The built-renderer Builds/UI acceptance verifies fresh English, German switching/restoration, loading, deferred/context, suggestion, focus, reduced-motion, overflow, and native plus Store local-delete confirmation probes. - [ ] An elevated packaged-executable run separately verifies the same renderer behavior when making a package-runtime claim; built-renderer evidence alone does not prove UAC, bridge, or native runtime behavior. ## Upgrade Projection - [ ] Projection appears only below +20 with four known legal substats. - [ ] Worst is less than or equal to Middle; Middle is less than or equal to Best. - [ ] Remaining roll count matches the current Artifact level. - [ ] Review, illegal, incomplete, three-substat, 4-star, and rarity-ambiguous data disables projection. - [ ] +20 is complete and does not invent future rolls. - [ ] UI states that target substat and tier are random and not guaranteed. - [ ] Projection does not claim character/build usefulness. ## Native Offline Replay - [ ] Replay reads an existing `scan-results.json` and never starts capture/input. - [ ] At least three repeats produce the same full derived-payload hash. - [ ] Every clean parsed Artifact is evaluated or the command fails. - [ ] Explicit 1–4★ entries replay as stable `excluded` results and are not counted as clean-but-unevaluated failures. - [ ] Review remains Review and is not counted as an evaluation failure. - [ ] Report includes value/projection counts and score range. - [ ] Accepted bounded 20/50/100 runs and the 2,211 full-inventory corpus are replayed before changing the evaluation contract. - [ ] `npm run scan:native:validate:saved` passes for the latest complete evidence set, including `-- --targets=2211` for full-inventory-sensitive work. - [ ] Saved-run validation confirms manifest/status/job/result counts, PNG containment, zero processing errors, non-persistence, review provenance, and projection ordering. ## Release Or Packaging - [ ] `npm run acceptance:offline` passes before the live acceptance session. - [ ] Production build succeeds. - [ ] Electron preload bridge is copied to `dist-electron/preload.cjs`. - [ ] App starts outside browser preview. - [ ] Smart Capture bridge is available. - [ ] No generated debug artifacts are included accidentally. - [ ] `npm audit --omit=dev` reports zero production vulnerabilities. - [ ] `npm run package:offline-check` passes before packaged runtime testing. - [ ] ASAR contains renderer, Electron main, preload, and package manifest. - [ ] Packaged `dist/index.html` uses relative `./assets/...` references; the verifier rejects root-absolute `/assets/...` references. - [ ] `resources/input-helper/InputHelper.exe` exists in the unpacked app. - [ ] `resources/ik-inventorylists` exists and its version matches source data. - [ ] Packaged helper/IK resolution uses `process.resourcesPath` without an implicit `process.cwd()` repository fallback. - [ ] Packaged and source `APP_RUNTIME_SIGNATURE` values match, so evidence from an older runtime is rejected as stale. - [x] `npm run package:live:builds` passed against the built renderer: fresh English, German selection, restored English, Builds loading/context/focus, reduced motion, no document overflow, and native plus Store delete-confirmation UI probes. - [ ] The same UI evidence is collected from an elevated packaged executable before claiming current package-runtime/UAC behavior. - [ ] Packaged runtime launch, UAC, bridge, helper, and crop preview are tested separately; offline resource checks do not prove runtime behavior. ## Next Live Acceptance Session Use [TOMORROW_LIVE_TEST_PLAN_2026-07-10.md](TOMORROW_LIVE_TEST_PLAN_2026-07-10.md) in order. Start with packaged launch and existing Inventory data, then one Smart Capture, native 5, and only then gated 20/50/100 runs. ## Git Merge And Gitea Push - [ ] `git status --short --branch` is checked before switching branches, committing, merging, or pushing. - [ ] Work is committed on the intended feature branch before merging into `main`. - [ ] Merge into `main` uses fast-forward when possible, or a deliberate merge commit when the history requires it. - [ ] `main` is clean before push except for explicitly ignored or deliberately untracked local files. - [ ] `git remote -v` points to the intended Gitea remote before pushing. - [ ] Gitea HTTPS credentials are stored through Git Credential Manager, not in repository files or remote URLs. - [ ] If authentication fails, refresh the credential using [GITEA_AUTH.md](GITEA_AUTH.md), then rerun the same `git push`. - [ ] After push, `git status --short --branch` shows `main...origin/main` without ahead/behind drift.