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.
• Capture failures are shown to the user.
• OCR uncertainty remains inspectable in Details.
• Parser output does not silently trust low-confidence text.
• npm run lint passes.
• 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%.
• Speed reporting uses active scan timing plus quality, not click count alone.

UI Change

• The main workflow remains visible without unnecessary scrolling.
• Debug or secondary information is moved behind buttons/modals where appropriate.
• Disabled states prevent actions without required data.
• Text fits in controls and panels.
• Desktop viewport is checked manually.
• 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 live rail shows finished artifact rows only, not intermediate OCR/debug state.
• 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.
• 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.

Release Or Packaging

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

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.