Approve Shu infantry handpainted sprite v8

docs/handpaint-batch2-shu-infantry-quality-restart-v8-report.md

@@ -0,0 +1,24 @@
+# Shu Infantry Quality Restart Sample v8
+
+- source: `handpaint-batch2-shu-infantry-quality-restart-source-v8.png`
+- base status: ok
+- action status: ok
+- base partial alpha: 0, opaque pixels: 2034444
+- action partial alpha: 0, opaque pixels: 4825025
+- base frame border hits: 0
+- action frame border hits: 0
+- base empty frames: 0
+- action empty frames: 0
+- base bbox width range: 183..222
+- base bbox height range: 288..288
+- base bottom range: 303..303
+- action bbox width range: 181..255
+- action bbox height range: 280..288
+- action bottom range: 303..303
+- contact: `handpaint-batch2-shu-infantry-quality-restart-v8-contact.png`
+- animation: `handpaint-batch2-shu-infantry-quality-restart-v8-animation.gif`
+- before/after: `handpaint-batch2-shu-infantry-quality-restart-v8-before-after.png`
+- scale compare: `handpaint-batch2-shu-infantry-quality-restart-v8-scale-compare.png`
+- battle composite: `handpaint-batch2-shu-infantry-quality-restart-v8-battle-composite.png`
+- manual checks: run build and local browser verification after generation
+- note: battle composite is a scale review image; gameplay roster is unchanged during sample approval

docs/unit-sprite-art-quality-gate.md

@@ -0,0 +1,30 @@
+# Unit Sprite Art Quality Gate
+
+This file is generated by `scripts/check-unit-sprite-art-quality.py`.
+
+This gate catches obvious sprite-art failures before user approval. It does not replace manual visual approval.
+
+- Manifest: `docs/unit-sprite-rework-manifest.json`
+- Audit: `docs/unit-sprite-rework-audit.json`
+- Approved baseline units: 7
+- Pending approval units: 0
+- Queued rework units: 84
+
+## Checked Rules
+
+- Required approval artifacts exist, including contact sheet, GIF, scale comparison, battle preview, and current approval board.
+- Base/action sheets have no partial alpha, border hits, or empty frames.
+- 50px battle-scale silhouette is not too small or too tall.
+- Idle/walk base frames stay vertically stable.
+- Approval packet points at the current approval board and browser debug preview evidence.
+
+## none
+
+Status: OK
+
+Evidence:
+- no pending approval units: nothing to check
+
+## Result
+
+OK

docs/unit-sprite-batch-output-checklist.md

@@ -0,0 +1,90 @@
+# Unit Sprite Batch Output Checklist
+
+Use this checklist for every unit and every batch before approval, commit, push, or deploy.
+
+Pipeline reference: `unit-sprite-handpaint-pipeline-guide.md`.
+
+Review state manifest: `unit-sprite-rework-manifest.json`.
+
+## Per-Unit Required Artifacts
+
+- Production spec for the unit, when one exists in `docs/unit-sprite-batch*-*-spec.md`.
+- Source image on flat chroma-key background.
+- Base sheet in `src/assets/images/units/<unit-key>.png`.
+- Action sheet in `src/assets/images/units/<unit-key>-actions.png`.
+- Contact sheet in `docs/`.
+- Idle/walk/action GIF in `docs/`.
+- Previous/new comparison image in `docs/`.
+- 50px/72px scale comparison image in `docs/`.
+- Battle map composite in `docs/`.
+- Debug sprite preview battle screenshot in `docs/` for the current pending sample.
+- Per-unit report in `docs/`.
+
+## Per-Unit Technical Checks
+
+- Base sheet size is exactly `5008x1252`.
+- Action sheet size is exactly `11268x1252`.
+- Frame size remains `313x313`.
+- Base partial alpha is `0`.
+- Action partial alpha is `0`.
+- No idle/walk frame touches the frame border.
+- No detached fragments in idle/walk frames.
+- Body scale and foot line are stable during idle/walk.
+- Action frames may have larger silhouettes, but must not visibly clip in game scale.
+- Unit appears as `ok` in `docs/unit-sprite-rework-audit.json`.
+- Unit review stage is correct:
+  - approved units use `approved-baseline`
+  - current sample uses `pending-approval`
+  - untouched future units remain `queued-rework`
+
+## Per-Unit Visual Checks
+
+- The unit reads clearly at 50px.
+- The 50px/72px comparison is checked against approved units, not only against the old placeholder.
+- Weapon/class reads from silhouette:
+  - sword/infantry
+  - spear
+  - bow
+  - horse/cavalry
+  - fan/scroll/strategist
+  - officer/banner
+- Faction palette reads clearly.
+- The sprite itself solves readability; no rings, base plates, badges, glows, or UI decorations are used to compensate.
+- Style remains aligned with approved hand-painted batch 1 and the current `unit-shu-infantry` approval candidate.
+
+## Per-Batch Checks
+
+- `python scripts/audit-unit-sprite-sheets.py`
+- `python scripts/render-unit-sprite-review-boards.py`
+- `python scripts/check-unit-sprite-art-quality.py`
+- `python scripts/check-unit-sprite-approval-gate.py --mode sample`
+- `python scripts/write-unit-sprite-next-steps.py`
+- `python scripts/check-unit-sprite-workflow-consistency.py`
+- Review the relevant `docs/unit-sprite-review-<batch>.png` by eye.
+- `pnpm build`
+- Local PC browser check.
+- For pending samples, local PC browser check with `?debug&debugSpritePreview=<unit-key>`.
+- Console errors: `0`.
+- Approval received for the batch before commit/push/deploy.
+
+## Commit/Deploy Gate
+
+Do not commit, push, or deploy when:
+
+- The current sample is still awaiting approval.
+- Any unit in the batch has failed the technical checks.
+- Any newly edited unit is still marked `pending-approval`.
+- Any untouched unit is accidentally counted as approved because it is only technically `ok`.
+- The review board shows the new unit is not visibly better than the old placeholder.
+- The browser check has not been run.
+- Console errors are present.
+
+After approval and successful verification:
+
+- Run `python scripts\promote-unit-sprite-approval.py --unit <unit-key> --expected-version <version>` so approved units move from `pendingApproval` to `approvedBaseline`.
+- Regenerate audit and review boards after the manifest update.
+- Run `python scripts/check-unit-sprite-approval-gate.py --mode release`.
+- Commit the batch changes.
+- Push to the Gitea remote.
+- Deploy to the NAS-hosted URL.
+- Provide the deployed URL and representative review images.

docs/unit-sprite-batch-queue.md

@@ -0,0 +1,192 @@
+# Unit Sprite Batch Queue
+
+This file is generated by `scripts/write-unit-sprite-batch-queue.py`.
+
+Use this as the long-running queue for the full hand-painted sprite rework. It is inventory and sequencing, not approval by itself.
+
+## Current State
+
+- Approved baseline units: 6
+- Pending approval units: 1
+- Queued rework units: 84
+- Manifest: `docs/unit-sprite-rework-manifest.json`
+- Audit: `docs/unit-sprite-rework-audit.json`
+
+## Approval Blocker
+
+Do not start the next unit, commit, push, or deploy while these units are pending:
+
+- `unit-shu-infantry`
+
+## Next After Approval
+
+1. `unit-shu-spearman` - spec `unit-sprite-batch2-shu-spearman-spec.md`
+2. `unit-shu-archer` - spec `unit-sprite-batch2-shu-archer-spec.md`
+3. `unit-shu-cavalry` - spec `unit-sprite-batch2-shu-cavalry-spec.md`
+4. `unit-shu-strategist` - spec `unit-sprite-batch2-shu-strategist-spec.md`
+5. `unit-shu-officer` - spec `unit-sprite-batch2-shu-officer-spec.md`
+
+## Batch Queue
+
+### Batch 1 approved core heroes
+
+- Batch key: `batch1-approved-core`
+- Total units: 3
+- Stage counts: approved-baseline 3
+
+| unit | role | stage | status | battle base px | spec |
+| --- | --- | --- | --- | --- | --- |
+| `unit-guan-yu` | approved reference | approved-baseline | technical ok | 30.4..43.1 x 44.1..46.5 |  |
+| `unit-liu-bei` | approved reference | approved-baseline | technical ok | 22.0..41.2 x 44.4..46.2 |  |
+| `unit-zhang-fei` | approved reference | approved-baseline | technical ok | 22.8..48.9 x 43.8..46.2 |  |
+
+### Batch 1 approved rebel references
+
+- Batch key: `batch1-approved-rebel`
+- Total units: 3
+- Stage counts: approved-baseline 3
+
+| unit | role | stage | status | battle base px | spec |
+| --- | --- | --- | --- | --- | --- |
+| `unit-rebel` | approved reference | approved-baseline | technical ok | 31.2..45.4 x 43.3..44.9 |  |
+| `unit-rebel-archer` | approved reference | approved-baseline | technical ok | 29.6..42.0 x 43.5..44.4 |  |
+| `unit-rebel-cavalry` | approved reference | approved-baseline | technical ok | 22.2..46.2 x 42.5..44.9 |  |
+
+### Batch 2 Shu generic units
+
+- Batch key: `batch2-shu`
+- Total units: 18
+- Stage counts: pending-approval 1, queued-rework 17
+
+| unit | role | stage | status | battle base px | spec |
+| --- | --- | --- | --- | --- | --- |
+| `unit-shu-infantry` | current approval sample | pending-approval | technical ok | 25.6..32.9 x 46.3..47.3 |  |
+| `unit-shu-spearman` | next primary queue | queued-rework | base border-hits=32; actions border-hits=82 | 31.0..40.6 x 44.6..44.6 | `unit-sprite-batch2-shu-spearman-spec.md` |
+| `unit-shu-archer` | next primary queue | queued-rework | base border-hits=64; actions border-hits=140 | 39.1..39.3 x 44.6..44.6 | `unit-sprite-batch2-shu-archer-spec.md` |
+| `unit-shu-cavalry` | next primary queue | queued-rework | base border-hits=64; actions border-hits=144 | 25.6..46.5 x 45.0..46.2 | `unit-sprite-batch2-shu-cavalry-spec.md` |
+| `unit-shu-strategist` | next primary queue | queued-rework | base border-hits=32; actions border-hits=98 | 38.8..39.3 x 44.7..44.9 | `unit-sprite-batch2-shu-strategist-spec.md` |
+| `unit-shu-officer` | next primary queue | queued-rework | base border-hits=32; actions border-hits=82 | 31.9..40.6 x 44.6..44.6 | `unit-sprite-batch2-shu-officer-spec.md` |
+| `unit-shu-archer-longbow` | queued rework | queued-rework | base border-hits=64; actions border-hits=140 | 39.1..39.3 x 44.6..44.6 |  |
+| `unit-shu-archer-veteran` | queued rework | queued-rework | base border-hits=64; actions border-hits=144 | 39.8..39.9 x 45.0..46.0 |  |
+| `unit-shu-cavalry-scout` | queued rework | queued-rework | base border-hits=64; actions border-hits=144 | 25.6..46.5 x 45.0..46.2 |  |
+| `unit-shu-cavalry-white` | queued rework | queued-rework | base border-hits=64; actions border-hits=144 | 25.6..46.5 x 45.0..46.2 |  |
+| `unit-shu-infantry-banner` | queued rework | queued-rework | base border-hits=32; actions border-hits=82 | 30.7..44.2 x 44.6..44.6 |  |
+| `unit-shu-infantry-guard` | queued rework | queued-rework | base border-hits=64; actions border-hits=144 | 31.6..44.7 x 45.0..46.0 |  |
+| `unit-shu-officer-council` | queued rework | queued-rework | base border-hits=32; actions border-hits=82 | 31.9..40.6 x 44.6..44.6 |  |
+| `unit-shu-officer-vanguard` | queued rework | queued-rework | base border-hits=64; actions border-hits=144 | 33.2..41.2 x 45.0..46.0 |  |
+| `unit-shu-spearman-guard` | queued rework | queued-rework | base border-hits=64; actions border-hits=144 | 32.3..41.2 x 45.0..46.0 |  |
+| `unit-shu-spearman-veteran` | queued rework | queued-rework | base border-hits=64; actions border-hits=144 | 32.3..41.2 x 45.0..46.0 |  |
+| `unit-shu-strategist-field` | queued rework | queued-rework | base border-hits=32; actions border-hits=98 | 38.8..39.3 x 44.7..44.9 |  |
+| `unit-shu-strategist-white` | queued rework | queued-rework | base border-hits=32; actions border-hits=98 | 38.8..39.3 x 44.7..44.9 |  |
+
+### Batch 3 Wei generic units
+
+- Batch key: `batch3-wei`
+- Total units: 16
+- Stage counts: queued-rework 16
+
+| unit | role | stage | status | battle base px | spec |
+| --- | --- | --- | --- | --- | --- |
+| `unit-wei-archer` | queued rework | queued-rework | base border-hits=64; actions border-hits=140 | 39.1..39.3 x 44.6..44.6 |  |
+| `unit-wei-archer-crossbow` | queued rework | queued-rework | base border-hits=64; actions border-hits=144 | 39.1..39.3 x 44.6..44.6 |  |
+| `unit-wei-archer-veteran` | queued rework | queued-rework | base border-hits=64; actions border-hits=144 | 39.8..39.9 x 45.0..46.0 |  |
+| `unit-wei-cavalry` | queued rework | queued-rework | base border-hits=64; actions border-hits=144 | 25.6..46.5 x 45.0..46.2 |  |
+| `unit-wei-cavalry-elite` | queued rework | queued-rework | base border-hits=64; actions border-hits=144 | 26.5..47.3 x 45.0..46.0 |  |
+| `unit-wei-cavalry-iron` | queued rework | queued-rework | base border-hits=64; actions border-hits=144 | 26.5..47.3 x 45.0..46.0 |  |
+| `unit-wei-infantry` | queued rework | queued-rework | base border-hits=32; actions border-hits=82 | 30.7..44.2 x 44.6..44.6 |  |
+| `unit-wei-infantry-shield` | queued rework | queued-rework | base border-hits=32; actions border-hits=82 | 30.7..44.2 x 44.6..44.6 |  |
+| `unit-wei-infantry-veteran` | queued rework | queued-rework | base border-hits=64; actions border-hits=144 | 31.6..44.7 x 45.0..46.0 |  |
+| `unit-wei-officer` | queued rework | queued-rework | base border-hits=32; actions border-hits=82 | 31.9..40.6 x 44.6..44.6 |  |
+| `unit-wei-officer-gate` | queued rework | queued-rework | base border-hits=32; actions border-hits=82 | 31.9..40.6 x 44.6..44.6 |  |
+| `unit-wei-officer-iron` | queued rework | queued-rework | base border-hits=64; actions border-hits=144 | 33.2..41.2 x 45.0..46.0 |  |
+| `unit-wei-strategist` | queued rework | queued-rework | base border-hits=32; actions border-hits=98 | 38.8..39.3 x 44.7..44.9 |  |
+| `unit-wei-strategist-black` | queued rework | queued-rework | base border-hits=32; actions border-hits=98 | 38.8..39.3 x 44.7..44.9 |  |
+| `unit-wei-strategist-blue` | queued rework | queued-rework | base border-hits=32; actions border-hits=98 | 38.8..39.3 x 44.7..44.9 |  |
+| `unit-wei-yan` | queued rework | queued-rework | base border-hits=32; actions border-hits=82 | 31.0..40.6 x 44.6..44.6 |  |
+
+### Batch 4 Wu generic units
+
+- Batch key: `batch4-wu`
+- Total units: 16
+- Stage counts: queued-rework 16
+
+| unit | role | stage | status | battle base px | spec |
+| --- | --- | --- | --- | --- | --- |
+| `unit-wu-archer` | queued rework | queued-rework | base border-hits=64; actions border-hits=140 | 39.1..39.3 x 44.6..44.6 |  |
+| `unit-wu-archer-naval` | queued rework | queued-rework | base border-hits=64; actions border-hits=140 | 39.1..39.3 x 44.6..44.6 |  |
+| `unit-wu-archer-river` | queued rework | queued-rework | base border-hits=64; actions border-hits=140 | 39.1..39.3 x 44.6..44.6 |  |
+| `unit-wu-cavalry` | queued rework | queued-rework | base border-hits=64; actions border-hits=144 | 25.6..46.5 x 45.0..46.2 |  |
+| `unit-wu-cavalry-elite` | queued rework | queued-rework | base border-hits=64; actions border-hits=144 | 26.5..47.3 x 45.0..46.0 |  |
+| `unit-wu-cavalry-river` | queued rework | queued-rework | base border-hits=64; actions border-hits=144 | 25.6..46.5 x 45.0..46.2 |  |
+| `unit-wu-infantry` | queued rework | queued-rework | base border-hits=32; actions border-hits=82 | 30.7..44.2 x 44.6..44.6 |  |
+| `unit-wu-infantry-marine` | queued rework | queued-rework | base border-hits=32; actions border-hits=82 | 30.7..44.2 x 44.6..44.6 |  |
+| `unit-wu-infantry-river` | queued rework | queued-rework | base border-hits=32; actions border-hits=82 | 30.7..44.2 x 44.6..44.6 |  |
+| `unit-wu-officer` | queued rework | queued-rework | base border-hits=32; actions border-hits=82 | 31.9..40.6 x 44.6..44.6 |  |
+| `unit-wu-officer-harbor` | queued rework | queued-rework | base border-hits=32; actions border-hits=82 | 31.9..40.6 x 44.6..44.6 |  |
+| `unit-wu-officer-river` | queued rework | queued-rework | base border-hits=32; actions border-hits=82 | 31.9..40.6 x 44.6..44.6 |  |
+| `unit-wu-strategist` | queued rework | queued-rework | base border-hits=32; actions border-hits=98 | 38.8..39.3 x 44.7..44.9 |  |
+| `unit-wu-strategist-fire` | queued rework | queued-rework | base border-hits=32; actions border-hits=98 | 38.8..39.3 x 44.7..44.9 |  |
+| `unit-wu-strategist-river` | queued rework | queued-rework | base border-hits=32; actions border-hits=98 | 38.8..39.3 x 44.7..44.9 |  |
+| `unit-wu-yi` | queued rework | queued-rework | base border-hits=32; actions border-hits=82 | 31.9..40.6 x 44.6..44.6 |  |
+
+### Batch 5 remaining rebel/bandit units
+
+- Batch key: `batch5-rebel-other`
+- Total units: 6
+- Stage counts: queued-rework 6
+
+| unit | role | stage | status | battle base px | spec |
+| --- | --- | --- | --- | --- | --- |
+| `unit-rebel-archer-fire` | queued rework | queued-rework | base border-hits=64; actions border-hits=140 | 39.1..39.3 x 42.5..42.5 |  |
+| `unit-rebel-archer-veteran` | queued rework | queued-rework | base border-hits=64; actions border-hits=140 | 39.8..39.9 x 44.1..44.2 |  |
+| `unit-rebel-cavalry-veteran` | queued rework | queued-rework | base border-hits=64; actions border-hits=144 | 26.5..47.3 x 45.0..46.0 |  |
+| `unit-rebel-leader` | queued rework | queued-rework | base border-hits=32; actions border-hits=72 | 31.9..40.6 x 42.5..42.5 |  |
+| `unit-rebel-leader-warlord` | queued rework | queued-rework | base border-hits=32; actions border-hits=78 | 35.8..42.5 x 44.1..44.2 |  |
+| `unit-rebel-ragged` | queued rework | queued-rework | base border-hits=32; actions border-hits=72 | 30.7..44.2 x 42.5..42.5 |  |
+
+### Batch 6 Nanman/special units
+
+- Batch key: `batch6-nanman-special`
+- Total units: 10
+- Stage counts: queued-rework 10
+
+| unit | role | stage | status | battle base px | spec |
+| --- | --- | --- | --- | --- | --- |
+| `unit-meng-huo` | queued rework | queued-rework | base border-hits=32; actions border-hits=82 | 33.2..45.5 x 44.6..44.6 |  |
+| `unit-nanman-infantry` | queued rework | queued-rework | base border-hits=32; actions border-hits=82 | 30.7..44.2 x 44.6..44.6 |  |
+| `unit-nanman-infantry-jungle` | queued rework | queued-rework | base border-hits=32; actions border-hits=82 | 30.7..44.2 x 44.6..44.6 |  |
+| `unit-nanman-infantry-spear` | queued rework | queued-rework | base border-hits=32; actions border-hits=82 | 30.7..44.2 x 44.6..44.6 |  |
+| `unit-nanman-officer` | queued rework | queued-rework | base border-hits=32; actions border-hits=82 | 31.9..40.6 x 44.6..44.6 |  |
+| `unit-nanman-officer-bronze` | queued rework | queued-rework | base border-hits=64; actions border-hits=144 | 33.2..41.2 x 45.0..46.0 |  |
+| `unit-nanman-officer-warlord` | queued rework | queued-rework | base border-hits=64; actions border-hits=144 | 35.8..42.5 x 45.0..46.0 |  |
+| `unit-nanman-shaman` | queued rework | queued-rework | base border-hits=32; actions border-hits=98 | 38.8..39.3 x 44.7..44.9 |  |
+| `unit-nanman-shaman-ember` | queued rework | queued-rework | base border-hits=32; actions border-hits=98 | 38.8..39.3 x 44.7..44.9 |  |
+| `unit-nanman-shaman-storm` | queued rework | queued-rework | base border-hits=32; actions border-hits=98 | 38.8..39.3 x 44.7..44.9 |  |
+
+### Batch 7 unique officers
+
+- Batch key: `batch7-unique-officer`
+- Total units: 19
+- Stage counts: queued-rework 19
+
+| unit | role | stage | status | battle base px | spec |
+| --- | --- | --- | --- | --- | --- |
+| `unit-cao-cao` | queued rework | queued-rework | base border-hits=64; actions border-hits=144 | 33.2..43.3 x 45.0..46.0 |  |
+| `unit-fa-zheng` | queued rework | queued-rework | base border-hits=32; actions border-hits=98 | 38.8..39.3 x 44.7..44.9 |  |
+| `unit-gong-zhi` | queued rework | queued-rework | base border-hits=32; actions border-hits=82 | 31.9..40.6 x 44.6..44.6 |  |
+| `unit-huang-quan` | queued rework | queued-rework | base border-hits=32; actions border-hits=82 | 31.9..40.6 x 44.6..44.6 |  |
+| `unit-huang-zhong` | queued rework | queued-rework | base border-hits=64; actions border-hits=140 | 39.1..39.3 x 44.6..44.6 |  |
+| `unit-jiang-wei` | queued rework | queued-rework | base border-hits=32; actions border-hits=82 | 31.0..40.6 x 44.6..44.6 |  |
+| `unit-li-yan` | queued rework | queued-rework | base border-hits=32; actions border-hits=82 | 31.9..40.6 x 44.6..44.6 |  |
+| `unit-lu-bu` | queued rework | queued-rework | base border-hits=64; actions border-hits=144 | 28.8..47.3 x 45.0..46.0 |  |
+| `unit-lu-meng` | queued rework | queued-rework | base border-hits=32; actions border-hits=82 | 30.7..44.2 x 44.6..44.6 |  |
+| `unit-ma-chao` | queued rework | queued-rework | base border-hits=64; actions border-hits=144 | 26.5..47.3 x 45.0..46.0 |  |
+| `unit-ma-dai` | queued rework | queued-rework | base border-hits=64; actions border-hits=144 | 25.6..46.5 x 45.0..46.2 |  |
+| `unit-ma-liang` | queued rework | queued-rework | base border-hits=32; actions border-hits=98 | 38.8..39.3 x 44.7..44.9 |  |
+| `unit-pang-tong` | queued rework | queued-rework | base border-hits=32; actions border-hits=98 | 38.8..39.3 x 44.7..44.9 |  |
+| `unit-sima-yi` | queued rework | queued-rework | base border-hits=32; actions border-hits=98 | 38.8..39.3 x 44.7..44.9 |  |
+| `unit-wang-ping` | queued rework | queued-rework | base border-hits=32; actions border-hits=82 | 31.9..40.6 x 44.6..44.6 |  |
+| `unit-yan-yan` | queued rework | queued-rework | base border-hits=32; actions border-hits=82 | 31.0..40.6 x 44.6..44.6 |  |
+| `unit-yi-ji` | queued rework | queued-rework | base border-hits=32; actions border-hits=98 | 38.8..39.3 x 44.7..44.9 |  |
+| `unit-zhao-yun` | queued rework | queued-rework | base border-hits=64; actions border-hits=144 | 26.5..47.3 x 45.0..46.0 |  |
+| `unit-zhuge-liang` | queued rework | queued-rework | base border-hits=32; actions border-hits=98 | 38.8..39.3 x 44.7..44.9 |  |

docs/unit-sprite-batch2-shu-archer-spec.md

@@ -0,0 +1,64 @@
+# Batch 2 Shu Archer Production Spec
+
+Use this only after `unit-shu-infantry` v3 is approved and the current queue reaches `unit-shu-archer`.
+
+## Target
+
+- Unit key: `unit-shu-archer`
+- Batch: Batch 2 Shu generic units
+- Role: generic Shu bow infantry
+- Style reference:
+  - `unit-liu-bei`
+  - `unit-guan-yu`
+  - `unit-zhang-fei`
+  - `unit-shu-infantry` v3
+- Required output sheets:
+  - `src/assets/images/units/unit-shu-archer.png`
+  - `src/assets/images/units/unit-shu-archer-actions.png`
+
+## Visual Direction
+
+- Must read as a bow unit at 50px battle scale.
+- Bow curve and arrow line must be visible in idle, walk, and attack poses.
+- Body should be leaner than infantry but not thin or low-contrast.
+- Use green Shu cloth, bronze leather armor, yellow-green sash, dark outline, and large readable color blocks.
+- Keep bow, quiver, and arrow contained inside each 313px frame.
+- No detached arrow fragments in idle/walk; action arrow effects must be reviewed and contained.
+- Do not solve readability with base rings, badges, glows, or UI decoration.
+
+## Source Image Prompt
+
+```text
+Use case: stylized-concept
+Asset type: production source image for a tactical RPG unit sprite sheet
+Primary request: Create a high-quality hand-painted raster contact sheet for ONE Shu archer unit, in the same production style as the approved Shu infantry v3 sample but clearly differentiated by a readable bow silhouette.
+Scene/backdrop: perfectly flat solid #ff00ff chroma-key background only, no shadows, no floor plane, no texture, no text.
+Subject: original Three Kingdoms-inspired Shu archer infantry, no copyrighted game assets, no logos. Green cloth coat, bronze leather armor plates, yellow-green sash, dark boots, small helmet or headwrap, quiver on back or hip, curved wooden bow and visible arrows. The character should look like an elite generic Shu field archer.
+Style/medium: premium hand-painted pixel-adjacent raster game art, bold dark ink outline, large readable color masses, crisp opaque body shapes, subtle painted fabric folds, tactical RPG battle sprite source art.
+Composition/framing: 6 columns by 2 rows contact sheet, twelve separate full-body frames, each frame centered with generous padding and the entire bow visible. No cropping. Keep each figure around 76-82% of its cell height with stable body scale and ground position across all frames.
+Frames left to right, top row: front idle holding bow vertically, front walk step, east walk side with bow carried forward, back walk with quiver visible, west walk side mirrored pose, attack windup drawing bow. Bottom row: arrow release with bow fully drawn, follow-through with bow lowered, command gesture, item/strategy gesture, hurt recoil, victory pose raising bow.
+Animation constraints: each frame should be newly drawn with natural pose differences in arms, legs, bow, quiver, sash, and cloth folds, but body size must remain stable. Idle should not twist sideways. Walk frames should not drift far horizontally. Action frames must stay inside their cell.
+Readability constraints: at 50px game scale the bow arc, arrow gesture, green Shu armor, and archer body block must read before the background. Use thicker silhouette, deeper shadows, stronger outline, fewer tiny details, clear weapon shape.
+Avoid: thin line art, transparent body pixels, ghostly low opacity, tiny head, overly realistic painting, chibi proportions, blurred edges, cropped bow limb, detached arrow fragments, labels, captions, watermarks, UI, grid lines, checker backgrounds, duplicated identical frames.
+```
+
+## Expected Artifacts
+
+- Source: `docs/handpaint-batch2-shu-archer-source-v1.png`
+- Contact sheet: `docs/handpaint-batch2-shu-archer-contact.png`
+- Animation GIF: `docs/handpaint-batch2-shu-archer-animation.gif`
+- Previous/new comparison: `docs/handpaint-batch2-shu-archer-before-after.png`
+- Battle-scale comparison: `docs/handpaint-batch2-shu-archer-scale-compare.png`
+- Battle map composite: `docs/handpaint-batch2-shu-archer-battle-composite.png`
+- Report: `docs/handpaint-batch2-shu-archer-report.md`
+
+## Validation Targets
+
+- Base partial alpha: `0`
+- Action partial alpha: `0`
+- Base frame border hits: `0`
+- Action frame border hits: `0`
+- Base sheet size: `5008x1252`
+- Action sheet size: `11268x1252`
+- `unit-shu-archer` must appear as `ok` in `docs/unit-sprite-rework-audit.json`
+- `unit-sprite-review-batch2-shu.png` must show `unit-shu-archer` as visually stronger than the old placeholder.

docs/unit-sprite-batch2-shu-cavalry-spec.md

@@ -0,0 +1,65 @@
+# Batch 2 Shu Cavalry Production Spec
+
+Use this only after `unit-shu-infantry` v3 is approved and the current queue reaches `unit-shu-cavalry`.
+
+## Target
+
+- Unit key: `unit-shu-cavalry`
+- Batch: Batch 2 Shu generic units
+- Role: generic Shu horse cavalry
+- Style reference:
+  - `unit-liu-bei`
+  - `unit-guan-yu`
+  - `unit-zhang-fei`
+  - `unit-rebel-cavalry`
+  - `unit-shu-infantry` v3
+- Required output sheets:
+  - `src/assets/images/units/unit-shu-cavalry.png`
+  - `src/assets/images/units/unit-shu-cavalry-actions.png`
+
+## Visual Direction
+
+- Must read as horse and rider at 50px battle scale.
+- Horse silhouette is the priority: head, chest, legs, saddle, and rider must read as one stable unit.
+- Rider should carry a short spear or saber without pushing the frame outside tile limits.
+- Use green Shu saddle cloth, bronze armor, tan/brown horse, dark outline, and large readable color blocks.
+- Movement must not drift sideways across frames; cavalry previously caused tile-boundary discomfort, so containment is strict.
+- Do not solve readability with base rings, badges, glows, or UI decoration.
+
+## Source Image Prompt
+
+```text
+Use case: stylized-concept
+Asset type: production source image for a tactical RPG mounted unit sprite sheet
+Primary request: Create a high-quality hand-painted raster contact sheet for ONE Shu cavalry unit, in the same production style as the approved hand-painted units but clearly differentiated by a compact horse-and-rider silhouette.
+Scene/backdrop: perfectly flat solid #ff00ff chroma-key background only, no shadows, no floor plane, no texture, no text.
+Subject: original Three Kingdoms-inspired Shu cavalry soldier, no copyrighted game assets, no logos. Brown warhorse with compact strong body, green Shu saddle cloth, bronze tack, mounted rider in green-and-bronze armor, short spear or saber, small cloak and dark boots. The character should look like an elite generic Shu cavalryman, not a named hero.
+Style/medium: premium hand-painted pixel-adjacent raster game art, bold dark ink outline, large readable color masses, crisp opaque body shapes, subtle painted armor and horse highlights, tactical RPG battle sprite source art.
+Composition/framing: 6 columns by 2 rows contact sheet, twelve separate full-body mounted frames, each frame centered with generous padding and the entire horse/rider visible. No cropping. Keep horse and rider around 76-84% of cell height and 78-88% of cell width, with stable body scale and ground position across frames.
+Frames left to right, top row: front idle horse facing forward, front walk step, east walk side, back walk, west walk side mirrored pose, attack windup with rider weapon raised. Bottom row: mounted strike, mounted follow-through, command gesture, item/strategy gesture, hurt recoil, victory pose with rider raising weapon.
+Animation constraints: each frame should be newly drawn with natural pose differences in horse legs, rider arms, reins, saddle cloth, and weapon, but total mounted silhouette size must remain stable. Idle should breathe subtly without twisting. Walk frames should not slide far horizontally. Action frames must stay inside their cell.
+Readability constraints: at 50px game scale the horse body, rider torso, green saddle cloth, and mounted weapon must read before the background. Use thick silhouette, deep shadows, strong outline, fewer tiny details, and clear mounted posture.
+Avoid: thin line art, transparent body pixels, ghostly low opacity, tiny horse legs, overly realistic painting, chibi proportions, blurred edges, cropped horse head, cropped weapon tip, detached leg/tail/weapon fragments, excessive sideways drift, labels, captions, watermarks, UI, grid lines, checker backgrounds, duplicated identical frames.
+```
+
+## Expected Artifacts
+
+- Source: `docs/handpaint-batch2-shu-cavalry-source-v1.png`
+- Contact sheet: `docs/handpaint-batch2-shu-cavalry-contact.png`
+- Animation GIF: `docs/handpaint-batch2-shu-cavalry-animation.gif`
+- Previous/new comparison: `docs/handpaint-batch2-shu-cavalry-before-after.png`
+- Battle-scale comparison: `docs/handpaint-batch2-shu-cavalry-scale-compare.png`
+- Battle map composite: `docs/handpaint-batch2-shu-cavalry-battle-composite.png`
+- Report: `docs/handpaint-batch2-shu-cavalry-report.md`
+
+## Validation Targets
+
+- Base partial alpha: `0`
+- Action partial alpha: `0`
+- Base frame border hits: `0`
+- Action frame border hits: `0`
+- Base sheet size: `5008x1252`
+- Action sheet size: `11268x1252`
+- `unit-shu-cavalry` must appear as `ok` in `docs/unit-sprite-rework-audit.json`
+- Cavalry must not visibly overflow or drift outside the square tile at battle scale.
+- `unit-sprite-review-batch2-shu.png` must show `unit-shu-cavalry` as visually stronger than the old placeholder.

docs/unit-sprite-batch2-shu-officer-spec.md

@@ -0,0 +1,64 @@
+# Batch 2 Shu Officer Production Spec
+
+Use this only after `unit-shu-infantry` v3 is approved and the current queue reaches `unit-shu-officer`.
+
+## Target
+
+- Unit key: `unit-shu-officer`
+- Batch: Batch 2 Shu generic units
+- Role: generic Shu field officer
+- Style reference:
+  - `unit-liu-bei`
+  - `unit-guan-yu`
+  - `unit-zhang-fei`
+  - `unit-shu-infantry` v3
+- Required output sheets:
+  - `src/assets/images/units/unit-shu-officer.png`
+  - `src/assets/images/units/unit-shu-officer-actions.png`
+
+## Visual Direction
+
+- Must read as a command/officer unit at 50px battle scale, not as a basic infantry clone.
+- Command baton, banner tassel, sword, or formal shoulder armor should identify the class.
+- Use deeper green cloak/tabard, bronze officer armor, red-gold command accents, dark outline, and large readable color blocks.
+- Silhouette should be more upright and authoritative than infantry but less heroic than Liu Bei/Guan Yu/Zhang Fei.
+- Keep command props contained inside each 313px frame.
+- Do not solve readability with base rings, badges, glows, or UI decoration.
+
+## Source Image Prompt
+
+```text
+Use case: stylized-concept
+Asset type: production source image for a tactical RPG officer unit sprite sheet
+Primary request: Create a high-quality hand-painted raster contact sheet for ONE Shu field officer unit, in the same production style as the approved hand-painted units but clearly differentiated by command posture and officer equipment.
+Scene/backdrop: perfectly flat solid #ff00ff chroma-key background only, no shadows, no floor plane, no texture, no text.
+Subject: original Three Kingdoms-inspired Shu field officer, no copyrighted game assets, no logos. Deep green cloak or officer tabard, bronze lamellar armor, red-gold command sash, short sword or command baton, optional small back banner/tassel, sturdy boots, helmet or tied hair. The character should look like an elite generic Shu officer, not Liu Bei or any named hero.
+Style/medium: premium hand-painted pixel-adjacent raster game art, bold dark ink outline, large readable color masses, crisp opaque body shapes, subtle painted armor highlights and cloak folds, tactical RPG battle sprite source art.
+Composition/framing: 6 columns by 2 rows contact sheet, twelve separate full-body frames, each frame centered with generous padding and all command props visible. No cropping. Keep each figure around 80-86% of its cell height with stable body scale and ground position across all frames.
+Frames left to right, top row: front idle authoritative stance, front walk step, east walk side with cloak and sword/baton, back walk with cloak/banner visible, west walk side mirrored pose, attack windup with officer weapon raised. Bottom row: sword/baton strike, command sweep or follow-through, command gesture pointing forward, item/strategy gesture, hurt recoil, victory pose raising command item.
+Animation constraints: each frame should be newly drawn with natural pose differences in arms, legs, cloak, banner tassel, and weapon, but body size must remain stable. Idle should not twist sideways. Walk frames should not drift far horizontally. Action frames must stay inside their cell.
+Readability constraints: at 50px game scale the officer cloak/tabard, command prop, green Shu palette, and upright command silhouette must read before the background. Use thick silhouette, deep shadows, strong outline, fewer tiny details, and clear officer posture.
+Avoid: thin line art, transparent body pixels, ghostly low opacity, tiny head, overly realistic painting, chibi proportions, blurred edges, cropped banner or sword, detached tassel fragments, overly heroic named-character design, labels, captions, watermarks, UI, grid lines, checker backgrounds, duplicated identical frames.
+```
+
+## Expected Artifacts
+
+- Source: `docs/handpaint-batch2-shu-officer-source-v1.png`
+- Contact sheet: `docs/handpaint-batch2-shu-officer-contact.png`
+- Animation GIF: `docs/handpaint-batch2-shu-officer-animation.gif`
+- Previous/new comparison: `docs/handpaint-batch2-shu-officer-before-after.png`
+- Battle-scale comparison: `docs/handpaint-batch2-shu-officer-scale-compare.png`
+- Battle map composite: `docs/handpaint-batch2-shu-officer-battle-composite.png`
+- Report: `docs/handpaint-batch2-shu-officer-report.md`
+
+## Validation Targets
+
+- Base partial alpha: `0`
+- Action partial alpha: `0`
+- Base frame border hits: `0`
+- Action frame border hits: `0`
+- Base sheet size: `5008x1252`
+- Action sheet size: `11268x1252`
+- `unit-shu-officer` must appear as `ok` in `docs/unit-sprite-rework-audit.json`
+- Officer silhouette must read differently from infantry and strategist at 50px.
+- `unit-sprite-review-batch2-shu.png` must show `unit-shu-officer` as visually stronger than the old placeholder.

docs/unit-sprite-batch2-shu-spearman-spec.md

@@ -0,0 +1,64 @@
+# Batch 2 Shu Spearman Production Spec
+
+Use this only after `unit-shu-infantry` v3 is approved.
+
+## Target
+
+- Unit key: `unit-shu-spearman`
+- Batch: Batch 2 Shu generic units
+- Role: generic Shu spear infantry
+- Style reference:
+  - `unit-liu-bei`
+  - `unit-guan-yu`
+  - `unit-zhang-fei`
+  - `unit-shu-infantry` v3
+- Required output sheets:
+  - `src/assets/images/units/unit-shu-spearman.png`
+  - `src/assets/images/units/unit-shu-spearman-actions.png`
+
+## Visual Direction
+
+- Must read as a spear unit at 50px battle scale.
+- Long spear silhouette should be visible in every side-facing combat/walk frame.
+- Body should be broad enough to match the v3 infantry quality bar, but slightly leaner than Zhang Fei.
+- Use green Shu cloth/armor with bronze/gold plates, dark outline, and large readable color blocks.
+- Use a sturdy foot-soldier stance, not a unique hero pose.
+- Keep the spear contained inside each 313px frame; no detached shaft/tip fragments.
+- Do not solve readability with base rings, badges, glows, or UI decoration.
+
+## Source Image Prompt
+
+```text
+Use case: stylized-concept
+Asset type: production source image for a tactical RPG unit sprite sheet
+Primary request: Create a high-quality hand-painted raster contact sheet for ONE Shu spearman unit, in the same production style as the approved Shu infantry v3 sample but clearly differentiated by a long spear silhouette.
+Scene/backdrop: perfectly flat solid #ff00ff chroma-key background only, no shadows, no floor plane, no texture, no text.
+Subject: original Three Kingdoms-inspired Shu spear infantry, not Guan Yu, not Zhang Fei, no copyrighted game assets, no logos. Green-and-bronze lamellar armor, long spear/qiang, compact round or small strapped shield only if it does not obscure the spear, sturdy boots, dark hair topknot or helmet, small cloak/tabard. The character should look like an elite generic Shu spear soldier.
+Style/medium: premium hand-painted pixel-adjacent raster game art, bold dark ink outline, large readable color masses, crisp opaque body shapes, subtle painted armor highlights, tactical RPG battle sprite source art.
+Composition/framing: 6 columns by 2 rows contact sheet, twelve separate full-body frames, each frame centered with generous padding and the entire spear visible. No cropping. Keep each figure around 78-84% of its cell height with stable body scale and ground position across all frames.
+Frames left to right, top row: front idle with spear upright, front walk step, east walk side with spear angled forward, back walk with spear visible behind shoulder, west walk side mirrored pose, attack windup with spear pulled back. Bottom row: spear thrust with readable forward line, sweeping spear slash, command gesture, item/strategy gesture, hurt recoil, victory pose.
+Animation constraints: each frame should be newly drawn with natural pose differences in arms, legs, spear, cloak and cloth folds, but body size must remain stable. Idle should not twist sideways. Walk frames should not drift far horizontally. Action frames must stay inside their cell.
+Readability constraints: at 50px game scale the spear line, green Shu armor, and infantry body block must read before the background. Use thicker silhouette, deeper shadows, stronger outline, fewer tiny details, clear weapon shape.
+Avoid: thin line art, transparent body pixels, ghostly low opacity, tiny head, overly realistic painting, chibi proportions, blurred edges, cropped spear tip, detached spear fragments, labels, captions, watermarks, UI, grid lines, checker backgrounds, duplicated identical frames.
+```
+
+## Expected Artifacts
+
+- Source: `docs/handpaint-batch2-shu-spearman-source-v1.png`
+- Contact sheet: `docs/handpaint-batch2-shu-spearman-contact.png`
+- Animation GIF: `docs/handpaint-batch2-shu-spearman-animation.gif`
+- Previous/new comparison: `docs/handpaint-batch2-shu-spearman-before-after.png`
+- Battle-scale comparison: `docs/handpaint-batch2-shu-spearman-scale-compare.png`
+- Battle map composite: `docs/handpaint-batch2-shu-spearman-battle-composite.png`
+- Report: `docs/handpaint-batch2-shu-spearman-report.md`
+
+## Validation Targets
+
+- Base partial alpha: `0`
+- Action partial alpha: `0`
+- Base frame border hits: `0`
+- Action frame border hits: `0`
+- Base sheet size: `5008x1252`
+- Action sheet size: `11268x1252`
+- `unit-shu-spearman` must appear as `ok` in `docs/unit-sprite-rework-audit.json`
+- `unit-sprite-review-batch2-shu.png` must show `unit-shu-spearman` as visually stronger than the old placeholder.

docs/unit-sprite-batch2-shu-strategist-spec.md

@@ -0,0 +1,63 @@
+# Batch 2 Shu Strategist Production Spec
+
+Use this only after `unit-shu-infantry` v3 is approved and the current queue reaches `unit-shu-strategist`.
+
+## Target
+
+- Unit key: `unit-shu-strategist`
+- Batch: Batch 2 Shu generic units
+- Role: generic Shu tactician/strategist
+- Style reference:
+  - `unit-liu-bei`
+  - `unit-shu-infantry` v3
+  - approved hand-painted batch 1 readability
+- Required output sheets:
+  - `src/assets/images/units/unit-shu-strategist.png`
+  - `src/assets/images/units/unit-shu-strategist-actions.png`
+
+## Visual Direction
+
+- Must read as a strategist at 50px battle scale, not as a plain infantry unit.
+- Fan, scroll, robe silhouette, and calm upright posture should identify the class.
+- Use green/cream Shu robes with bronze belt details and a dark outline.
+- Keep robes broad enough to read, with simple large folds and no wispy transparent edges.
+- Strategy action frames may include contained painted effect shapes, but no detached idle/walk fragments.
+- Do not solve readability with base rings, badges, glows, or UI decoration.
+
+## Source Image Prompt
+
+```text
+Use case: stylized-concept
+Asset type: production source image for a tactical RPG strategist unit sprite sheet
+Primary request: Create a high-quality hand-painted raster contact sheet for ONE Shu strategist unit, in the same production style as the approved hand-painted units but clearly differentiated by fan, scroll, and robe silhouette.
+Scene/backdrop: perfectly flat solid #ff00ff chroma-key background only, no shadows, no floor plane, no texture, no text.
+Subject: original Three Kingdoms-inspired Shu strategist, no copyrighted game assets, no logos. Green and cream layered robes, bronze belt plate, dark boots, scholar cap or tied hair, feather fan or folded war fan, small scroll case. The character should look like an elite generic Shu tactician, not Zhuge Liang or another named hero.
+Style/medium: premium hand-painted pixel-adjacent raster game art, bold dark ink outline, large readable color masses, crisp opaque body shapes, subtle painted robe folds, tactical RPG battle sprite source art.
+Composition/framing: 6 columns by 2 rows contact sheet, twelve separate full-body frames, each frame centered with generous padding and the entire fan/scroll visible. No cropping. Keep each figure around 78-84% of its cell height with stable body scale and ground position across all frames.
+Frames left to right, top row: front idle holding fan, front walk step, east walk side with robe and fan visible, back walk with scroll case, west walk side mirrored pose, strategy windup raising fan. Bottom row: strategy cast with contained scroll/fan gesture, second strategy pose with robe sweep, command gesture, item gesture, hurt recoil, victory pose with fan lifted.
+Animation constraints: each frame should be newly drawn with natural pose differences in sleeves, robe hem, fan angle, head, and arms, but body size must remain stable. Idle should not twist sideways. Walk frames should not drift far horizontally. Action frames must stay inside their cell.
+Readability constraints: at 50px game scale the fan shape, robe mass, green Shu palette, and strategist posture must read before the background. Use thick silhouette, deep shadows, strong outline, fewer tiny details, and clear class props.
+Avoid: thin line art, transparent body pixels, ghostly low opacity, tiny head, overly realistic painting, chibi proportions, blurred edges, cropped fan, detached spell fragments in idle/walk, excessive glowing effects, labels, captions, watermarks, UI, grid lines, checker backgrounds, duplicated identical frames.
+```
+
+## Expected Artifacts
+
+- Source: `docs/handpaint-batch2-shu-strategist-source-v1.png`
+- Contact sheet: `docs/handpaint-batch2-shu-strategist-contact.png`
+- Animation GIF: `docs/handpaint-batch2-shu-strategist-animation.gif`
+- Previous/new comparison: `docs/handpaint-batch2-shu-strategist-before-after.png`
+- Battle-scale comparison: `docs/handpaint-batch2-shu-strategist-scale-compare.png`
+- Battle map composite: `docs/handpaint-batch2-shu-strategist-battle-composite.png`
+- Report: `docs/handpaint-batch2-shu-strategist-report.md`
+
+## Validation Targets
+
+- Base partial alpha: `0`
+- Action partial alpha: `0`
+- Base frame border hits: `0`
+- Action frame border hits: `0`
+- Base sheet size: `5008x1252`
+- Action sheet size: `11268x1252`
+- `unit-shu-strategist` must appear as `ok` in `docs/unit-sprite-rework-audit.json`
+- Fan/robe silhouette must be readable at 50px without relying on effects.
+- `unit-sprite-review-batch2-shu.png` must show `unit-shu-strategist` as visually stronger than the old placeholder.

docs/unit-sprite-handpaint-pipeline-guide.md

@@ -0,0 +1,156 @@
+# Hand-Painted Sprite Pipeline Guide
+
+This guide captures the current approved/pending workflow so future unit work stays consistent.
+
+## Current Gate
+
+- Review state manifest: `unit-sprite-rework-manifest.json`.
+- Do not produce the next unit until `unit-shu-infantry` v3 is approved.
+- Do not commit, push, or deploy while a sample is pending approval.
+- Current pending sample: `docs/unit-sprite-shu-infantry-v3-approval-packet.md`.
+- Current visual approval board: `docs/unit-sprite-current-approval-board.png`.
+- Next prepared target after approval: `docs/unit-sprite-batch2-shu-spearman-spec.md`.
+
+## Source Image Contract
+
+Generate each unit as a 6 column x 2 row contact sheet on a flat `#ff00ff` background.
+
+Required 12 cells:
+
+1. front idle
+2. front walk step
+3. east walk side
+4. back walk
+5. west walk side
+6. attack windup
+7. attack strike 1
+8. attack strike 2
+9. command gesture
+10. item/strategy gesture
+11. hurt recoil
+12. victory pose
+
+The source image must have:
+
+- full-body figures, no cropping
+- stable scale across cells
+- no labels, UI, grid lines, watermark, or checker background
+- weapon/class silhouette visible at 50px
+- enough padding that weapon tips can be contained in 313px frames
+
+## Sheet Assembly Contract
+
+The generated source is converted into:
+
+- Base sheet: `5008x1252`, 4 rows x 16 frames
+- Action sheet: `11268x1252`, 4 rows x 36 frames
+- Frame size: `313x313`
+- Direction rows: south, east, north, west
+- Base columns: 8 idle + 8 walk per direction
+- Action groups: attack 10, strategy 8, item 8, hurt 4, celebrate 6
+
+The current reference implementation is `scripts/assemble-handpaint-shu-infantry-quality-sample.py`.
+
+Default execution regenerates the pending Shu infantry v3 sample:
+
+```powershell
+python scripts\assemble-handpaint-shu-infantry-quality-sample.py
+```
+
+After `unit-shu-infantry` v3 is approved, reuse the same assembler for the next unit by changing only the source, stem, titles, labels, and output prefix. Example for the prepared Shu spearman target:
+
+```powershell
+python scripts\assemble-handpaint-shu-infantry-quality-sample.py `
+  --source docs\handpaint-batch2-shu-spearman-source-v1.png `
+  --stem unit-shu-spearman `
+  --work-dir tmp\handpaint-shu-spearman `
+  --output-prefix handpaint-batch2-shu-spearman `
+  --contact-title "Shu Spearman Hand-Painted Sample" `
+  --before-title "Shu Spearman Previous / Hand-Painted Sample" `
+  --before-scale-label "Previous / new at battle scale" `
+  --report-title "Shu Spearman Hand-Painted Sample" `
+  --sample-label "shu spear" `
+  --compare-stems unit-liu-bei,unit-guan-yu,unit-zhang-fei,unit-shu-infantry,unit-shu-spearman `
+  --compare-labels liu-bei,guan-yu,zhang-fei,shu-infantry,shu-spearman
+```
+
+## Extraction Rules
+
+- Remove chroma-key background.
+- Despill magenta edge color.
+- Convert body pixels to fully opaque alpha.
+- Keep detached effects only for explicitly reviewed action frames.
+- Idle/walk frames should keep only the main connected body component.
+- Mirror east-facing poses for west only when the generated west pose is not reliable.
+- Keep feet/bottom alignment stable.
+
+## Required Commands
+
+After assembling a unit:
+
+```powershell
+python scripts\audit-unit-sprite-sheets.py
+python scripts\render-unit-sprite-review-boards.py
+python scripts\check-unit-sprite-art-quality.py
+python scripts\check-unit-sprite-approval-gate.py --mode sample
+python scripts\write-unit-sprite-next-steps.py
+python scripts\check-unit-sprite-workflow-consistency.py
+python -m py_compile scripts\audit-unit-sprite-sheets.py scripts\render-unit-sprite-review-boards.py scripts\assemble-handpaint-shu-infantry-quality-sample.py
+pnpm build
+```
+
+Then verify in a PC browser preview and confirm console errors are `0`.
+
+For pending sample approval, open the local battle with a debug-only sprite preview:
+
+```text
+http://127.0.0.1:4173/heros_web/?debug&debugSpritePreview=unit-shu-infantry&v=shu-infantry-debug-preview
+```
+
+The `debugSpritePreview` panel renders the requested unit at 72px, 50px, and one action frame inside the real battle scene. It is only shown when debug tools are enabled and does not appear during normal play.
+
+## Visual Review
+
+Always inspect:
+
+- per-unit contact sheet
+- animation GIF
+- previous/new comparison
+- 50px/72px scale comparison
+- battle map composite
+- debug sprite preview battle screenshot, when reviewing a pending sample
+- current approval board, `docs/unit-sprite-current-approval-board.png`
+- relevant batch inventory board, for example `docs/unit-sprite-review-batch2-shu.png`
+
+The current approval board is the primary artifact for judging whether a pending sample is good enough. Batch inventory boards are secondary; they include old queued assets by design and must not be read as completed deliverables.
+
+The audit distinguishes technical validity from art approval:
+
+- `approved-baseline`: approved hand-painted reference units.
+- `pending-approval`: a prepared sample that must not be expanded, committed, pushed, or deployed yet.
+- `queued-rework`: units still waiting for hand-painted rework, even if their sheet dimensions are technically valid.
+
+These stages are loaded from `unit-sprite-rework-manifest.json`. Technical audit results and art approval must remain separate.
+
+Use `python scripts\check-unit-sprite-approval-gate.py --mode sample` while a sample is awaiting approval. Use `--mode release` only after approval and manifest promotion; release mode intentionally fails while `pendingApproval` is non-empty.
+
+After explicit user approval, promote the approved pending sample with the helper script instead of editing the manifest by hand:
+
+```powershell
+python scripts\promote-unit-sprite-approval.py --unit unit-shu-infantry --expected-version v3
+python scripts\audit-unit-sprite-sheets.py
+python scripts\render-unit-sprite-review-boards.py
+python scripts\check-unit-sprite-approval-gate.py --mode release
+```
+
+## Acceptance Bar
+
+A unit can move to approval only when:
+
+- it is visibly stronger than the old placeholder
+- it reads at 50px without rings/badges/glows
+- it has no ghostly transparency
+- it has no detached idle/walk fragments
+- it passes the audit script as `ok`
+- it passes `scripts/check-unit-sprite-art-quality.py`
+- it matches the approved hand-painted style direction

docs/unit-sprite-next-steps.md

@@ -0,0 +1,50 @@
+# Unit Sprite Next Steps
+
+This file is generated by `scripts/write-unit-sprite-next-steps.py`.
+
+## Current Gate
+
+- Approved baseline units: 7
+- Pending approval units: 0
+- Queued rework units: 84
+- Manifest: `docs/unit-sprite-rework-manifest.json`
+- Audit: `docs/unit-sprite-rework-audit.json`
+- Current approval board: not generated until the next pending sample.
+- Batch inventory boards include old queued assets; use them for inventory/regression checks, not approval.
+
+## Next Unit Queue
+
+1. `unit-shu-spearman` - queued-rework, base `border-hits=32`, actions `border-hits=82`, spec `unit-sprite-batch2-shu-spearman-spec.md`
+2. `unit-shu-archer` - queued-rework, base `border-hits=64`, actions `border-hits=140`, spec `unit-sprite-batch2-shu-archer-spec.md`
+3. `unit-shu-cavalry` - queued-rework, base `border-hits=64`, actions `border-hits=144`, spec `unit-sprite-batch2-shu-cavalry-spec.md`
+4. `unit-shu-strategist` - queued-rework, base `border-hits=32`, actions `border-hits=98`, spec `unit-sprite-batch2-shu-strategist-spec.md`
+5. `unit-shu-officer` - queued-rework, base `border-hits=32`, actions `border-hits=82`, spec `unit-sprite-batch2-shu-officer-spec.md`
+
+## Commands Before Approval
+
+```powershell
+python scripts\audit-unit-sprite-sheets.py
+python scripts\render-unit-sprite-review-boards.py
+python scripts\render-current-sprite-approval-board.py
+python scripts\check-unit-sprite-art-quality.py
+python scripts\check-unit-sprite-approval-gate.py --mode sample
+python scripts\write-unit-sprite-next-steps.py
+python scripts\check-unit-sprite-workflow-consistency.py
+```
+
+## Commands After Approval
+
+After user approval, promote the approved unit in `unit-sprite-rework-manifest.json`, regenerate outputs, and only then use the release gate.
+
+```powershell
+python scripts\audit-unit-sprite-sheets.py
+python scripts\render-unit-sprite-review-boards.py
+python scripts\check-unit-sprite-approval-gate.py --mode release
+pnpm build
+```
+
+## First Task After Current Approval
+
+- Start with `unit-shu-spearman`.
+- Use spec: `unit-sprite-batch2-shu-spearman-spec.md`.
+- Generate source art, assemble sheets, produce contact/GIF/before-after/scale/battle screenshots, then rerun the gates.

docs/unit-sprite-rework-audit.md

@@ -0,0 +1,145 @@
+# Unit Sprite Rework Audit
+
+This file is generated by `scripts/audit-unit-sprite-sheets.py`.
+
+Review stages are loaded from `docs/unit-sprite-rework-manifest.json`.
+
+Visual review boards are generated by `scripts/render-unit-sprite-review-boards.py`.
+
+- Review index: `unit-sprite-review-index.png`
+- Batch 1 core: `unit-sprite-review-batch1-approved-core.png`
+- Batch 1 rebel: `unit-sprite-review-batch1-approved-rebel.png`
+- Batch 2 Shu: `unit-sprite-review-batch2-shu.png`
+- Batch 3 Wei: `unit-sprite-review-batch3-wei.png`
+- Batch 4 Wu: `unit-sprite-review-batch4-wu.png`
+- Batch 5 rebel other: `unit-sprite-review-batch5-rebel-other.png`
+- Batch 6 Nanman/special: `unit-sprite-review-batch6-nanman-special.png`
+- Batch 7 unique officer: `unit-sprite-review-batch7-unique-officer.png`
+
+## Batch Counts
+
+- batch1-approved-core: 3
+- batch1-approved-rebel: 3
+- batch2-shu: 18
+- batch3-wei: 16
+- batch4-wu: 16
+- batch5-rebel-other: 6
+- batch6-nanman-special: 10
+- batch7-unique-officer: 19
+
+## Review Stage Counts
+
+- approved-baseline: 7
+- queued-rework: 84
+
+## Batch Plan
+
+- batch1-approved-core/rebel: already approved baseline, use as quality reference.
+- batch2-shu: Shu generic infantry/spearman/archer/cavalry/strategist/officer variants.
+- batch3-wei: Wei generic infantry/archer/cavalry/strategist/officer variants.
+- batch4-wu: Wu generic infantry/archer/cavalry/strategist/officer variants.
+- batch5-rebel-other: remaining rebel/bandit/yellow-turban variants outside approved batch1.
+- batch6-nanman-special: Nanman and special tribal unit variants.
+- batch7-unique-officer: unique officer sheets not covered by earlier batches.
+
+## Review Stage
+
+- `approved-baseline`: approved hand-painted reference units.
+- `pending-approval`: technically prepared, waiting for user approval before expansion/commit/deploy.
+- `queued-rework`: listed for later hand-painted rework; technical `ok` does not mean visually approved.
+
+## Sheet Status
+
+| batch | stage | stem | base | actions | base bbox | action bbox | battle base px | motion swing |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| batch7-unique-officer | queued-rework | `unit-cao-cao` | border-hits=64 | border-hits=144 | 208..271 x 282..288 | 208..280 x 275..290 | 33.2..43.3 x 45.0..46.0 | w63 h6 b6 |
+| batch7-unique-officer | queued-rework | `unit-fa-zheng` | border-hits=32 | border-hits=98 | 243..246 x 280..281 | 220..255 x 275..281 | 38.8..39.3 x 44.7..44.9 | w3 h1 b6 |
+| batch7-unique-officer | queued-rework | `unit-gong-zhi` | border-hits=32 | border-hits=82 | 200..254 x 279..279 | 200..263 x 275..279 | 31.9..40.6 x 44.6..44.6 | w54 h0 b6 |
+| batch1-approved-core | approved-baseline | `unit-guan-yu` | ok | ok | 190..270 x 276..291 | 172..296 x 171..289 | 30.4..43.1 x 44.1..46.5 | w80 h15 b4 |
+| batch7-unique-officer | queued-rework | `unit-huang-quan` | border-hits=32 | border-hits=82 | 200..254 x 279..279 | 200..263 x 275..279 | 31.9..40.6 x 44.6..44.6 | w54 h0 b6 |
+| batch7-unique-officer | queued-rework | `unit-huang-zhong` | border-hits=64 | border-hits=140 | 245..246 x 279..279 | 220..255 x 275..279 | 39.1..39.3 x 44.6..44.6 | w1 h0 b6 |
+| batch7-unique-officer | queued-rework | `unit-jiang-wei` | border-hits=32 | border-hits=82 | 194..254 x 279..279 | 194..263 x 275..279 | 31.0..40.6 x 44.6..44.6 | w60 h0 b6 |
+| batch7-unique-officer | queued-rework | `unit-li-yan` | border-hits=32 | border-hits=82 | 200..254 x 279..279 | 200..263 x 275..279 | 31.9..40.6 x 44.6..44.6 | w54 h0 b6 |
+| batch1-approved-core | approved-baseline | `unit-liu-bei` | ok | ok | 138..258 x 278..289 | 148..300 x 252..284 | 22.0..41.2 x 44.4..46.2 | w120 h11 b12 |
+| batch7-unique-officer | queued-rework | `unit-lu-bu` | border-hits=64 | border-hits=144 | 180..296 x 282..288 | 180..305 x 274..290 | 28.8..47.3 x 45.0..46.0 | w116 h6 b6 |
+| batch7-unique-officer | queued-rework | `unit-lu-meng` | border-hits=32 | border-hits=82 | 192..277 x 279..279 | 192..286 x 275..279 | 30.7..44.2 x 44.6..44.6 | w85 h0 b6 |
+| batch7-unique-officer | queued-rework | `unit-ma-chao` | border-hits=64 | border-hits=144 | 166..296 x 282..288 | 166..305 x 274..290 | 26.5..47.3 x 45.0..46.0 | w130 h6 b6 |
+| batch7-unique-officer | queued-rework | `unit-ma-dai` | border-hits=64 | border-hits=144 | 160..291 x 282..289 | 160..300 x 274..290 | 25.6..46.5 x 45.0..46.2 | w131 h7 b7 |
+| batch7-unique-officer | queued-rework | `unit-ma-liang` | border-hits=32 | border-hits=98 | 243..246 x 280..281 | 220..255 x 275..281 | 38.8..39.3 x 44.7..44.9 | w3 h1 b6 |
+| batch6-nanman-special | queued-rework | `unit-meng-huo` | border-hits=32 | border-hits=82 | 208..285 x 279..279 | 208..294 x 275..279 | 33.2..45.5 x 44.6..44.6 | w77 h0 b6 |
+| batch6-nanman-special | queued-rework | `unit-nanman-infantry` | border-hits=32 | border-hits=82 | 192..277 x 279..279 | 192..286 x 275..279 | 30.7..44.2 x 44.6..44.6 | w85 h0 b6 |
+| batch6-nanman-special | queued-rework | `unit-nanman-infantry-jungle` | border-hits=32 | border-hits=82 | 192..277 x 279..279 | 192..286 x 275..279 | 30.7..44.2 x 44.6..44.6 | w85 h0 b6 |
+| batch6-nanman-special | queued-rework | `unit-nanman-infantry-spear` | border-hits=32 | border-hits=82 | 192..277 x 279..279 | 192..286 x 275..279 | 30.7..44.2 x 44.6..44.6 | w85 h0 b6 |
+| batch6-nanman-special | queued-rework | `unit-nanman-officer` | border-hits=32 | border-hits=82 | 200..254 x 279..279 | 200..263 x 275..279 | 31.9..40.6 x 44.6..44.6 | w54 h0 b6 |
+| batch6-nanman-special | queued-rework | `unit-nanman-officer-bronze` | border-hits=64 | border-hits=144 | 208..258 x 282..288 | 208..267 x 275..290 | 33.2..41.2 x 45.0..46.0 | w50 h6 b6 |
+| batch6-nanman-special | queued-rework | `unit-nanman-officer-warlord` | border-hits=64 | border-hits=144 | 224..266 x 282..288 | 224..275 x 275..290 | 35.8..42.5 x 45.0..46.0 | w42 h6 b6 |
+| batch6-nanman-special | queued-rework | `unit-nanman-shaman` | border-hits=32 | border-hits=98 | 243..246 x 280..281 | 220..255 x 275..281 | 38.8..39.3 x 44.7..44.9 | w3 h1 b6 |
+| batch6-nanman-special | queued-rework | `unit-nanman-shaman-ember` | border-hits=32 | border-hits=98 | 243..246 x 280..281 | 220..255 x 275..281 | 38.8..39.3 x 44.7..44.9 | w3 h1 b6 |
+| batch6-nanman-special | queued-rework | `unit-nanman-shaman-storm` | border-hits=32 | border-hits=98 | 243..246 x 280..281 | 220..255 x 275..281 | 38.8..39.3 x 44.7..44.9 | w3 h1 b6 |
+| batch7-unique-officer | queued-rework | `unit-pang-tong` | border-hits=32 | border-hits=98 | 243..246 x 280..281 | 220..255 x 275..281 | 38.8..39.3 x 44.7..44.9 | w3 h1 b6 |
+| batch1-approved-rebel | approved-baseline | `unit-rebel` | ok | ok | 195..284 x 271..281 | 180..286 x 178..289 | 31.2..45.4 x 43.3..44.9 | w89 h10 b8 |
+| batch1-approved-rebel | approved-baseline | `unit-rebel-archer` | ok | ok | 185..263 x 272..278 | 116..284 x 228..288 | 29.6..42.0 x 43.5..44.4 | w78 h6 b1 |
+| batch5-rebel-other | queued-rework | `unit-rebel-archer-fire` | border-hits=64 | border-hits=140 | 245..246 x 266..266 | 220..255 x 265..272 | 39.1..39.3 x 42.5..42.5 | w1 h0 b6 |
+| batch5-rebel-other | queued-rework | `unit-rebel-archer-veteran` | border-hits=64 | border-hits=140 | 249..250 x 276..277 | 223..259 x 275..278 | 39.8..39.9 x 44.1..44.2 | w1 h1 b6 |
+| batch1-approved-rebel | approved-baseline | `unit-rebel-cavalry` | ok | ok | 139..289 x 266..281 | 167..286 x 186..282 | 22.2..46.2 x 42.5..44.9 | w150 h15 b3 |
+| batch5-rebel-other | queued-rework | `unit-rebel-cavalry-veteran` | border-hits=64 | border-hits=144 | 166..296 x 282..288 | 166..305 x 274..290 | 26.5..47.3 x 45.0..46.0 | w130 h6 b6 |
+| batch5-rebel-other | queued-rework | `unit-rebel-leader` | border-hits=32 | border-hits=72 | 200..254 x 266..266 | 200..263 x 265..266 | 31.9..40.6 x 42.5..42.5 | w54 h0 b6 |
+| batch5-rebel-other | queued-rework | `unit-rebel-leader-warlord` | border-hits=32 | border-hits=78 | 224..266 x 276..277 | 224..275 x 275..277 | 35.8..42.5 x 44.1..44.2 | w42 h1 b6 |
+| batch5-rebel-other | queued-rework | `unit-rebel-ragged` | border-hits=32 | border-hits=72 | 192..277 x 266..266 | 192..286 x 265..266 | 30.7..44.2 x 42.5..42.5 | w85 h0 b6 |
+| batch2-shu | queued-rework | `unit-shu-archer` | border-hits=64 | border-hits=140 | 245..246 x 279..279 | 220..255 x 275..279 | 39.1..39.3 x 44.6..44.6 | w1 h0 b6 |
+| batch2-shu | queued-rework | `unit-shu-archer-longbow` | border-hits=64 | border-hits=140 | 245..246 x 279..279 | 220..255 x 275..279 | 39.1..39.3 x 44.6..44.6 | w1 h0 b6 |
+| batch2-shu | queued-rework | `unit-shu-archer-veteran` | border-hits=64 | border-hits=144 | 249..250 x 282..288 | 223..259 x 275..290 | 39.8..39.9 x 45.0..46.0 | w1 h6 b6 |
+| batch2-shu | queued-rework | `unit-shu-cavalry` | border-hits=64 | border-hits=144 | 160..291 x 282..289 | 160..300 x 274..290 | 25.6..46.5 x 45.0..46.2 | w131 h7 b7 |
+| batch2-shu | queued-rework | `unit-shu-cavalry-scout` | border-hits=64 | border-hits=144 | 160..291 x 282..289 | 160..300 x 274..290 | 25.6..46.5 x 45.0..46.2 | w131 h7 b7 |
+| batch2-shu | queued-rework | `unit-shu-cavalry-white` | border-hits=64 | border-hits=144 | 160..291 x 282..289 | 160..300 x 274..290 | 25.6..46.5 x 45.0..46.2 | w131 h7 b7 |
+| batch2-shu | approved-baseline | `unit-shu-infantry` | ok | ok | 183..222 x 288..288 | 181..255 x 280..288 | 29.2..35.5 x 46.0..46.0 | w39 h0 b0 |
+| batch2-shu | queued-rework | `unit-shu-infantry-banner` | border-hits=32 | border-hits=82 | 192..277 x 279..279 | 192..286 x 275..279 | 30.7..44.2 x 44.6..44.6 | w85 h0 b6 |
+| batch2-shu | queued-rework | `unit-shu-infantry-guard` | border-hits=64 | border-hits=144 | 198..280 x 282..288 | 198..289 x 275..290 | 31.6..44.7 x 45.0..46.0 | w82 h6 b6 |
+| batch2-shu | queued-rework | `unit-shu-officer` | border-hits=32 | border-hits=82 | 200..254 x 279..279 | 200..263 x 275..279 | 31.9..40.6 x 44.6..44.6 | w54 h0 b6 |
+| batch2-shu | queued-rework | `unit-shu-officer-council` | border-hits=32 | border-hits=82 | 200..254 x 279..279 | 200..263 x 275..279 | 31.9..40.6 x 44.6..44.6 | w54 h0 b6 |
+| batch2-shu | queued-rework | `unit-shu-officer-vanguard` | border-hits=64 | border-hits=144 | 208..258 x 282..288 | 208..267 x 275..290 | 33.2..41.2 x 45.0..46.0 | w50 h6 b6 |
+| batch2-shu | queued-rework | `unit-shu-spearman` | border-hits=32 | border-hits=82 | 194..254 x 279..279 | 194..263 x 275..279 | 31.0..40.6 x 44.6..44.6 | w60 h0 b6 |
+| batch2-shu | queued-rework | `unit-shu-spearman-guard` | border-hits=64 | border-hits=144 | 202..258 x 282..288 | 202..267 x 275..290 | 32.3..41.2 x 45.0..46.0 | w56 h6 b6 |
+| batch2-shu | queued-rework | `unit-shu-spearman-veteran` | border-hits=64 | border-hits=144 | 202..258 x 282..288 | 202..267 x 275..290 | 32.3..41.2 x 45.0..46.0 | w56 h6 b6 |
+| batch2-shu | queued-rework | `unit-shu-strategist` | border-hits=32 | border-hits=98 | 243..246 x 280..281 | 220..255 x 275..281 | 38.8..39.3 x 44.7..44.9 | w3 h1 b6 |
+| batch2-shu | queued-rework | `unit-shu-strategist-field` | border-hits=32 | border-hits=98 | 243..246 x 280..281 | 220..255 x 275..281 | 38.8..39.3 x 44.7..44.9 | w3 h1 b6 |
+| batch2-shu | queued-rework | `unit-shu-strategist-white` | border-hits=32 | border-hits=98 | 243..246 x 280..281 | 220..255 x 275..281 | 38.8..39.3 x 44.7..44.9 | w3 h1 b6 |
+| batch7-unique-officer | queued-rework | `unit-sima-yi` | border-hits=32 | border-hits=98 | 243..246 x 280..281 | 220..255 x 275..281 | 38.8..39.3 x 44.7..44.9 | w3 h1 b6 |
+| batch7-unique-officer | queued-rework | `unit-wang-ping` | border-hits=32 | border-hits=82 | 200..254 x 279..279 | 200..263 x 275..279 | 31.9..40.6 x 44.6..44.6 | w54 h0 b6 |
+| batch3-wei | queued-rework | `unit-wei-archer` | border-hits=64 | border-hits=140 | 245..246 x 279..279 | 220..255 x 275..279 | 39.1..39.3 x 44.6..44.6 | w1 h0 b6 |
+| batch3-wei | queued-rework | `unit-wei-archer-crossbow` | border-hits=64 | border-hits=144 | 245..246 x 279..279 | 220..255 x 275..279 | 39.1..39.3 x 44.6..44.6 | w1 h0 b6 |
+| batch3-wei | queued-rework | `unit-wei-archer-veteran` | border-hits=64 | border-hits=144 | 249..250 x 282..288 | 223..259 x 275..290 | 39.8..39.9 x 45.0..46.0 | w1 h6 b6 |
+| batch3-wei | queued-rework | `unit-wei-cavalry` | border-hits=64 | border-hits=144 | 160..291 x 282..289 | 160..300 x 274..290 | 25.6..46.5 x 45.0..46.2 | w131 h7 b7 |
+| batch3-wei | queued-rework | `unit-wei-cavalry-elite` | border-hits=64 | border-hits=144 | 166..296 x 282..288 | 166..305 x 274..290 | 26.5..47.3 x 45.0..46.0 | w130 h6 b6 |
+| batch3-wei | queued-rework | `unit-wei-cavalry-iron` | border-hits=64 | border-hits=144 | 166..296 x 282..288 | 166..305 x 274..290 | 26.5..47.3 x 45.0..46.0 | w130 h6 b6 |
+| batch3-wei | queued-rework | `unit-wei-infantry` | border-hits=32 | border-hits=82 | 192..277 x 279..279 | 192..286 x 275..279 | 30.7..44.2 x 44.6..44.6 | w85 h0 b6 |
+| batch3-wei | queued-rework | `unit-wei-infantry-shield` | border-hits=32 | border-hits=82 | 192..277 x 279..279 | 192..286 x 275..279 | 30.7..44.2 x 44.6..44.6 | w85 h0 b6 |
+| batch3-wei | queued-rework | `unit-wei-infantry-veteran` | border-hits=64 | border-hits=144 | 198..280 x 282..288 | 198..289 x 275..290 | 31.6..44.7 x 45.0..46.0 | w82 h6 b6 |
+| batch3-wei | queued-rework | `unit-wei-officer` | border-hits=32 | border-hits=82 | 200..254 x 279..279 | 200..263 x 275..279 | 31.9..40.6 x 44.6..44.6 | w54 h0 b6 |
+| batch3-wei | queued-rework | `unit-wei-officer-gate` | border-hits=32 | border-hits=82 | 200..254 x 279..279 | 200..263 x 275..279 | 31.9..40.6 x 44.6..44.6 | w54 h0 b6 |
+| batch3-wei | queued-rework | `unit-wei-officer-iron` | border-hits=64 | border-hits=144 | 208..258 x 282..288 | 208..267 x 275..290 | 33.2..41.2 x 45.0..46.0 | w50 h6 b6 |
+| batch3-wei | queued-rework | `unit-wei-strategist` | border-hits=32 | border-hits=98 | 243..246 x 280..281 | 220..255 x 275..281 | 38.8..39.3 x 44.7..44.9 | w3 h1 b6 |
+| batch3-wei | queued-rework | `unit-wei-strategist-black` | border-hits=32 | border-hits=98 | 243..246 x 280..281 | 220..255 x 275..281 | 38.8..39.3 x 44.7..44.9 | w3 h1 b6 |
+| batch3-wei | queued-rework | `unit-wei-strategist-blue` | border-hits=32 | border-hits=98 | 243..246 x 280..281 | 220..255 x 275..281 | 38.8..39.3 x 44.7..44.9 | w3 h1 b6 |
+| batch3-wei | queued-rework | `unit-wei-yan` | border-hits=32 | border-hits=82 | 194..254 x 279..279 | 194..263 x 275..279 | 31.0..40.6 x 44.6..44.6 | w60 h0 b6 |
+| batch4-wu | queued-rework | `unit-wu-archer` | border-hits=64 | border-hits=140 | 245..246 x 279..279 | 220..255 x 275..279 | 39.1..39.3 x 44.6..44.6 | w1 h0 b6 |
+| batch4-wu | queued-rework | `unit-wu-archer-naval` | border-hits=64 | border-hits=140 | 245..246 x 279..279 | 220..255 x 275..279 | 39.1..39.3 x 44.6..44.6 | w1 h0 b6 |
+| batch4-wu | queued-rework | `unit-wu-archer-river` | border-hits=64 | border-hits=140 | 245..246 x 279..279 | 220..255 x 275..279 | 39.1..39.3 x 44.6..44.6 | w1 h0 b6 |
+| batch4-wu | queued-rework | `unit-wu-cavalry` | border-hits=64 | border-hits=144 | 160..291 x 282..289 | 160..300 x 274..290 | 25.6..46.5 x 45.0..46.2 | w131 h7 b7 |
+| batch4-wu | queued-rework | `unit-wu-cavalry-elite` | border-hits=64 | border-hits=144 | 166..296 x 282..288 | 166..305 x 274..290 | 26.5..47.3 x 45.0..46.0 | w130 h6 b6 |
+| batch4-wu | queued-rework | `unit-wu-cavalry-river` | border-hits=64 | border-hits=144 | 160..291 x 282..289 | 160..300 x 274..290 | 25.6..46.5 x 45.0..46.2 | w131 h7 b7 |
+| batch4-wu | queued-rework | `unit-wu-infantry` | border-hits=32 | border-hits=82 | 192..277 x 279..279 | 192..286 x 275..279 | 30.7..44.2 x 44.6..44.6 | w85 h0 b6 |
+| batch4-wu | queued-rework | `unit-wu-infantry-marine` | border-hits=32 | border-hits=82 | 192..277 x 279..279 | 192..286 x 275..279 | 30.7..44.2 x 44.6..44.6 | w85 h0 b6 |
+| batch4-wu | queued-rework | `unit-wu-infantry-river` | border-hits=32 | border-hits=82 | 192..277 x 279..279 | 192..286 x 275..279 | 30.7..44.2 x 44.6..44.6 | w85 h0 b6 |
+| batch4-wu | queued-rework | `unit-wu-officer` | border-hits=32 | border-hits=82 | 200..254 x 279..279 | 200..263 x 275..279 | 31.9..40.6 x 44.6..44.6 | w54 h0 b6 |
+| batch4-wu | queued-rework | `unit-wu-officer-harbor` | border-hits=32 | border-hits=82 | 200..254 x 279..279 | 200..263 x 275..279 | 31.9..40.6 x 44.6..44.6 | w54 h0 b6 |
+| batch4-wu | queued-rework | `unit-wu-officer-river` | border-hits=32 | border-hits=82 | 200..254 x 279..279 | 200..263 x 275..279 | 31.9..40.6 x 44.6..44.6 | w54 h0 b6 |
+| batch4-wu | queued-rework | `unit-wu-strategist` | border-hits=32 | border-hits=98 | 243..246 x 280..281 | 220..255 x 275..281 | 38.8..39.3 x 44.7..44.9 | w3 h1 b6 |
+| batch4-wu | queued-rework | `unit-wu-strategist-fire` | border-hits=32 | border-hits=98 | 243..246 x 280..281 | 220..255 x 275..281 | 38.8..39.3 x 44.7..44.9 | w3 h1 b6 |
+| batch4-wu | queued-rework | `unit-wu-strategist-river` | border-hits=32 | border-hits=98 | 243..246 x 280..281 | 220..255 x 275..281 | 38.8..39.3 x 44.7..44.9 | w3 h1 b6 |
+| batch4-wu | queued-rework | `unit-wu-yi` | border-hits=32 | border-hits=82 | 200..254 x 279..279 | 200..263 x 275..279 | 31.9..40.6 x 44.6..44.6 | w54 h0 b6 |
+| batch7-unique-officer | queued-rework | `unit-yan-yan` | border-hits=32 | border-hits=82 | 194..254 x 279..279 | 194..263 x 275..279 | 31.0..40.6 x 44.6..44.6 | w60 h0 b6 |
+| batch7-unique-officer | queued-rework | `unit-yi-ji` | border-hits=32 | border-hits=98 | 243..246 x 280..281 | 220..255 x 275..281 | 38.8..39.3 x 44.7..44.9 | w3 h1 b6 |
+| batch1-approved-core | approved-baseline | `unit-zhang-fei` | ok | ok | 143..306 x 274..289 | 188..286 x 181..290 | 22.8..48.9 x 43.8..46.2 | w163 h15 b14 |
+| batch7-unique-officer | queued-rework | `unit-zhao-yun` | border-hits=64 | border-hits=144 | 166..296 x 282..288 | 166..305 x 274..290 | 26.5..47.3 x 45.0..46.0 | w130 h6 b6 |
+| batch7-unique-officer | queued-rework | `unit-zhuge-liang` | border-hits=32 | border-hits=98 | 243..246 x 280..281 | 220..255 x 275..281 | 38.8..39.3 x 44.7..44.9 | w3 h1 b6 |

docs/unit-sprite-rework-manifest.json

@@ -0,0 +1,36 @@
+{
+  "schema": 1,
+  "baselineCommit": "3092b295 Improve handpainted battle unit readability",
+  "approvalPolicy": {
+    "holdExpansionUntilCurrentSampleApproved": true,
+    "holdCommitPushDeployUntilBatchApproved": true,
+    "notes": [
+      "Do not treat technical sheet validity as hand-painted art approval.",
+      "Move a unit from pendingApproval to approvedBaseline only after user approval.",
+      "Keep untouched or lower-quality units queuedRework even when their PNG dimensions are technically valid."
+    ]
+  },
+  "approvedBaseline": [
+    "unit-guan-yu",
+    "unit-liu-bei",
+    "unit-rebel",
+    "unit-rebel-archer",
+    "unit-rebel-cavalry",
+    "unit-shu-infantry",
+    "unit-zhang-fei"
+  ],
+  "pendingApproval": [],
+  "currentApprovalCandidate": {},
+  "nextAfterApproval": [
+    "unit-shu-spearman",
+    "unit-shu-archer",
+    "unit-shu-cavalry",
+    "unit-shu-strategist",
+    "unit-shu-officer"
+  ],
+  "reviewStages": {
+    "approved-baseline": "Approved hand-painted reference or approved completed unit.",
+    "pending-approval": "Prepared sample waiting for user approval; do not expand, commit, push, or deploy.",
+    "queued-rework": "Still waiting for hand-painted rework; technical OK does not mean visually approved."
+  }
+}

docs/unit-sprite-rework-plan.md

@@ -0,0 +1,97 @@
+# 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.

docs/unit-sprite-shu-infantry-v8-approval-packet.md

@@ -0,0 +1,84 @@
+# Shu Infantry v8 Approval Packet
+
+This packet records the approved `unit-shu-infantry` Batch 2 Shu quality baseline.
+
+## Decision Target
+
+- Unit: `unit-shu-infantry`
+- Batch: Batch 2 Shu generic units
+- Status: approved by user
+- Review stage: `approved-baseline`
+- Review manifest: `unit-sprite-rework-manifest.json`
+- Art quality gate: `unit-sprite-art-quality-gate.md`
+- Next unit after approval: `unit-shu-spearman`
+- Commit/push/deploy: allowed after release gate verification
+
+## Visual Evidence
+
+- Approval board at review time: `unit-sprite-current-approval-board.png`
+- Source art: `handpaint-batch2-shu-infantry-quality-restart-source-v8.png`
+- Contact sheet: `handpaint-batch2-shu-infantry-quality-restart-v8-contact.png`
+- Animation GIF: `handpaint-batch2-shu-infantry-quality-restart-v8-animation.gif`
+- v7/v8 comparison: `handpaint-batch2-shu-infantry-quality-restart-v8-before-after.png`
+- 50px/72px scale comparison: `handpaint-batch2-shu-infantry-quality-restart-v8-scale-compare.png`
+- Battle-scale map composite: `handpaint-batch2-shu-infantry-quality-restart-v8-battle-composite.png`
+- Local browser title check: `handpaint-batch2-shu-infantry-quality-restart-v8-browser-check.png`
+- Local browser first battle check: `handpaint-batch2-shu-infantry-quality-restart-v8-battle-browser-check.png`
+- Local browser debug sprite preview: `handpaint-batch2-shu-infantry-quality-restart-v8-debug-preview-battle-check.png`
+- Approved/pending deliverables board: `unit-sprite-review-approved-and-pending.png`
+- Batch 2 inventory board: `unit-sprite-review-batch2-shu.png`
+- Review index: `unit-sprite-review-index.png`
+
+## Technical Evidence
+
+- Base sheet: `src/assets/images/units/unit-shu-infantry.png`
+- Action sheet: `src/assets/images/units/unit-shu-infantry-actions.png`
+- Base sheet size: `5008x1252`
+- Action sheet size: `11268x1252`
+- Base partial alpha: `0`
+- Action partial alpha: `0`
+- Base frame border hits: `0`
+- Action frame border hits: `0`
+- Base frame empty count: `0`
+- Action frame empty count: `0`
+- Base bbox range: `183..222 x 288..288`
+- Action bbox range: `181..255 x 280..288`
+- Base bottom range: `303..303`
+- Action bottom range: `303..303`
+- Audit status: `ok`
+
+## Completed Verification
+
+- `python scripts/assemble-handpaint-shu-infantry-quality-sample.py --source docs\handpaint-batch2-shu-infantry-quality-restart-source-v8.png --work-dir tmp\handpaint-shu-infantry-quality-sample-v8 --output-prefix handpaint-batch2-shu-infantry-quality-restart-v8`
+- Technical alpha/border/bbox inspection passed
+- `pnpm build`
+- Local browser app load passed at `http://127.0.0.1:4173/heros_web/?debug&debugSpritePreview=unit-shu-infantry&v=shu-infantry-v8-final`
+- Local browser first battle load passed at the same URL.
+- Local browser debug sprite preview passed at the same URL.
+- Local browser console errors: `0`
+- Note: the first battle uses approved baseline story units; `unit-shu-infantry` is verified in the real battle scene through the debug-only sprite preview panel.
+
+## Quality Note
+
+This v8 candidate replaced v7 and was approved as the current Shu infantry baseline. v7 was technically clean, but v8 raises the visible art bar with stronger hand-painted armor mass, a more readable gold-rim shield, clearer sword angles, denser helmet and shoulder detail, and more distinct pose-to-pose motion while preserving the 313px frame format and 50px battle readability.
+
+Approved because:
+
+- It reads clearly at the 50px battle size.
+- It feels close enough to the approved Liu Bei/Guan Yu/Zhang Fei/Rebel direction.
+- The helmet, large shield, sword, green Shu armor, and foot-soldier silhouette read before the background.
+- The unit does not look ghostly, transparent, low-resolution, too thin, or like a placeholder.
+- The user accepted this as the quality bar for continuing Batch 2.
+
+After approval completed:
+
+- `unit-shu-infantry` was moved from `pendingApproval` to `approvedBaseline` in `unit-sprite-rework-manifest.json`.
+- Audit, review boards, release gate, and build were rerun.
+- Next unit: `unit-shu-spearman`.
+
+Reject or request revision if:
+
+- The character still feels too generic, too stiff, or lower quality than the approved first batch.
+- The style is not close enough to the approved Liu Bei/Guan Yu/Zhang Fei/Rebel direction.
+- The 50px view is not readable enough for live battle play.
+- The armor/weapon silhouette should be more exaggerated before applying the style to the remaining Shu units.

docs/unit-sprite-workflow-consistency.md

@@ -0,0 +1,20 @@
+# Unit Sprite Workflow Consistency
+
+This file is generated by `scripts/check-unit-sprite-workflow-consistency.py`.
+
+The check validates that manifest state, approval docs, and gate command lists describe the same workflow.
+
+## Result
+
+OK
+
+## Checked
+
+- Manifest: `docs/unit-sprite-rework-manifest.json`
+- Audit: `docs/unit-sprite-rework-audit.json`
+- Next steps: `docs/unit-sprite-next-steps.md`
+- Pipeline guide: `docs/unit-sprite-handpaint-pipeline-guide.md`
+- Checklist: `docs/unit-sprite-batch-output-checklist.md`
+- Rework plan: `docs/unit-sprite-rework-plan.md`
+- Current board: skipped because there is no pending approval unit.
+- Art quality gate: `docs/unit-sprite-art-quality-gate.md`