Upgrade Pebble Poses to V2 look directions

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 3.0.0 - 2026-07-30
+
+- Upgraded the runtime package to the Codex V2 `8 × 11` atlas contract.
+- Added 16 clockwise look directions with validated up, right, down, and left
+  cardinal anchors and reviewed intermediate-direction continuity.
+- Changed the runtime manifest and release archive from the V1 PNG to a lossless
+  V2 WebP with `spriteVersionNumber: 2`.
+- Preserved the hardened standard animation rows already on `main`; the V2
+  migration adds only the approved neutral and look-direction cells.
+- Extended deterministic rebuild comparison, adversarial tests, installer,
+  documentation, previews, and release packaging for V2.
+
 ## 2.1.0 - 2026-07-24
 
 - Rebuilt all nine runtime rows from dedicated, state-specific source frames.

CONTRIBUTING.md

@@ -35,8 +35,13 @@ same change as the source or build-logic change that produced them.
 - Keep each state visually distinct at a 192×208 cell size.
 - Do not add floor scenery, detached particles, text, UI, shadows, or effects.
 - Use a shared scale and registration within an animation row.
+- Preserve the fixed clockwise V2 look order and treat all four cardinal
+  directions as hard visual gates.
 - Record the source and derivation in `docs/ASSET-PROVENANCE.md`.
 - Inspect the contact sheet and all looping row previews before requesting review.
+- For artwork replacements, run the hatch-pet V2 despill and direction QA once
+  before committing the resulting source cells; do not despill already approved
+  source rows during routine rebuilds.
 
 ## Pull requests
 

README.md

@@ -7,15 +7,16 @@ Pebble Poses is a local custom pet package for ChatGPT desktop and compatible Co
 ```text
 pebble-poses/
 ├── pet.json
-└── spritesheet.png
+└── spritesheet.webp
 ```
 
-The runtime sprite sheet is a transparent PNG with the fixed Codex V1 geometry:
+The runtime sprite sheet is a lossless transparent WebP with the Codex V2 geometry:
 
-- `1536 × 1872` pixels
-- `8 × 9` cells
+- `1536 × 2288` pixels
+- `8 × 11` cells
 - `192 × 208` pixels per cell
 - fully transparent unused cells
+- 16 clockwise look directions in rows 9–10
 - under the `20 MiB` upload limit
 
 Official references:
@@ -28,7 +29,7 @@ Official references:
 
 | Row | State | Used columns | Timing |
 |---:|---|---:|---|
-| 0 | `idle` | 0–5 | 280, 110, 110, 140, 140, 320 ms |
+| 0 | `idle` | 0–6 | 0–5 animate at 280, 110, 110, 140, 140, 320 ms; 6 is the V2 neutral look frame |
 | 1 | `running-right` | 0–7 | 120 ms each; final 220 ms |
 | 2 | `running-left` | 0–7 | 120 ms each; final 220 ms |
 | 3 | `waving` | 0–3 | 140 ms each; final 280 ms |
@@ -37,14 +38,19 @@ Official references:
 | 6 | `waiting` | 0–5 | 150 ms each; final 260 ms |
 | 7 | `running` | 0–5 | 120 ms each; final 220 ms |
 | 8 | `review` | 0–5 | 150 ms each; final 280 ms |
+| 9 | `look-directions-a` | 0–7 | 000° through 157.5° in 22.5° steps |
+| 10 | `look-directions-b` | 0–7 | 180° through 337.5° in 22.5° steps |
+
+`000°` means up. The direction rows proceed clockwise in screen coordinates;
+neutral pointer input falls back to the idle animation.
 
 The exact approved source frame for every runtime cell is recorded in
 [`docs/animation-map.json`](docs/animation-map.json).
 
 ## Requirements
 
 - Python 3.10 or later
-- Pillow 12.2.0
+- Pillow 12.3.0
 - Bash for the installer
 
 ```bash
@@ -72,10 +78,13 @@ source/poses/*.png
 docs/animation-map.json
 ```
 
-`spritesheet.png` is the packaged runtime asset. The lossless WebP is retained as an alternate QA/build artifact.
+`spritesheet.webp` is the packaged runtime asset. The PNG is retained as a
+lossless decoded QA/build artifact.
 Runtime rows are composed from the approved 192×208 PNG frames in
 `source/rows/`; `source/poses/` remains a deterministic extraction of the
-original production-art board for reference.
+original production-art board for reference. The committed source-row cells
+already contain the single approved V2 edge-despill result, so ordinary rebuilds
+must not apply chroma cleanup a second time.
 
 ## Verify
 
@@ -150,6 +159,8 @@ attestation.
 The runtime atlas uses dedicated, state-specific animation frames derived from
 the Pebble production art. The left movement row is a deterministic mirror of
 the approved right movement row, keeping frame order, scale, and registration
-exactly paired. Runtime frames contain no floor scenery or detached debris.
+exactly paired. The two coherent look rows form one approved clockwise 16-pose
+loop with unmistakable cardinal directions. Runtime frames contain no floor
+scenery or detached debris.
 See [`docs/ASSET-PROVENANCE.md`](docs/ASSET-PROVENANCE.md) for derivation
 details.

docs/ASSET-PROVENANCE.md

@@ -11,9 +11,19 @@ project; no third-party stock assets are included.
 | `source/rows/{idle,waving,jumping,failed,waiting,running,review}/*.png` | Project animation-art pass | State-specific, identity-preserving animation frames on transparency |
 | `source/rows/running-right/*.png` | Project locomotion-art pass | Approved right-facing shell-drag sequence |
 | `source/rows/running-left/*.png` | Repository derivation | Deterministic horizontal mirror of the matching right-facing frame |
+| `source/rows/look-directions-{a,b}/*.png` | Pebble V2 hatch-pet upgrade | Approved normalized cells from two coherent 8-pose look families; cardinal, blind-axis, labeled-semantic, continuity, and final visual QA passed |
 | `pebble-poses/spritesheet.*` | Repository build output | Deterministically composed from approved source-row frames |
 | `preview/*` | Repository build output | Rendered from the runtime atlas |
 
+The V2 migration reassembled the coherent look strips against the current
+`main` neutral frame, applied hatch-pet's deterministic edge-local chroma-spill
+suppression once to the complete atlas, and extracted the approved post-cleanup
+cells into `source/rows/`. Alpha was preserved during despill. Repository builds
+compose those committed cells directly and do not repeat chroma cleanup. A
+blind-review failure at `000` caused row 9 to be regenerated as a complete
+coherent family. Both final look rows were then uniformly normalized to a
+shared practical scale and baseline before the final visual pass.
+
 The repository's MIT license applies to the committed source and generated
 assets. Future contributions must document externally sourced references,
 licenses, and material transformations before merge.

docs/LOOK-DIRECTION-QA.md

@@ -0,0 +1,35 @@
+# Look-Direction QA
+
+Pebble Poses V2 includes 16 clockwise look directions across atlas rows 9 and
+10. The four cardinals are hard gates: 000 up, 090 screen-right, 180 down, and
+270 screen-left.
+
+## Accepted evidence
+
+- Three isolated reviewers classified a randomized, unlabeled A/B direction
+  sheet. Both hard cardinal pairs passed by strict majority.
+- Thirteen of fourteen intermediate axis pairs passed. The remaining 157.5
+  horizontal component was ambiguous in isolation but was accepted as a
+  warning after labeled loop review confirmed a continuous down-right pose.
+- The final continuity report contains no alpha-hole candidates. Its remaining
+  metric warnings were visually reviewed and show no clipping, identity drift,
+  semantic reversal, or conspicuous size pop.
+- A final independent reviewer passed all nine standard animation rows and the
+  complete 16-direction loop after both coherent look rows were uniformly
+  scaled by 1.30, recentered, and planted at the shared y=203 baseline.
+- Both the repository verifier and the hatch-pet V2 atlas validator pass the
+  final source-driven WebP with zero structural or chroma warnings.
+
+Machine-readable semantic verdicts are stored in
+qa/direction-semantics.json; the final visual disposition is stored in
+qa/final-visual-qa.json.
+
+## Accepted warnings
+
+- 157.5 has a subtle screen-right cue when viewed alone; the ordered
+  135 -> 157.5 -> 180 loop preserves the intended down-right progression.
+- 112.5 -> 135 is a pixel-difference outlier caused by the bowed-pose
+  transition, with no visible snap at normal pet size.
+- 337.5 -> 000 has an 11.5-pixel center shift and 1.15 area ratio as Pebble
+  returns to the full upward pose. The planted baseline, identity, and
+  clockwise direction semantics remain stable.