# Hand-Painted Unit Sprite Rework Plan

## Current Baseline

- Approved baseline commit: `3092b295 Improve handpainted battle unit readability`
- Approved batch 1 style references:
  - `unit-liu-bei`
  - `unit-guan-yu`
  - `unit-zhang-fei`
  - `unit-rebel`
  - `unit-rebel-archer`
  - `unit-rebel-cavalry`
- Pending quality restart sample:
  - `unit-shu-infantry`
  - Source: `handpaint-batch2-shu-infantry-quality-restart-source-v3.png`
  - Contact sheet: `handpaint-batch2-shu-infantry-quality-restart-v3-contact.png`
  - Battle-scale composite: `handpaint-batch2-shu-infantry-quality-restart-v3-battle-composite.png`
  - Approval packet: `unit-sprite-shu-infantry-v3-approval-packet.md`

## Batch Inventory

Generated by `scripts/audit-unit-sprite-sheets.py`.

Visual review boards are generated by `scripts/render-unit-sprite-review-boards.py`.

- Review index: `unit-sprite-review-index.png`
- Approved/pending deliverables only: `unit-sprite-review-approved-and-pending.png`
- Current Shu batch board: `unit-sprite-review-batch2-shu.png`
- Review manifest: `unit-sprite-rework-manifest.json`
- Output checklist: `unit-sprite-batch-output-checklist.md`
- Pipeline guide: `unit-sprite-handpaint-pipeline-guide.md`
- Progress log: `unit-sprite-rework-progress-log.md`
- Next-step report: `unit-sprite-next-steps.md`

- Batch 1 approved core: 3 sheets
- Batch 1 approved rebel: 3 sheets
- Batch 2 Shu generic: 18 sheets
- Batch 3 Wei generic: 16 sheets
- Batch 4 Wu generic: 16 sheets
- Batch 5 remaining rebel/bandit: 6 sheets
- Batch 6 Nanman/special: 10 sheets
- Batch 7 unique officers: 19 sheets

## Batch 2 Shu Order

The Shu infantry v3 sample is the quality gate before expanding the rest of batch 2.

1. `unit-shu-infantry` - pending approval as the v3 restart sample.
2. `unit-shu-spearman` - long spear silhouette, green/bronze Shu armor. Spec: `unit-sprite-batch2-shu-spearman-spec.md`
3. `unit-shu-archer` - bow silhouette readable at 50px. Spec: `unit-sprite-batch2-shu-archer-spec.md`
4. `unit-shu-cavalry` - horse and rider must fit inside tile without lateral drift. Spec: `unit-sprite-batch2-shu-cavalry-spec.md`
5. `unit-shu-strategist` - fan/scroll/robe silhouette. Spec: `unit-sprite-batch2-shu-strategist-spec.md`
6. `unit-shu-officer` - command/officer silhouette. Spec: `unit-sprite-batch2-shu-officer-spec.md`
7. Variants after primary classes are approved:
   - `unit-shu-infantry-banner`
   - `unit-shu-infantry-guard`
   - `unit-shu-spearman-guard`
   - `unit-shu-spearman-veteran`
   - `unit-shu-archer-longbow`
   - `unit-shu-archer-veteran`
   - `unit-shu-cavalry-scout`
   - `unit-shu-cavalry-white`
   - `unit-shu-strategist-field`
   - `unit-shu-strategist-white`
   - `unit-shu-officer-council`
   - `unit-shu-officer-vanguard`

## Quality Gate

Each unit must pass these checks before batch commit/deploy:

- New hand-painted raster source, not a filter-only or simple shape pass.
- Existing 313x313 frame layout preserved.
- Base sheet size: `5008x1252`.
- Action sheet size: `11268x1252`.
- Partial alpha: `0`.
- Frame border hits: `0` unless a reviewed attack effect intentionally reaches near the border without gameplay clipping.
- Idle/walk body scale and bottom position stable.
- No detached sprite fragments in idle/walk frames.
- 50px battle-scale view reads before the background.
- Contact sheet, GIF, before/after, and battle-scale verification image generated.
- `pnpm build` passes.
- Local PC browser preview has no console errors.

## Approval Gate

- Do not expand to the next unit until the current sample direction is approved.
- Do not commit, push, or deploy an unapproved sample batch.
- Use `unit-sprite-review-approved-and-pending.png` for quality review of actual deliverables; batch boards still include old queued assets for inventory only.
- Review stages are controlled by `unit-sprite-rework-manifest.json`, not by whether a sheet is merely technically `ok`.
- When the user approves a unit or batch, move it from `pendingApproval` to `approvedBaseline` in the manifest before regenerating audit/review boards.
- `scripts/check-unit-sprite-approval-gate.py --mode sample` must pass while a sample is pending.
- `scripts/check-unit-sprite-art-quality.py` must pass for the current pending sample before asking for approval.
- `scripts/check-unit-sprite-workflow-consistency.py` must pass so manifest, docs, and gate command lists stay aligned.
- `scripts/check-unit-sprite-approval-gate.py --mode release` must pass before commit/push/deploy; it blocks pending samples by design.
- `scripts/write-unit-sprite-next-steps.py` records the current blocker and the first queued unit after approval.
- After a batch is approved, run build/browser verification, then commit, push, and deploy.