@howaboua/pi-pet 0.1.1

package/authoring/hatch/references/final-assembly.md

@@ -0,0 +1,67 @@
+# Final assembly
+
+Read `chroma_key.hex` from the run's `pet_request.json` with an available JSON capability and substitute that literal value for `<chroma-key>` below.
+
+Register row 9 before generating row 10:
+
+```bash
+uv run --project "$HATCH_DIR" --locked python "$HATCH_DIR/scripts/assemble_extended_atlas.py" \
+  --base-atlas "$RUN_DIR/final/spritesheet.webp" --look-row-9 "$RUN_DIR/decoded/look-row-9.png" \
+  --neutral-cell "$RUN_DIR/frames/idle/00.png" --chroma-key "<chroma-key>" \
+  --registered-row-output "$RUN_DIR/qa/look-row-9-registered.png" \
+  --registration-manifest-output "$RUN_DIR/qa/look-row-9-registration.json"
+```
+
+Assemble row 10 against the approved row-9 transform:
+
+```bash
+uv run --project "$HATCH_DIR" --locked python "$HATCH_DIR/scripts/assemble_extended_atlas.py" \
+  --base-atlas "$RUN_DIR/final/spritesheet.webp" \
+  --registered-row-9 "$RUN_DIR/qa/look-row-9-registered.png" \
+  --row-9-registration "$RUN_DIR/qa/look-row-9-registration.json" \
+  --look-row-10 "$RUN_DIR/decoded/look-row-10.png" \
+  --neutral-cell "$RUN_DIR/frames/idle/00.png" --chroma-key "<chroma-key>" \
+  --output "$RUN_DIR/final/spritesheet-extended.png" \
+  --webp-output "$RUN_DIR/final/spritesheet-extended.webp" \
+  --manifest-output "$RUN_DIR/final/spritesheet-extended.json"
+```
+
+Run one—and only one—despill pass, then validate:
+
+```bash
+uv run --project "$HATCH_DIR" --locked python "$HATCH_DIR/scripts/despill_chroma_edges.py" \
+  "$RUN_DIR/final/spritesheet-extended.png" --output "$RUN_DIR/final/spritesheet-extended.png" \
+  --webp-output "$RUN_DIR/final/spritesheet-extended.webp" --chroma-key "<chroma-key>" \
+  --json-out "$RUN_DIR/qa/chroma-despill-extended.json"
+uv run --project "$HATCH_DIR" --locked python "$HATCH_DIR/scripts/validate_atlas.py" \
+  "$RUN_DIR/final/spritesheet-extended.webp" \
+  --json-out "$RUN_DIR/final/validation-extended.json" --chroma-key "<chroma-key>" --require-v2
+```
+
+Produce QA media:
+
+```bash
+uv run --project "$HATCH_DIR" --locked python "$HATCH_DIR/scripts/make_contact_sheet.py" \
+  "$RUN_DIR/final/spritesheet-extended.webp" --output "$RUN_DIR/qa/contact-sheet-extended.png"
+uv run --project "$HATCH_DIR" --locked python "$HATCH_DIR/scripts/make_direction_qa_sheet.py" \
+  "$RUN_DIR/final/spritesheet-extended.webp" --output "$RUN_DIR/qa/look-directions.png"
+uv run --project "$HATCH_DIR" --locked python "$HATCH_DIR/scripts/make_direction_blind_qa_sheet.py" \
+  "$RUN_DIR/final/spritesheet-extended.webp" --output "$RUN_DIR/qa/direction-blind-pairs.png" \
+  --answer-key "$RUN_DIR/qa/direction-blind-answer-key.json"
+uv run --project "$HATCH_DIR" --locked python "$HATCH_DIR/scripts/measure_direction_continuity.py" \
+  "$RUN_DIR/final/spritesheet-extended.webp" --json-out "$RUN_DIR/qa/look-continuity.json"
+```
+
+After three isolated verdict files exist:
+
+```bash
+uv run --project "$HATCH_DIR" --locked python "$HATCH_DIR/scripts/combine_direction_blind_verdicts.py" \
+  --verdicts "$RUN_DIR/qa/direction-blind-verdicts-1.json" \
+  --verdicts "$RUN_DIR/qa/direction-blind-verdicts-2.json" \
+  --verdicts "$RUN_DIR/qa/direction-blind-verdicts-3.json" \
+  --json-out "$RUN_DIR/qa/direction-blind-verdicts.json"
+uv run --project "$HATCH_DIR" --locked python "$HATCH_DIR/scripts/validate_direction_blind_verdicts.py" \
+  --answer-key "$RUN_DIR/qa/direction-blind-answer-key.json" \
+  --verdicts "$RUN_DIR/qa/direction-blind-verdicts.json" \
+  --json-out "$RUN_DIR/qa/direction-blind-validation.json"
+```

package/authoring/hatch/references/look-directions.md

@@ -0,0 +1,35 @@
+# Look-direction generation
+
+## Mechanics plan
+
+Write `qa/look-mechanics.md` before generation:
+
+- natural gaze mechanism for this construction;
+- stable anchor and baseline;
+- eyes/eyelids/head/body parts that lead and follow;
+- deformation allowed by material;
+- prop attachment, occlusion, and lag;
+- cardinal pose families and expected visible sides;
+- roughly even motion budget for each 22.5° step.
+
+Physical eyeballs rotate as complete globes with iris, pupil, eyelids, rim, and highlights. Printed/screen eyes may move features on a fixed surface. Flexible bodies bend; blobs stretch subtly; separate heads turn; rigid objects use an appropriate hinge, aim, lean, or attached feature. Preserve the original eye design—never add replacement or googly eyes.
+
+## Cardinal gate
+
+Generate `000 up`, `090 screen-right`, `180 down`, and `270 screen-left together. Viewer/screen coordinates are authoritative. At normal pet size, cardinals must be unmistakable from pupils, nose, face surface, head/body direction, or the pet's natural aiming feature. Regenerate an ambiguous anchor.
+
+## Coherent rows
+
+- Row 9: `000, 022.5, 045, 067.5, 090, 112.5, 135, 157.5`.
+- Row 10: `180, 202.5, 225, 247.5, 270, 292.5, 315, 337.5`.
+- Generate each row as one eight-pose family, not eight unrelated cells.
+- Keep scale, lower-body anchor, baseline, identity, and props continuous.
+- Row 10 receives completed row 9; `157.5→180` and `337.5→000` are normal adjacent transitions.
+- Every look pose differs visibly from neutral at actual display size.
+- No whole-sprite rotation, skew, affine tilt, procedural pupil overlay, independent recentering, or patched final cell unless the pet's literal construction and mechanics plan justify it.
+
+## Acceptance
+
+Hard failure: wrong/ambiguous cardinal, labeled wrong quadrant, reversal, conspicuous snap, scale/registration pop, identity change, broken attachment, clipping, seam, transparent interior damage, or replacement eyes.
+
+Review warning: subtle intermediate cue, similar neighbors, isolated blind uncertainty, or a metric outlier without a visible defect. Warnings require recorded labeled-loop judgment; they do not automatically force regeneration.

package/authoring/hatch/references/pet-contract.md

@@ -0,0 +1,40 @@
+# Pi Pet v2 contract
+
+## Package
+
+```text
+pets/<pet-id>/
+├── PET.md
+├── pet.json
+├── spritesheet.webp
+└── validation.json
+```
+
+`pet.json`:
+
+```json
+{
+  "id": "pet-id",
+  "displayName": "Pet Name",
+  "description": "One short sentence.",
+  "spriteVersionNumber": 2,
+  "spritesheetPath": "spritesheet.webp"
+}
+```
+
+Pi Pet deliberately consumes the Codex-compatible v2 base format. An optional `pet.pi.json` extension layer may add later Pi-only actions; it is not part of hatching the standard atlas.
+
+## Atlas
+
+- PNG or WebP, exactly `1536×2288`.
+- 8 columns × 11 rows; each cell `192×208`.
+- Rows 0–8 are standard animations. Rows 9–10 are sixteen clockwise look directions.
+- Used cells contain visible pixels. Unused standard-row cells are fully transparent.
+- Fully transparent pixels have zero RGB residue. No background, guide marks, seams, clipping, or colored alpha fringe.
+- The intermediate 8×9 `1536×1872` atlas is review-only and never packaged.
+
+Coordinates are deterministic: `x = column × 192`, `y = row × 208`.
+
+## Data boundary
+
+Packages are inert data. Asset paths stay relative, regular, bounded PNG/WebP files inside the package. Never add scripts, HTML, event handlers, remote URLs, absolute paths, traversal, or escaping symlinks.

package/authoring/hatch/references/qa-rubric.md

@@ -0,0 +1,34 @@
+# Acceptance rubric
+
+Do not package until every required item passes.
+
+## Geometry and data
+
+- Final atlas exactly `1536×2288`, 8×11 grid, `192×208` cells.
+- `spriteVersionNumber: 2`; used cells visible; unused standard cells transparent.
+- Fully transparent pixels have zero RGB residue.
+- Final despill report and v2 validation have `ok: true`; frame review has no errors.
+- Durable package under `$PET_DATA/pets/<pet-id>` contains inert bounded files only and passes `npm run pet:validate -- $PET_DATA/pets/<pet-id>` from the installed Pi Pet package root.
+
+## Identity and motion
+
+- Same silhouette, proportions, face, expression language, material, palette, markings, lighting, and props across all rows.
+- Every standard row has exact frame count and recognizable semantics.
+- Idle is calm but not static; gait alternates; loops do not pop or reverse.
+- Waiting, working, review, and failure remain visually distinct.
+- No unintended character, object, logo, text, scene, shadow, detached effect, guide, or background.
+
+## Directions
+
+- Four approved cardinals and all sixteen directions in fixed clockwise order.
+- Coherent adjacent movement, stable baseline/scale/anchor, no whole-sprite rotation or replacement eyes.
+- Focused direction sheet, blind consensus, labeled semantics, and continuity evidence exist.
+- Cardinal blind gates pass. No labeled wrong quadrant, reversal, clipping, identity drift, or unexplained visible continuity defect remains.
+- Any warning has explicit evidence and reviewer/user disposition; no `fail` remains.
+
+## Review and evidence
+
+- Three isolated blind reviews plus independent final visual QA, or an explicitly recorded user-review fallback with reduced assurance.
+- Repairs were independently re-reviewed.
+- Retain request, final atlas, validation, despill, contact sheets, previews, direction sheets, blind verdicts/validation, semantics, continuity, final review, and run summary.
+- `PET.md` records identity, action semantics, generation provenance, review method, and licensing uncertainty.

package/authoring/hatch/references/reviewer-protocol.md

@@ -0,0 +1,72 @@
+# Reviewer protocol
+
+## Isolation
+
+- Use three fresh vision-capable reviewers for blind direction classification.
+- Give each only `qa/direction-blind-pairs.png`; never provide labels, prompts, atlas order, answer key, prior verdicts, or another review.
+- Use a separate final visual reviewer after deterministic processing and blind consensus.
+- Reviewers inspect and report; the parent owns repairs, files, packaging, and cleanup.
+
+## Blind direction review
+
+Prompt each reviewer:
+
+```text
+Inspect only the supplied unlabeled A/B direction sheet.
+
+Each row names one axis. For a horizontal row, classify A and B as screen-left, screen-right, or ambiguous. For a vertical row, classify A and B as up, down, or ambiguous. Judge at displayed pet size from pupils, nose, face/head turn, body aim, or the pet's natural aiming feature. Never infer from A/B order and do not force opposite answers.
+
+Return exactly one JSON object:
+{"pairs":[{"pair":"horizontal-1|vertical-1","A":"screen-left|screen-right|up|down|ambiguous","B":"screen-left|screen-right|up|down|ambiguous","reason":"short landmark evidence"}]}
+Include every pair shown.
+```
+
+Write responses separately as `direction-blind-verdicts-{1,2,3}.json`, combine by strict majority, then validate against the hidden key. Cardinal ambiguity or mismatch blocks packaging. Intermediate disagreement becomes labeled-review evidence.
+
+## Final visual review
+
+Give the final reviewer:
+
+- standard and extended contact sheets;
+- all standard-row GIF previews;
+- focused direction sheet;
+- direction semantics, blind validation, and continuity JSON;
+- frame review and v2 atlas validation.
+
+Require exactly one JSON object and save it as `qa/final-visual-review.json`:
+
+```json
+{
+  "visual_qa": "pass",
+  "qa_note": "One-sentence evidence summary.",
+  "reviewed_by": "agent:<identity>",
+  "directions": [
+    {
+      "direction": "000",
+      "expected": "up",
+      "verdict": "pass",
+      "horizontal": "neutral",
+      "vertical": "up",
+      "observed": "Visible landmark observation.",
+      "reason": "Why the evidence passes, warns, or fails."
+    }
+  ],
+  "warnings": [],
+  "repair_rows": [],
+  "repair_notes": []
+}
+```
+
+Require all sixteen directions in `directions`. Copy that array with `overall`, `reviewed_by`, and warnings to `qa/direction-semantics.json`; do not reduce it to prose.
+
+The reviewer checks one identity/style across all rows, correct state semantics, complete motion, transparency, no clipping/overlap/guides/detached effects, stable scale/baseline, and a coherent clockwise look loop. Deterministic despill and atlas validation are authoritative for chroma; visual review must not invent another cleanup pass.
+
+## Failure resolution
+
+- **Major:** wrong/ambiguous cardinal, labeled wrong quadrant/reversal, visible snap or scale pop, identity change, broken attachment, clipping, seam/hole, or deterministic failure. Repair required.
+- **Minor:** subtle intermediate cue, reviewer disagreement, or metric warning without a visible defect. Parent or user may accept only with written labeled-loop evidence in `qa/blind-review-resolution.json`.
+- Never override a major failure or let the repairing agent self-approve its repair.
+
+## Run summary
+
+After acceptance, write `qa/run-summary.json` with `ok: true`, `spriteVersionNumber: 2`, review method, package path, and paths to the final atlas, validation, despill, both contact sheets, previews, direction sheet, semantics, blind validation, continuity, and final visual review. A missing artifact is a failed summary, not `null` evidence.

package/authoring/hatch/references/standard-assembly.md

@@ -0,0 +1,21 @@
+# Standard assembly
+
+After all nine standard strips pass incremental checks:
+
+```bash
+uv run --project "$HATCH_DIR" --locked python "$HATCH_DIR/scripts/extract_strip_frames.py" \
+  --decoded-dir "$RUN_DIR/decoded" --output-dir "$RUN_DIR/frames" --states all --method auto
+uv run --project "$HATCH_DIR" --locked python "$HATCH_DIR/scripts/inspect_frames.py" \
+  --frames-root "$RUN_DIR/frames" --json-out "$RUN_DIR/qa/review.json" --require-components
+uv run --project "$HATCH_DIR" --locked python "$HATCH_DIR/scripts/compose_atlas.py" \
+  --frames-root "$RUN_DIR/frames" --output "$RUN_DIR/final/spritesheet.png" \
+  --webp-output "$RUN_DIR/final/spritesheet.webp"
+uv run --project "$HATCH_DIR" --locked python "$HATCH_DIR/scripts/make_contact_sheet.py" \
+  "$RUN_DIR/final/spritesheet.webp" --output "$RUN_DIR/qa/contact-sheet.png"
+uv run --project "$HATCH_DIR" --locked python "$HATCH_DIR/scripts/render_animation_previews.py" \
+  --frames-root "$RUN_DIR/frames" --output-dir "$RUN_DIR/qa/previews"
+```
+
+Inspect `qa/contact-sheet.png` and every GIF at actual pet scale. Reject identity/style drift, blank or clipped poses, copied guides, wrong state semantics, reversed or static gait, inert idle, baseline jumps, and size popping.
+
+If `auto` extraction alone causes popping while the source strip has stable scale and placement, rerun extraction with `--method stable-slots`, then inspection with `--allow-stable-slots`, composition, contact sheet, and previews. Record the decision. Never use stable slots to hide a broken source strip.

package/authoring/hatch/references/visual-generation.md

@@ -0,0 +1,59 @@
+# Visual generation handoff
+
+## Capability selection
+
+A suitable capability can:
+
+- generate or edit PNG/WebP from a supplied prompt;
+- accept all reference images required by a job;
+- preserve a canonical character across iterations;
+- save the selected result to a known local path.
+
+Do not require a named vendor, model, API, skill, or tool. Record the capability/service actually used in run evidence and `PET.md`.
+
+## Native generation
+
+For each ready entry in `visual-jobs.json`:
+
+1. Open its `prompt_file`.
+2. Attach every `input_images` file with its recorded role.
+3. Generate only that job.
+4. Check frame count, identity, flat chroma background, spacing, clipping, and forbidden detached effects.
+5. Save the selected original, copy it to `output_path`, and record `source_path`, `qa_note`, and completion time atomically.
+
+Use an available JSON capability to read the selected job's `output_path`, then an available file capability to create its parent and copy the selected original there. If those capabilities are unavailable, perform the same bounded JSON read and file copy with Python through the guide's locked uv environment. For the `base` job, also copy that output to `references/canonical-base.png`. Use the manifest-declared destinations; never invent parallel filenames.
+
+After that job's required deterministic and visual checks pass, write `status: "complete"`, `source_path`, `qa_note`, and UTC `completed_at` through a temporary file plus atomic rename. Do not mark a copied but unreviewed strip complete.
+
+One isolated worker per job prevents visual payloads and failed variants from flooding the parent context. Workers return only the selected path and a short evidence note.
+
+## No native generator
+
+Do not declare the workflow blocked before preparing the run. Create `visual-jobs.json`, prompts, layout guides, and reference bundles first, then offer:
+
+1. **User-operated service:** ChatGPT image generation, Gemini, Grok Imagine, or any other service that supports prompts and reference uploads.
+2. **Authorized browser assistance:** when browser control exists, offer to upload references, submit the prepared prompt, and download the selected result through the user's already logged-in session.
+3. **Manual artwork:** accept files created by an artist or another application if they satisfy the same job contract.
+
+For each external job, give the user:
+
+- service-neutral prompt file;
+- exact reference files and their roles;
+- expected number/order of poses;
+- required flat chroma color;
+- destination filename;
+- a warning not to generate the full atlas or include labels, grids, shadows, scenery, text, or guide marks.
+
+After the file is returned, inspect and process it exactly like native output. External origin never weakens QA.
+
+## Browser boundary
+
+Browser assistance requires the user's authorization for that service and upload. Use their existing session; never request or expose passwords, payment details, recovery codes, or session tokens. Do not purchase credits, accept new legal terms, publish images, or upload sensitive references without explicit approval. If download automation fails, ask the user to save the image and provide its path.
+
+## Grounding
+
+- Only the base may be prompt-only.
+- Standard rows use the canonical base and matching layout guide.
+- Cardinals use the canonical base, approved standard contact sheet, and cardinal guide.
+- Look row 9 uses approved cardinals; row 10 also uses completed row 9.
+- Do not paste individual generations into a coherent look row or fake missing motion with deterministic transforms.

package/authoring/hatch/scripts/approve_cardinals.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""Complete the cardinal approval gate only when its required evidence exists."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+from PIL import Image
+
+MAX_MANIFEST_BYTES = 1024 * 1024
+MAX_EVIDENCE_BYTES = 1024 * 1024
+EXPECTED_STRIP_SIZE = (4 * 192, 208)
+
+
+def load_object(path: Path, limit: int) -> dict[str, object]:
+    if not path.is_file() or path.stat().st_size > limit:
+        raise SystemExit(f"missing or oversized evidence: {path}")
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as error:
+        raise SystemExit(f"invalid JSON evidence: {path}: {error}") from error
+    if not isinstance(value, dict):
+        raise SystemExit(f"JSON evidence must be an object: {path}")
+    return value
+
+
+def job(manifest: dict[str, object], job_id: str) -> dict[str, object]:
+    jobs = manifest.get("jobs")
+    if not isinstance(jobs, list):
+        raise SystemExit("visual-jobs.json jobs must be a list")
+    for value in jobs:
+        if isinstance(value, dict) and value.get("id") == job_id:
+            return value
+    raise SystemExit(f"visual-jobs.json is missing job: {job_id}")
+
+
+def run_file(run_dir: Path, relative: str) -> Path:
+    if not relative or Path(relative).is_absolute() or ".." in Path(relative).parts:
+        raise SystemExit(f"approval artifact path is unsafe: {relative!r}")
+    path = (run_dir / relative).resolve()
+    try:
+        path.relative_to(run_dir)
+    except ValueError as error:
+        raise SystemExit(f"approval artifact escapes run directory: {relative}") from error
+    return path
+
+
+def atomic_write(path: Path, value: dict[str, object]) -> None:
+    temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    try:
+        temporary.write_text(json.dumps(value, indent=2) + "\n", encoding="utf-8")
+        temporary.replace(path)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--run-dir", required=True)
+    parser.add_argument("--reviewed-by", required=True)
+    parser.add_argument("--qa-note", required=True)
+    args = parser.parse_args()
+
+    reviewed_by = args.reviewed_by.strip()
+    qa_note = args.qa_note.strip()
+    if not reviewed_by or len(reviewed_by) > 80:
+        raise SystemExit("--reviewed-by must contain 1-80 characters")
+    if not qa_note or len(qa_note) > 500:
+        raise SystemExit("--qa-note must contain 1-500 characters")
+
+    run_dir = Path(args.run_dir).expanduser().resolve()
+    manifest_path = run_dir / "visual-jobs.json"
+    manifest = load_object(manifest_path, MAX_MANIFEST_BYTES)
+    source_job = job(manifest, "look-cardinals")
+    gate = job(manifest, "look-cardinals-approved")
+    if source_job.get("status") != "complete":
+        raise SystemExit("look-cardinals generation must be complete before approval")
+
+    required = gate.get("required_artifacts")
+    if not isinstance(required, list) or not all(isinstance(value, str) for value in required):
+        raise SystemExit("cardinal approval gate has invalid required_artifacts")
+    artifacts = {relative: run_file(run_dir, relative) for relative in required}
+    for relative, path in artifacts.items():
+        if not path.is_file() or path.stat().st_size <= 0 or path.stat().st_size > MAX_EVIDENCE_BYTES:
+            raise SystemExit(f"missing or oversized cardinal approval artifact: {relative}")
+
+    report = load_object(run_dir / "qa/cardinal-anchors.json", MAX_EVIDENCE_BYTES)
+    if report.get("ok") is not True:
+        raise SystemExit("cardinal anchor extraction did not pass")
+    with Image.open(run_dir / "decoded/look-anchors-approved.png") as image:
+        if image.size != EXPECTED_STRIP_SIZE:
+            raise SystemExit(
+                f"approved cardinal strip must be {EXPECTED_STRIP_SIZE[0]}x{EXPECTED_STRIP_SIZE[1]}"
+            )
+        image.verify()
+
+    gate["status"] = "complete"
+    gate["completed_at"] = datetime.now(timezone.utc).isoformat()
+    gate["reviewed_by"] = reviewed_by
+    gate["qa_note"] = qa_note
+    atomic_write(manifest_path, manifest)
+    print(json.dumps({"ok": True, "job_id": "look-cardinals-approved"}))
+
+
+if __name__ == "__main__":
+    main()