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

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