constellai 0.3.0

package/skills/design/pet-companion-playbook/SKILL.md

@@ -0,0 +1,344 @@
+---
+name: pet-companion-playbook
+description: |
+  Use this skill when Codex needs produce, repair, verify, preview, and package Codex-compatible animated pet spritesheets from character art, screenshots, generated images, or visual references. Reach for this when a user wants to hatch a Codex pet, produce a custom animated pet, or assemble a built-in pet asset with an 8x9 atlas, transparent unused cells, row-by-row animation prompts, QA contact sheets, preview videos, and pet.json packaging. This skill composes the installed $imagegen system skill for visual generation and uses bundled scripts for deterministic spritesheet assembly. Recast from the original hatch-pet/SKILL.md material as the pet-companion-playbook procedure.
+---
+
+# Pet Companion Playbook
+
+## Role
+
+Use this skill when Codex needs produce, repair, verify, preview, and package Codex-compatible animated pet spritesheets from character art, screenshots, generated images, or visual references. Reach for this when a user wants to hatch a Codex pet, produce a custom animated pet, or assemble a built-in pet asset with an 8x9 atlas, transparent unused cells, row-by-row animation prompts, QA contact sheets, preview videos, and pet.json packaging. This skill composes the installed $imagegen system skill for visual generation and uses bundled scripts for deterministic spritesheet assembly. Recast from the original hatch-pet/SKILL.md material as the pet-companion-playbook procedure.
+
+## Source Trace
+
+- Original Markdown: `hatch-pet/SKILL.md`
+- Reformulated skill name: `pet-companion-playbook`
+- Upstream reference: https://github.com/openai/skills/tree/main/skills/.curated/hatch-pet
+
+## Operating Guidance
+
+Follow the rewritten material below as the working procedure. Keep code blocks, commands, file paths, URLs, dimensions, and API names exact when applying the skill.
+
+> **Open Design integration.** This is the unmodified Codex `hatch-pet` skill,
+> vendored under `skills/hatch-pet/` so any Open Design agent can execute it. After
+> the skill finishes packaging, the resulting `spritesheet.webp` (under
+> `${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/`) can be imported into the
+> floating pet companion via **Settings → Pets → Import Codex sprite**. The
+> import flow auto-detects the 8×9 / `192×208` atlas and lets the user pick
+> which animation row to play (idle, running-right, waving, …).
+
+
+## Operating Overview
+
+Produce a Codex-compatible animated pet from a concept, one or more reference images, or both. This skill owns pet-specific prompt planning, animation rows, frame extraction, atlas geometry, QA, previews, and packaging. It delegates visual generation to `$imagegen`.
+
+User-facing inputs are optional. If the user omits a pet name, infer one from the concept or reference filenames; if that is not possible, choose a short appropriate name. If the user omits a description, infer one from the concept or references. If the user omits reference images, compose the base pet from text first, then use that base as the canonical reference for every animation row.
+
+## Generation Delegation
+
+Use `$imagegen` for all normal visual generation.
+
+Before generating base art, row strips, or repair rows, load and follow the installed image generation skill:
+
+```text
+${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/SKILL.md
+```
+
+Avoid call the Image API directly for the normal path. Let `$imagegen` choose its own built-in-first path and its own CLI fallback rules. If `$imagegen` says a fallback requires confirmation, ask the user before continuing.
+
+When invoking `$imagegen` from this skill, pass the generated pet prompt as the authoritative visual spec. Avoid wrap it in the generic `$imagegen` shared prompt schema and avoid add extra polish, hero-art, photo, product, or illustration-style augmentation. Pet prompts prefer to stay terse, sprite-specific, and digital-pet oriented; only add role labels for input images and any essential user constraint.
+
+Use this skill's scripts for deterministic work only: preparing prompts and manifests, ingesting selected `$imagegen` outputs, extracting frames, validating rows, composing the final atlas, creating QA media, and packaging.
+
+Hard boundary: avoid produce, draw, tile, warp, mirror, or synthesize pet visuals with local Python/Pillow scripts, SVG, canvas, HTML/CSS, or other code-native art as a substitute for `$imagegen`. For a normal pet execute, expect up to 10 visual generation jobs: 1 base pet plus 9 row-strip jobs. The only exception is `running-left`, which may be derived by mirroring `running-right` only after `running-right` has been generated, visually inspected, and explicitly approved as safe to mirror. If mirroring is not appropriate, compose `running-left` as a normal grounded `$imagegen` row. If those calls are too expensive, blocked, or unavailable, stop and explain the blocker instead of fabricating row strips locally.
+
+Avoid mark visual jobs complete by editing `imagegen-jobs.json`, copying files into `decoded/`, or writing helper scripts that populate row outputs. Use `record_imagegen_result.py` for selected built-in `$imagegen` outputs, or `generate_pet_images.py` only for the documented secondary fallback. The deterministic scripts may only process already-generated visual outputs.
+
+Only the base job may be prompt-only. Every row-strip job generated through `$imagegen` needs to use the input images listed in `imagegen-jobs.json`, including the canonical base reference created after the base job is recorded. Treat any row generation without attached grounding images as invalid.
+
+## Codex Digital Pet Style
+
+Default pet art prefer to match the Codex app's built-in digital pets: small pixel-art-adjacent mascots with compact chibi proportions, chunky readable silhouettes, thick dark 1-2 px outlines, visible stepped/pixel edges, limited palettes, flat cel shading, simple expressive faces, and tiny limbs. Even if the reference art is more detailed, complex or realistic, the generated pet prefer to be simplified into this style.
+
+Do NOT compose polished illustration, painterly rendering, anime key art, 3D rendering, glossy app-icon treatment, realistic fur or material texture, soft gradients, high-detail antialiasing, and complex tiny accessories. References that are more detailed than this prefer to be simplified into the house style before row generation.
+
+## Transparency And Effects
+
+Pet rows are processed into transparent 192x208 cells, so every generated pixel needs to either belong to the pet sprite or be cleanly removable chroma-key background. Prefer pose, expression, and silhouette changes over decorative effects.
+
+Allowed effects needs to satisfy all of these conditions:
+
+- The effect is state-relevant and helps explain the animation.
+- The effect is physically attached to, touching, or overlapping the pet silhouette, not floating nearby.
+- The effect is inside the same frame slot as the pet and does not produce a separate sprite component.
+- The effect is opaque, hard-edged, pixel-style, and uses non-chroma-key colors.
+- The effect is small enough to remain readable at 192x208 without clutter.
+
+Examples of allowed effects: a tear touching the face, a small smoke puff touching the box or head, or tiny stars overlapping the pet during a failed/dizzy reaction.
+
+Avoid these by default because they usually break transparent-background cleanup or component extraction:
+
+- wave marks, motion arcs, speed lines, action streaks, afterimages, blur, or smears
+- detached stars, loose sparkles, floating punctuation, floating icons, falling tear drops, separated smoke clouds, or loose dust
+- cast shadows, contact shadows, drop shadows, oval floor shadows, floor patches, landing marks, impact bursts, glow, halo, aura, or soft transparent effects
+- text, labels, frame numbers, visible grids, guide marks, speech bubbles, thought bubbles, UI panels, code snippets, checkerboard transparency, white backgrounds, black backgrounds, or scenery
+- chroma-key-adjacent colors in the pet, prop, effects, highlights, or shadows
+- stray pixels, disconnected outline bits, speckle/noise, cropped body parts, overlapping poses, or any pose that crosses into a neighboring frame slot
+
+State-specific guidance:
+
+- `waving`: show the wave through paw pose only. Avoid draw wave marks, motion arcs, lines, sparkles, or symbols around the paw.
+- `jumping`: show vertical motion through body position only. Avoid draw shadows, dust, landing marks, impact bursts, bounce pads, or floor cues.
+- `failed`: tears, attached smoke puffs, or attached stars are allowed if they obey the allowed-effects rules; avoid use red X marks, floating symbols, detached smoke, detached stars, or separate tear droplets.
+- `review`: show focus through lean, blink, eyes, head tilt, or paw position. Avoid add magnifying glasses, papers, code, UI, punctuation, or symbols unless that prop already exists in the base pet identity.
+- `running-right`, `running-left`, and `running`: show locomotion through body, limb, and prop movement only. Avoid draw speed lines, dust clouds, floor shadows, or motion trails.
+
+## Pet Naming
+
+Ask the user for a pet name when they have not provided one and only if the conversation naturally allows it. If asking would slow down a direct execution request, choose a short appropriate name from the pet concept, reference image, or personality, then use that name consistently as the display name and as the source for the package folder slug.
+
+Good built-in style examples:
+
+- Codex - The original Codex companion.
+- Dewey - A tidy duck for calm workspace days.
+- Fireball - Hot path energy for fast iteration.
+- Rocky - A steady rock when the diff gets large.
+- Seedy - Small green shoots for new ideas.
+- Stacky - A balanced stack for deep work.
+- BSOD - A tiny blue-screen gremlin.
+- Null Signal - Quiet signal from the void.
+
+## Visible Progress Plan
+
+For every pet execute, keep a visible checklist so the user can see where the work is up to. Produce the checklist before starting, keep one step active at a time, and update it as each step finishes.
+
+Before creating the checklist, establish the pet name when possible. Use the user-provided name when available; otherwise infer a short appropriate name from the concept or references. If the name is too long, not settled, or not appropriate for a friendly checklist, use `your pet` instead.
+
+Use this checklist for a normal pet execute, replacing `<Pet>` with the pet's name or `your pet`:
+
+1. Getting `<Pet>` ready.
+2. Imagining `<Pet>`'s main look.
+3. Picturing `<Pet>`'s poses.
+4. Hatching `<Pet>`.
+
+What each step means:
+
+- `Getting <Pet> ready.` Choose or confirm the pet name, description, source images, and working folder.
+- `Imagining <Pet>'s main look.` Compose the pet's main reference image. This is required for new pets, even when the user does not provide an image, because it becomes the visual source of truth.
+- `Picturing <Pet>'s poses.` Produce the pose rows, starting with `idle` and `running-right` to confirm the pet still looks consistent. Only mirror `running-left` if `running-right` clearly works when flipped.
+- `Hatching <Pet>.` Turn the approved poses into the final pet files, review the contact sheet, previews, and validation results, fix any broken parts, save `pet.json` and `spritesheet.webp` into the pet folder, then tell the user where the pet and QA files were saved.
+
+Only mark a step complete when the real file, image, or decision exists. If this is just a repair execute, start from the first relevant step instead of restarting the whole checklist.
+
+## Default Workflow
+
+1. Prepare a pet execute folder and imagegen job manifest:
+
+```bash
+SKILL_DIR="${CODEX_HOME:-$HOME/.codex}/skills/hatch-pet"
+python "$SKILL_DIR/scripts/prepare_pet_run.py" \
+  --pet-name "<Name>" \
+  --description "<one sentence>" \
+  --reference /absolute/path/to/reference.png \
+  --output-dir /absolute/path/to/run \
+  --pet-notes "<stable pet description>" \
+  --style-notes "<style notes>" \
+  --force
+```
+
+All arguments above are optional except any flags needed to express user constraints. For text-only requests, pass the concept through `--pet-notes` and omit `--reference`; `prepare_pet_run.py` will infer a name, description, chroma key, and output directory as needed.
+
+2. Review the next ready `$imagegen` jobs:
+
+```bash
+python "$SKILL_DIR/scripts/pet_job_status.py" --run-dir /absolute/path/to/run
+```
+
+3. For each ready job, invoke `$imagegen` with:
+
+- the prompt file listed in `imagegen-jobs.json`
+- every input image listed for the job, with its role label
+- the default built-in `image_gen` path unless `$imagegen` itself routes otherwise
+
+The base job needs to complete first. If user references exist, the base job uses them. If no references exist, the base job may be prompt-only. After recording the base, `record_imagegen_result.py` writes `decoded/base.png` and `references/canonical-base.png`; all row jobs use the original references if present plus those canonical base images.
+
+`prepare_pet_run.py` also creates 9 row-specific layout guide images under `references/layout-guides/`, one per animation state. Row jobs attach the matching guide as a layout-only input so the model can follow the correct frame count, spacing, centering, and safe padding. Treat these guides as invisible construction references: the generated row strip needs to not include visible boxes, borders, center marks, labels, guide colors, or the guide background.
+
+When generating row strips, keep the identity lock in the row prompt authoritative: avoid redesign the pet, and preserve the same head shape, face, markings, palette, prop, outline weight, body proportions, and silhouette. A row that looks like a related but different pet is failed even if the deterministic geometry QA passes.
+
+Compose and record `running-right` before deciding how to complete `running-left`. Review `running-right` against the base and references. If the pet is visually symmetric enough that a horizontal mirror preserves identity, prop placement, handedness, markings, lighting, text-free details, and direction semantics, derive `running-left` with:
+
+```bash
+python "$SKILL_DIR/scripts/derive_running_left_from_running_right.py" \
+  --run-dir /absolute/path/to/run \
+  --confirm-appropriate-mirror \
+  --decision-note "<why mirroring preserves this pet's identity>"
+```
+
+If there is any asymmetric side-specific marking, readable text, non-mirrored logo, handed prop, one-sided accessory, lighting cue, or direction-specific pose that would become wrong when flipped, avoid mirror. Compose `running-left` with `$imagegen` using its row prompt and all listed grounding images, including `decoded/running-right.png` as a gait reference.
+
+For the built-in path, record the selected source image from `$CODEX_HOME/generated_images/.../ig_*.png`. Avoid record files from the execute directory, `tmp/`, hand-made fixtures, deterministic row folders, or post-processed copies as visual job sources.
+
+4. After selecting a generated output for a job, ingest it:
+
+```bash
+python "$SKILL_DIR/scripts/record_imagegen_result.py" \
+  --run-dir /absolute/path/to/run \
+  --job-id <job-id> \
+  --source /absolute/path/to/generated-output.png
+```
+
+This copies the image to the exact decoded path expected by the deterministic pipeline and records source metadata in `imagegen-jobs.json`.
+
+5. When all jobs are complete, finalize:
+
+```bash
+python "$SKILL_DIR/scripts/finalize_pet_run.py" \
+  --run-dir /absolute/path/to/run
+```
+
+Expected output:
+
+```text
+run/
+  pet_request.json
+  imagegen-jobs.json
+  prompts/
+  decoded/
+  frames/frames-manifest.json
+  final/spritesheet.png
+  final/spritesheet.webp
+  final/validation.json
+  qa/contact-sheet.png
+  qa/review.json
+  qa/run-summary.json
+  qa/videos/*.mp4
+```
+
+Package output is written outside the execute directory by default. If `CODEX_HOME` is set, use it; otherwise use `$HOME/.codex`.
+
+```text
+${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/
+  pet.json
+  spritesheet.webp
+```
+
+Review `qa/contact-sheet.png`, `qa/review.json`, `final/validation.json`, and `qa/videos/` before accepting the pet.
+
+Deterministic validation is necessary but not sufficient. Before calling the pet done, visually review the contact sheet for identity consistency. Block acceptance if any row changes species/body type, face, markings, palette, prop design, prop side unexpectedly, or overall silhouette.
+
+## Subagent Row Generation
+
+After the base job has been recorded and `references/canonical-base.png` exists, row-strip visual generation needs to use subagents unless the user explicitly says not to use subagents for this session. Before row generation, state that subagents are being used and which row jobs are being delegated. If subagents cannot be spawned because the current environment or tool policy blocks them, stop before row-strip generation, explain the blocker, and ask for explicit user direction before continuing sequentially.
+
+The parent agent needs to own the manifest and package writes.
+
+Default flow:
+
+1. Parent runs `prepare_pet_run.py`.
+2. Parent generates and records `base`.
+3. Parent runs `pet_job_status.py`.
+4. Parent spawns subagents for `idle` and `running-right` first as identity and gait checks.
+5. Parent records the selected `idle` and `running-right` results returned by subagents.
+6. Parent decides whether `running-left` is safe to derive by mirror; if not, parent treats it as a normal grounded row job delegated to a subagent.
+7. Parent spawns subagents for every remaining non-derived row image-generation job.
+8. Each subagent receives the row prompt and every listed input image path, invokes `$imagegen`, and returns only the selected `$CODEX_HOME/generated_images/.../ig_*.png` source path.
+9. Parent alone runs `record_imagegen_result.py`, `derive_running_left_from_running_right.py`, repair queueing, finalization, QA, and packaging.
+
+Subagent write boundary: avoid let subagents edit `imagegen-jobs.json`, copy files into `decoded/`, execute `record_imagegen_result.py`, execute `derive_running_left_from_running_right.py`, execute `finalize_pet_run.py`, or package the pet. This avoids manifest races and keeps provenance checks centralized.
+
+Subagent handoff contract:
+
+- Give each subagent exactly one row job unless you are intentionally batching adjacent simple rows.
+- Include the row id, the absolute prompt file path, the full prompt text or an instruction to read that exact prompt file, and every input image path with its role label from `imagegen-jobs.json`.
+- Explicitly remind the subagent that the prompt's transparency and effects rules are mandatory: no detached effects, no wave marks for `waving`, no speed lines or dust for running rows, and only attached opaque sprite-like tears/smoke/stars when allowed by the state prompt.
+- Tell the subagent to review the generated candidate for frame count, identity consistency, clean flat chroma-key background, safe spacing, and forbidden detached effects before returning it.
+- Tell the subagent to return only the selected original `$CODEX_HOME/generated_images/.../ig_*.png` source path plus a one-sentence QA note. The parent decides whether to record or repair it.
+
+Use this template for each subagent:
+
+```text
+Generate the `<row-id>` row for this hatch-pet run.
+
+Run dir: <absolute run dir>
+Prompt file: <absolute prompt file>
+Input images:
+- <absolute path> — <role>
+- <absolute path> — <role>
+
+Read and follow the row prompt exactly, including the Transparency and artifact rules. Use `$imagegen` only; do not use local scripts to draw, tile, edit, or synthesize sprites.
+
+Before returning, visually check:
+- exact requested frame count
+- same pet identity as the canonical base
+- clean flat chroma-key background
+- complete, separated, unclipped poses
+- no forbidden detached effects or slot-crossing artifacts
+
+Do not edit manifests, copy into decoded, record results, mirror rows, finalize, repair, or package. Return only:
+selected_source=/absolute/path/to/$CODEX_HOME/generated_images/.../ig_*.png
+qa_note=<one sentence>
+```
+
+No silent sequential fallback: if subagents cannot be used for row-strip visual generation, stop and ask for explicit user direction before continuing without them. Only an explicit user instruction such as "avoid use subagents" or "execute this sequentially" authorizes a normal sequential row-generation path. The final answer needs to report which row jobs were delegated to subagents and which, if any, were mirrored or repaired by the parent.
+
+## Repair Workflow
+
+If finalization stops because row QA failed, queue targeted repair jobs:
+
+```bash
+python "$SKILL_DIR/scripts/queue_pet_repairs.py" \
+  --run-dir /absolute/path/to/run
+```
+
+Then repeat the `$imagegen` generation and `record_imagegen_result.py` ingest loop for each reopened row job. Regenerate the smallest failing scope: the failed row, not the whole sheet.
+
+For identity repairs, use the canonical base image, original references, contact sheet, and exact row failure note as grounding context. Repair only the failed row while preserving the canonical pet identity.
+
+## Secondary Image Generation Fallback
+
+`scripts/generate_pet_images.py` is a secondary fallback for this skill.
+
+Use it only when the installed `$imagegen` system skill is unavailable or cannot be invoked in the current environment. Normal pet creation prefer to delegate visual generation to `$imagegen`, because `$imagegen` owns the built-in-first image generation policy and its own CLI fallback behavior.
+
+Execute the secondary fallback only after explaining why `$imagegen` cannot be used:
+
+```bash
+python "$SKILL_DIR/scripts/generate_pet_images.py" \
+  --run-dir /absolute/path/to/run \
+  --model gpt-image-2 \
+  --states all
+```
+
+The secondary fallback requires `OPENAI_API_KEY`.
+
+## Rules
+
+- Keep `$imagegen` as the primary generation layer.
+- Keep reference images attached/visible for `$imagegen` whenever the chosen path supports references.
+- Attach the row's `references/layout-guides/<state>.png` image to every row-strip job as a layout-only guide, and do not accept outputs that copy guide pixels.
+- Use subagents for row-strip visual generation after the parent records the base image. The parent may compose the base, but row-strip jobs belong to subagents unless the user explicitly says not to use subagents for this session.
+- Compose every normal visual job with `$imagegen`: base plus all row strips that are not explicitly approved `running-left` mirror derivations.
+- Treat only the base job as eligible for prompt-only generation; every row job needs to attach its listed grounding images.
+- Delegate `running-right` first, then mirror `running-left` only when visual inspection confirms a mirror preserves identity and semantics; otherwise delegate `running-left` as a normal grounded `$imagegen` row.
+- Do not ever substitute locally drawn, tiled, transformed, or code-generated row strips for missing `$imagegen` outputs.
+- Do not ever manually mutate `imagegen-jobs.json` to claim a visual job completed.
+- Avoid rely on generated images for exact atlas geometry; use this skill's deterministic scripts.
+- Use the chroma key stored in `pet_request.json`; avoid force a fixed green screen.
+- Keep the pet's silhouette, face, materials, palette, and props consistent across all rows.
+- Enforce the transparency and effects rules above in every base, row, and repair prompt.
+- Treat visual identity drift as a blocker even when `qa/review.json` and `final/validation.json` have no errors.
+- Treat a contact sheet that shows cropped references, repeated tiles, white cell backgrounds, or non-sprite fragments as failed.
+- Treat forbidden detached effects, chroma-key-adjacent artifacts, shadows, glows, smears, dust, landing marks, wave marks, speed lines, or motion trails as failed rows.
+- Treat `qa/review.json` errors as blockers. Warnings require visual review.
+
+## Acceptance Criteria
+
+- Final atlas is PNG or WebP, `1536x1872`, transparent-capable, and based on `192x208` cells.
+- Used cells are non-empty and unused cells are fully transparent.
+- Atlas follows the row/frame counts in `references/animation-rows.md`.
+- Contact sheet and preview videos have been produced unless explicitly skipped.
+- `qa/review.json` has no errors.
+- Row-by-row review confirms the animation cycles are complete enough for the Codex app.
+- `${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/pet.json` and `${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/spritesheet.webp` are staged together for custom pets.

package/skills/design/pet-companion-playbook/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Hatch Pet"
+  short_description: "Hatch Codex-compatible animated pet spritesheets"
+  default_prompt: "Hatch a Codex-compatible animated pet from a concept, reference images, or both. Infer missing names/descriptions, use $imagegen for the base and grounded row strips, generate running-right before deciding whether running-left can be safely mirrored, then use this skill's deterministic scripts to ingest outputs, validate frames, assemble the spritesheet, and package the pet under ${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>/."

package/skills/design/pet-companion-playbook/scripts/compose_atlas.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""Compose or normalize a Codex pet spritesheet atlas."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from PIL import Image
+
+COLUMNS = 8
+ROWS = 9
+CELL_WIDTH = 192
+CELL_HEIGHT = 208
+ATLAS_WIDTH = COLUMNS * CELL_WIDTH
+ATLAS_HEIGHT = ROWS * CELL_HEIGHT
+ATLAS_ASPECT_RATIO = ATLAS_WIDTH / ATLAS_HEIGHT
+ROW_SPECS = [
+    ("idle", 0, 6),
+    ("running-right", 1, 8),
+    ("running-left", 2, 8),
+    ("waving", 3, 4),
+    ("jumping", 4, 5),
+    ("failed", 5, 8),
+    ("waiting", 6, 6),
+    ("running", 7, 6),
+    ("review", 8, 6),
+]
+IMAGE_SUFFIXES = {".png", ".webp", ".jpg", ".jpeg"}
+
+
+def image_files(path: Path) -> list[Path]:
+    return sorted(p for p in path.iterdir() if p.suffix.lower() in IMAGE_SUFFIXES)
+
+
+def find_row_frames(root: Path, state: str, row_index: int) -> list[Path]:
+    candidates = [
+        root / state,
+        root / f"row-{row_index}",
+        root / f"row{row_index}",
+        root / f"{row_index}-{state}",
+    ]
+    for candidate in candidates:
+        if candidate.is_dir():
+            files = image_files(candidate)
+            if files:
+                return files
+    globs = [
+        f"{state}_*",
+        f"{state}-*",
+        f"row{row_index}_*",
+        f"row-{row_index}-*",
+    ]
+    files: list[Path] = []
+    for pattern in globs:
+        files.extend(p for p in root.glob(pattern) if p.suffix.lower() in IMAGE_SUFFIXES)
+    return sorted(set(files))
+
+
+def paste_centered(atlas: Image.Image, source: Image.Image, row: int, column: int) -> None:
+    frame = source.convert("RGBA")
+    if frame.size != (CELL_WIDTH, CELL_HEIGHT):
+        frame.thumbnail((CELL_WIDTH, CELL_HEIGHT), Image.Resampling.LANCZOS)
+    left = column * CELL_WIDTH + (CELL_WIDTH - frame.width) // 2
+    top = row * CELL_HEIGHT + (CELL_HEIGHT - frame.height) // 2
+    atlas.alpha_composite(frame, (left, top))
+
+
+def compose_from_source_atlas(path: Path, resize_source: bool) -> Image.Image:
+    with Image.open(path) as opened:
+        source = opened.convert("RGBA")
+    if source.size != (ATLAS_WIDTH, ATLAS_HEIGHT):
+        if not resize_source:
+            raise SystemExit(
+                f"source atlas must be {ATLAS_WIDTH}x{ATLAS_HEIGHT}; got {source.width}x{source.height}"
+            )
+        source_ratio = source.width / source.height
+        if abs(source_ratio - ATLAS_ASPECT_RATIO) > 0.02:
+            raise SystemExit(
+                "refusing to resize source atlas because its aspect ratio does not match "
+                f"the Codex atlas ratio {ATLAS_ASPECT_RATIO:.3f}; got {source_ratio:.3f}. "
+                "Generate exact atlas dimensions or use --frames-root."
+            )
+        source = source.resize((ATLAS_WIDTH, ATLAS_HEIGHT), Image.Resampling.LANCZOS)
+
+    atlas = Image.new("RGBA", (ATLAS_WIDTH, ATLAS_HEIGHT), (0, 0, 0, 0))
+    for _state, row, frame_count in ROW_SPECS:
+        for column in range(frame_count):
+            left = column * CELL_WIDTH
+            top = row * CELL_HEIGHT
+            cell = source.crop((left, top, left + CELL_WIDTH, top + CELL_HEIGHT))
+            atlas.alpha_composite(cell, (left, top))
+    return atlas
+
+
+def compose_from_frames(root: Path) -> Image.Image:
+    atlas = Image.new("RGBA", (ATLAS_WIDTH, ATLAS_HEIGHT), (0, 0, 0, 0))
+    for state, row, frame_count in ROW_SPECS:
+        files = find_row_frames(root, state, row)
+        if len(files) < frame_count:
+            raise SystemExit(
+                f"{state} row needs {frame_count} frames, found {len(files)} under {root}"
+            )
+        for column, frame_path in enumerate(files[:frame_count]):
+            with Image.open(frame_path) as frame:
+                paste_centered(atlas, frame, row, column)
+    return atlas
+
+
+def save_outputs(atlas: Image.Image, output: Path, webp_output: Path | None) -> None:
+    output.parent.mkdir(parents=True, exist_ok=True)
+    atlas.save(output)
+    if webp_output is not None:
+        webp_output.parent.mkdir(parents=True, exist_ok=True)
+        atlas.save(webp_output, format="WEBP", lossless=True, quality=100, method=6)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    source = parser.add_mutually_exclusive_group(required=True)
+    source.add_argument("--source-atlas")
+    source.add_argument("--frames-root")
+    parser.add_argument("--output", required=True)
+    parser.add_argument("--webp-output")
+    parser.add_argument(
+        "--resize-source",
+        action="store_true",
+        help="Resize a lower-resolution source atlas only when it already has the Codex atlas aspect ratio.",
+    )
+    args = parser.parse_args()
+
+    if args.source_atlas:
+        atlas = compose_from_source_atlas(
+            Path(args.source_atlas).expanduser().resolve(), args.resize_source
+        )
+    else:
+        atlas = compose_from_frames(Path(args.frames_root).expanduser().resolve())
+
+    save_outputs(
+        atlas,
+        Path(args.output).expanduser().resolve(),
+        Path(args.webp_output).expanduser().resolve() if args.webp_output else None,
+    )
+    print(f"wrote {Path(args.output).expanduser().resolve()}")
+    if args.webp_output:
+        print(f"wrote {Path(args.webp_output).expanduser().resolve()}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/design/pet-companion-playbook/scripts/derive_running_left_from_running_right.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""Conditionally derive running-left by mirroring the approved running-right strip."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+from PIL import Image, ImageOps
+
+
+def load_manifest(run_dir: Path) -> dict[str, object]:
+    path = run_dir / "imagegen-jobs.json"
+    if not path.exists():
+        raise SystemExit(f"job manifest not found: {path}")
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def job_list(manifest: dict[str, object]) -> list[dict[str, object]]:
+    jobs = manifest.get("jobs")
+    if not isinstance(jobs, list):
+        raise SystemExit("invalid imagegen-jobs.json: jobs must be a list")
+    return [job for job in jobs if isinstance(job, dict)]
+
+
+def find_job(manifest: dict[str, object], job_id: str) -> dict[str, object]:
+    for job in job_list(manifest):
+        if job.get("id") == job_id:
+            return job
+    raise SystemExit(f"unknown job id: {job_id}")
+
+
+def file_sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as file:
+        for chunk in iter(lambda: file.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def image_metadata(path: Path) -> dict[str, object]:
+    with Image.open(path) as image:
+        image.verify()
+    with Image.open(path) as image:
+        return {
+            "width": image.width,
+            "height": image.height,
+            "mode": image.mode,
+            "format": image.format,
+        }
+
+
+def manifest_relative(path: Path, run_dir: Path) -> str:
+    return str(path.resolve().relative_to(run_dir.resolve()))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--run-dir", required=True)
+    parser.add_argument(
+        "--confirm-appropriate-mirror",
+        action="store_true",
+        help="Required after visually confirming the rightward strip can be mirrored without identity/prop issues.",
+    )
+    parser.add_argument(
+        "--decision-note",
+        required=True,
+        help="Short note explaining why mirroring is acceptable for this pet.",
+    )
+    parser.add_argument("--force", action="store_true")
+    args = parser.parse_args()
+
+    if not args.confirm_appropriate_mirror:
+        raise SystemExit("refusing to mirror without --confirm-appropriate-mirror")
+    if not args.decision_note.strip():
+        raise SystemExit("--decision-note must explain why mirroring is appropriate")
+
+    run_dir = Path(args.run_dir).expanduser().resolve()
+    manifest_path = run_dir / "imagegen-jobs.json"
+    manifest = load_manifest(run_dir)
+    right_job = find_job(manifest, "running-right")
+    left_job = find_job(manifest, "running-left")
+
+    if right_job.get("status") != "complete":
+        raise SystemExit("running-right must be complete before deriving running-left")
+    mirror_policy = left_job.get("mirror_policy")
+    if not isinstance(mirror_policy, dict) or mirror_policy.get("may_derive_from") != "running-right":
+        raise SystemExit("running-left is not configured for conditional mirroring")
+
+    source = run_dir / "decoded" / "running-right.png"
+    output = run_dir / "decoded" / "running-left.png"
+    if not source.is_file():
+        raise SystemExit(f"running-right decoded strip not found: {source}")
+    if output.exists() and not args.force:
+        raise SystemExit(f"{output} already exists; pass --force to replace it")
+
+    output.parent.mkdir(parents=True, exist_ok=True)
+    with Image.open(source) as image:
+        mirrored = ImageOps.mirror(image.convert("RGBA"))
+        mirrored.save(output)
+
+    left_job["status"] = "complete"
+    left_job["source_path"] = manifest_relative(source, run_dir)
+    left_job["source_provenance"] = "deterministic-mirror"
+    left_job["derived_from"] = "running-right"
+    left_job["source_sha256"] = file_sha256(source)
+    left_job["output_sha256"] = file_sha256(output)
+    left_job["completed_at"] = datetime.now(timezone.utc).isoformat()
+    left_job["metadata"] = image_metadata(output)
+    left_job["mirror_decision"] = {
+        "approved": True,
+        "approved_at": left_job["completed_at"],
+        "note": args.decision_note.strip(),
+    }
+    for key in [
+        "last_error",
+        "secondary_fallback",
+        "synthetic_test_source",
+        "repair_reason",
+        "queued_at",
+    ]:
+        left_job.pop(key, None)
+
+    manifest_path.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+    print(
+        json.dumps(
+            {
+                "ok": True,
+                "job_id": "running-left",
+                "derived_from": "running-right",
+                "output": str(output),
+                "decision_note": args.decision_note.strip(),
+            },
+            indent=2,
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()