genshin-assistant/docs/CHECKLISTS.md

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=<path>\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

• 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.

• 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.

• 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.

• 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

• Input, contract, and assessment schemas are explicitly versioned.
• Contracts require character/target identity, revision, game-versioned provenance, explained Set/Main-Stat/Substat rules, aggregate targets, and explicit conflict behavior.
• V1 safety floors cannot be lowered below 80% overall extraction and 70% for every required identity/value field.
• Review, non-parsed, incomplete, low-confidence, or non-canonical Set data blocks before downstream fit work.
• Native Artifact results map into the contract without guessing a Set key; non-Artifact categories are rejected.
• Roll-Efficiency is recorded only as separate context and is never used as Build-Fit eligibility or presented as a fit score.
• V1 assessments retain score: null and deferred recommendations even when the separate evidence-ranking layer is available.
• Real local account snapshots do not call the legacy demo scorer.
• 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.
• 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.
• 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.
• The ranker never uses roll-efficiency-v1, roll magnitude, or OCR confidence as a rank weight; confidence stays a hard gate.
• Required aggregate targets accept only explicit, user-confirmed, session-only local context and otherwise defer the profile.
• 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.
• 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 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, then rerun the same git push.
• After push, git status --short --branch shows main...origin/main without ahead/behind drift.