Skip to content

notque/vexjoy-agent / skills/game/game-dev

game-dev

Flagged

Game development: design, asset pipelines, Phaser, Unity CLI and builds, vanilla JS frontend, GM mode, match booking.

FileKindSize
SKILL.mdskill md13.2 KB
references/anchor-alignment.mdmarkdown16.0 KB
references/animate-scaffolds.mdmarkdown2.0 KB
references/arcade-physics.mdmarkdown7.4 KB
references/artifacts-and-prototyping.mdmarkdown1.5 KB
references/asset-sources.mdmarkdown7.9 KB
references/audit-and-red-team.mdmarkdown795 B
references/autonomous-improvement.mdmarkdown10.3 KB
references/backend-chain.mdmarkdown10.4 KB
references/bg-removal-local.mdmarkdown22.7 KB
references/build-scaffolds.mdmarkdown2.0 KB
references/capabilities/01-design-red-team-audit.mdmarkdown3.9 KB
references/capabilities/02-emotional-canvas-moodboard.mdmarkdown3.7 KB
references/capabilities/03-game-design-attribution-audit.mdmarkdown3.6 KB
references/capabilities/04-game-design-bartle-archetype-audit.mdmarkdown3.7 KB
references/capabilities/05-game-design-big-five-personality-audit.mdmarkdown3.6 KB
references/capabilities/06-game-design-brainstorm-methods.mdmarkdown3.9 KB
references/capabilities/07-game-design-core-loop-extractor.mdmarkdown3.7 KB
references/capabilities/08-game-design-craft-critique.mdmarkdown3.5 KB
references/capabilities/09-game-design-creative-unblocker.mdmarkdown3.5 KB
references/capabilities/10-game-design-design-pillars-extractor.mdmarkdown3.5 KB
references/capabilities/11-game-design-emotional-canvas.mdmarkdown3.6 KB
references/capabilities/12-game-design-failure-loop-audit.mdmarkdown3.8 KB
references/capabilities/13-game-design-fairness-frustration-audit.mdmarkdown3.6 KB
references/capabilities/14-game-design-fantasy-extractor.mdmarkdown3.6 KB
references/capabilities/15-game-design-feature-prioritization.mdmarkdown3.6 KB
references/capabilities/16-game-design-five-options.mdmarkdown3.5 KB
references/capabilities/17-game-design-flow-audit.mdmarkdown3.6 KB
references/capabilities/18-game-design-fogg-behavior-audit.mdmarkdown3.6 KB
references/capabilities/19-game-design-friction-journey-audit.mdmarkdown3.8 KB
references/capabilities/20-game-design-ftue-hero-journey-audit.mdmarkdown3.7 KB
references/capabilities/21-game-design-goal-density-and-immediacy-audit.mdmarkdown3.5 KB
references/capabilities/22-game-design-goal-framing.mdmarkdown3.5 KB
references/capabilities/23-game-design-granular-player-motivation-audit.mdmarkdown4.0 KB
references/capabilities/24-game-design-grow-design.mdmarkdown3.5 KB
references/capabilities/25-game-design-ideal-outcome-backcasting.mdmarkdown3.4 KB
references/capabilities/26-game-design-kpi-coverage-audit.mdmarkdown3.8 KB
references/capabilities/27-game-design-leaderboard-audit.mdmarkdown3.9 KB
references/capabilities/28-game-design-leaderboard-builder.mdmarkdown3.8 KB
references/capabilities/29-game-design-molyneux-lens.mdmarkdown3.5 KB
references/capabilities/30-game-design-multiplayer-feature-audit.mdmarkdown3.8 KB
references/capabilities/31-game-design-novelty-spectrum-audit.mdmarkdown3.6 KB
references/capabilities/32-game-design-one-page-design-doc.mdmarkdown3.8 KB
references/capabilities/33-game-design-one-thing-to-remove.mdmarkdown3.6 KB
references/capabilities/34-game-design-option-generation.mdmarkdown3.5 KB
references/capabilities/35-game-design-peak-end-audit.mdmarkdown3.6 KB
references/capabilities/36-game-design-perceived-randomness-audit.mdmarkdown3.7 KB
references/capabilities/37-game-design-pitch-deck-audit.mdmarkdown3.8 KB
references/capabilities/38-game-design-player-motivation-audit.mdmarkdown3.5 KB
references/capabilities/39-game-design-player-need-satisfaction-audit.mdmarkdown3.6 KB
references/capabilities/40-game-design-player-persona-extractor.mdmarkdown4.2 KB
references/capabilities/41-game-design-player-perspective-reframe.mdmarkdown3.7 KB
references/capabilities/42-game-design-player-segment-perception-audit.mdmarkdown3.6 KB
references/capabilities/43-game-design-player-values-mapper.mdmarkdown3.8 KB
references/capabilities/44-game-design-premium-pass-audit.mdmarkdown3.8 KB
references/capabilities/45-game-design-prosocial-session-chapters.mdmarkdown3.7 KB
references/capabilities/46-game-design-prototype-intent-audit.mdmarkdown3.7 KB
references/capabilities/47-game-design-prototyping-companion.mdmarkdown3.6 KB
references/capabilities/48-game-design-roadblock-reframing.mdmarkdown3.5 KB
references/capabilities/49-game-design-smart-goal-audit.mdmarkdown3.6 KB
references/capabilities/50-game-design-social-satisfaction-matrix.mdmarkdown3.7 KB
references/capabilities/51-game-design-systematizing-empathizing-audit.mdmarkdown3.6 KB
references/capabilities/52-game-design-thinking-fast-and-slow-audit.mdmarkdown3.6 KB
references/capabilities/53-game-design-transformative-reuse.mdmarkdown3.6 KB
references/capabilities/54-game-design-unknown-unknowns-prototyping.mdmarkdown3.6 KB
references/capabilities/55-game-design-zeigarnik-effect-audit.mdmarkdown3.6 KB
references/capabilities/56-game-dev-budget-estimator.mdmarkdown3.8 KB
references/capabilities/57-game-dev-first-steps.mdmarkdown3.6 KB
references/capabilities/58-game-dev-team-gap.mdmarkdown3.6 KB
references/capabilities/59-game-dev-time-estimator.mdmarkdown3.8 KB
references/capabilities/60-moodboard-generator.mdmarkdown4.0 KB
references/capabilities/61-software-team-conflict-patterns.mdmarkdown3.8 KB
references/capability-catalog.mdmarkdown18.4 KB
references/capability-map.mdmarkdown1.7 KB
references/capability-matrix.mdmarkdown12.5 KB
references/capacitor-ios.mdmarkdown7.3 KB
references/cognition-and-choice.mdmarkdown1.2 KB
references/cognitive-and-behavioral-lenses.mdmarkdown1.2 KB
references/concept-and-loop.mdmarkdown1.5 KB
references/core-loop-and-pillars.mdmarkdown835 B
references/core-patterns.mdmarkdown8.2 KB
references/cpu-systems-harmony.mdmarkdown3.4 KB
references/creative-and-options.mdmarkdown2.0 KB
references/creative-direction.mdmarkdown1.3 KB
references/deploy.mdmarkdown5.3 KB
references/design-artifacts.mdmarkdown1.0 KB
references/emotion-and-presentation.mdmarkdown1.1 KB
references/error-catalog.mdmarkdown22.6 KB
references/fairness-and-failure.mdmarkdown1.2 KB
references/fairness-and-learning.mdmarkdown1.3 KB
references/fal-ai-image.mdmarkdown7.1 KB
references/frame-detection.mdmarkdown20.0 KB
references/full-diagnostic.mdmarkdown4.2 KB
references/game-asset-generator.mdmarkdown9.5 KB
references/game-audio.mdmarkdown7.5 KB
references/game-feel-patterns.mdmarkdown12.2 KB
references/game-pipeline.mdmarkdown11.5 KB
references/game-qa.mdmarkdown6.7 KB
references/game-sprite-pipeline.mdmarkdown33.4 KB
references/gm-brilliant-implementation.mdmarkdown13.4 KB
references/grid-shapes.mdmarkdown8.0 KB
references/meshyai.mdmarkdown7.3 KB
references/motion-pipeline.mdmarkdown7.5 KB
references/output-formats.mdmarkdown9.4 KB
references/pacing-and-return.mdmarkdown1.6 KB
references/performance.mdmarkdown7.8 KB
references/phaser-gamedev.mdmarkdown7.5 KB
references/pipeline-spec.jsonconfig23.0 KB
references/pixel-art-sprites.mdmarkdown8.7 KB
references/planning-and-communication.mdmarkdown1.6 KB
references/planning-and-production.mdmarkdown1.8 KB
references/player-and-social.mdmarkdown2.3 KB
references/polish-scaffolds.mdmarkdown1.9 KB
references/progression-and-economy.mdmarkdown1.0 KB
references/promo-video.mdmarkdown6.6 KB
references/prompt-rules.mdmarkdown15.2 KB
references/quality-gates.mdmarkdown6.4 KB
references/road-to-aew-integration.mdmarkdown7.8 KB
references/social-and-competitive-design.mdmarkdown1.1 KB
references/social-and-competitive.mdmarkdown1.5 KB
references/spritesheets.mdmarkdown6.2 KB
references/stage-contracts.mdmarkdown11.1 KB
references/style-presets.mdmarkdown5.1 KB
references/subagent-delegation.mdmarkdown2.2 KB
references/tilemaps-and-physics.mdmarkdown13.6 KB
references/tilemaps.mdmarkdown7.0 KB
references/unity-batchmode-builds.mdmarkdown9.2 KB
references/unity-cli.mdmarkdown10.9 KB
references/unity-licensing.mdmarkdown5.0 KB
references/vfx-containment.mdmarkdown3.1 KB
references/workflow-dag.mdmarkdown4.1 KB
references/worldlabs.mdmarkdown7.9 KB
references/wrestler-archetypes.mdmarkdown7.2 KB
scripts/deterministic_idle.pyscript7.8 KB
scripts/fal_queue_image_run.pyscript9.4 KB
scripts/imgdiff.pyscript5.0 KB
scripts/meshy-generate.mjsscript11.1 KB
scripts/optimize-glb.mjsscript3.8 KB
scripts/portrait_pipeline.pyscript31.2 KB
scripts/qa_artifacts.pyscript14.4 KB
scripts/road_to_aew_integration.pyscript6.6 KB
scripts/row_job_status.pyscript8.6 KB
scripts/sprite_anchor.pyscript30.1 KB
scripts/sprite_assemble.pyscript16.0 KB
scripts/sprite_bg.pyscript28.5 KB
scripts/sprite_canvas.pyscript11.9 KB
scripts/sprite_generate.pyscript13.9 KB
scripts/sprite_pipeline.pyscript54.9 KB
scripts/sprite_process.pyscript13.5 KB
scripts/sprite_prompt.pyscript41.8 KB
scripts/sprite_slicing.pyscript38.7 KB
scripts/sprite_verify.pyscript58.5 KB
scripts/test_content_aware_extraction.pyscript13.4 KB
scripts/test_no_status_laundering.pyscript6.9 KB
scripts/test_phases_4_5_7_8.pyscript16.4 KB
scripts/test_pipeline_glue.pyscript20.9 KB
scripts/test_pipeline_patterns.pyscript10.9 KB
scripts/test_rc3_frames_distinct_threshold.pyscript14.2 KB
scripts/test_rc4_mass_centroid_default.pyscript8.3 KB
scripts/test_rc5_despill_pre_upscale.pyscript7.9 KB
scripts/test_slice_grid_cells.pyscript6.4 KB
scripts/test_slicer_strict_pitch_default.pyscript11.6 KB
scripts/test_verifier_cell_parity.pyscript9.0 KB
scripts/test_verify_gates.pyscript23.2 KB
scripts/tests/test_fal_queue_image_run.pyscript908 B
scripts/video_extract_frames.pyscript4.3 KB
scripts/video_process_frames.pyscript7.6 KB
scripts/video_select_frames.pyscript6.4 KB
scripts/with_server.pyscript5.8 KB

scripts/sprite_verify.py

View on GitHub
#!/usr/bin/env python3
"""Verifier-gate primitives for the game-sprite-pipeline skill.

Owns the six deterministic build-time gates (`verify_no_magenta`,
`verify_grid_alignment`, `verify_anchor_consistency`,
`verify_frames_have_content`, `verify_frames_distinct`,
`verify_pixel_preservation`) plus the combined `verify_asset_outputs`
runner and the `verify-asset` CLI subcommand.

Per docs/PHILOSOPHY.md: exact, repeatable checks belong in programs
and the Verifier pattern: separate planner / executor / verifier roles.
The verifier's job is to try to break the result -- "looks correct" is
not a verdict. These functions are the falsifiable checks the prior
pipeline lacked: the same broken output shipped every time because
nothing flagged it. Each verifier returns evidence-bearing structured
data the build can hard-fail on.

Public surface (re-exported through `sprite_process` for backward compat):
    verify_no_magenta, verify_grid_alignment, verify_anchor_consistency,
    verify_frames_have_content, verify_frames_distinct,
    verify_pixel_preservation, verify_asset_outputs, cmd_verify_asset,
    _slice_grid_into_cells, _dhash, _hamming.
"""

from __future__ import annotations

import argparse
import json
import logging
import os
import sys
from pathlib import Path

logger = logging.getLogger("sprite-pipeline.sprite_verify")

try:
    from PIL import Image
except ImportError as e:
    logger.error("Pillow not installed: %s", e)
    logger.error("Install with: pip install pillow")
    sys.exit(1)

try:
    import numpy as np

    HAS_NUMPY = True
except ImportError:
    HAS_NUMPY = False

from sprite_anchor import find_alpha_mass_centroid
from sprite_slicing import _parse_grid


# ---------------------------------------------------------------------------
# Verification gates (deterministic build-time checks)
# ---------------------------------------------------------------------------
def verify_no_magenta(
    img: Image.Image | Path | str,
    threshold_strict: int = 0,
    threshold_wide: int = 10,
) -> dict:
    """Pixel-comparison verification: count residual magenta in a final asset.

    Two pixel classes (mirroring the criteria in `kill_pink_fringe` and
    `neutralize_interior_magenta_spill`):

      - strict_count: R>200 AND B>200 AND G<100, alpha>16 (or full opaque
        for non-RGBA). Catches near-pure (255,0,255) bleeding through.
      - wide_count: R>130 AND B>120 AND G<80 AND R-G>50 AND B-G>40,
        alpha>16. Catches diluted pink halo / fringe survival.

    Returns dict with `passed = strict_count <= threshold_strict and
    wide_count <= threshold_wide`. The build-time gate hard-fails on
    `passed=False`. Pure numpy, ~10ms / 1024px image.

    Accepts PIL.Image, Path, or str. PNG/GIF/WebP all decode through Pillow.
    """
    if not HAS_NUMPY:
        # Pure-Python fallback would be O(W*H) loops -- too slow for build gate.
        return {
            "strict_count": -1,
            "wide_count": -1,
            "total_visible": -1,
            "pct": 0.0,
            "passed": False,
            "error": "numpy required for verify_no_magenta",
        }

    if isinstance(img, (str, Path)):
        img = Image.open(img)
    img = img.convert("RGBA")
    arr = np.array(img)
    r = arr[..., 0].astype(int)
    g = arr[..., 1].astype(int)
    b = arr[..., 2].astype(int)
    a = arr[..., 3]

    visible = a > 16
    total_visible = int(visible.sum())

    # Strict: near-pure magenta (255, 0, 255). Excludes purple (B much
    # higher than R) and saturated red. Pure magenta has B/R ~= 1.0; pure
    # purple has B/R >= 1.08. We require B/R <= 1.05 to keep the strict
    # band tight around magenta -- this preserves bright-purple costume
    # pixels (e.g. wizard robes (220,87,238) at B/R=1.08, manager-loop
    # cell (203,93,232) at B/R=1.14).
    strict = (r > 200) & (b > 200) & (g < 100) & (b * 100 <= r * 105) & visible
    # Wide-pink/magenta criterion: matches neutralize_interior_magenta_spill's
    # Tier B exactly. The verifier's job is to flag pixels the post-processor
    # SHOULD have neutralized but did not. Anything outside Tier B's gate is
    # legitimate costume color (purple shadows, dark hair) and not a defect.
    #
    # Tier B gates (matched 1:1 with neutralize_interior_magenta_spill):
    #  - r >= 130, b >= 90, g <= 100  (pink-cast color signature)
    #  - r - g > 90, b - g > 50       (high color separation, not muddy)
    #  - b * 100 <= r * 110           (pink/magenta hue, not purple)
    #
    # Costume protection: a manager's purple-shadow pixel (132, 56, 129)
    # has r-g=76 < 90, fails the tier-B gate, NOT flagged. A magenta bleed
    # pixel (250, 25, 202) has r-g=225 > 90, b-g=177 > 50, B*100=20200
    # vs R*110=27500 ✓ -- IS flagged. The asymmetry is intentional.
    wide = (r >= 130) & (b >= 90) & (g <= 100) & ((r - g) > 90) & ((b - g) > 50) & (b * 100 <= r * 110) & visible

    strict_count = int(strict.sum())
    wide_count = int(wide.sum())
    pct = (strict_count + wide_count) / max(total_visible, 1) * 100.0
    passed = strict_count <= threshold_strict and wide_count <= threshold_wide

    return {
        "strict_count": strict_count,
        "wide_count": wide_count,
        "total_visible": total_visible,
        "pct": round(pct, 4),
        "passed": passed,
    }


def verify_grid_alignment(
    img: Image.Image | Path | str,
    grid_rows: int,
    grid_cols: int,
    cell_size: int,
    edge_margin_px: int = 2,
    violation_tolerance: int = 1,
) -> dict:
    """Per-cell alignment check: each cell's character must clear cell edges.

    For each cell (row, col) in the sheet:
      1. Extract the cell at (col*cell_size, row*cell_size, ...)
      2. Find the alpha-bbox of non-background pixels
      3. Assert bbox top >= edge_margin_px and bbox bottom <= cell_size - edge_margin_px
         (and same for left/right). A character whose silhouette touches the
         cell boundary indicates an off-grid cut: the slicer placed the cell
         boundary inside another character's body.

    Returns `{violations: [{row, col, side, bbox}, ...], passed: bool}`.
    Empty cells (no opaque pixels) are NOT counted as violations -- the sheet
    may legitimately have idle frames.

    The check is deliberately conservative: edge_margin_px=2 catches
    only the hard "character runs into cell edge" failure, not artistic
    silhouettes that happen to touch a 1-pixel margin. Tune per asset if
    needed.
    """
    if not HAS_NUMPY:
        return {"violations": [], "passed": True, "error": "numpy required"}

    if isinstance(img, (str, Path)):
        img = Image.open(img)
    img = img.convert("RGBA")
    arr = np.array(img)

    expected_w = grid_cols * cell_size
    expected_h = grid_rows * cell_size
    if arr.shape[1] != expected_w or arr.shape[0] != expected_h:
        return {
            "violations": [],
            "passed": False,
            "error": (f"image size {(arr.shape[1], arr.shape[0])} != expected {(expected_w, expected_h)}"),
        }

    # The failure mode this verifier targets: the slicer placed a cell
    # boundary mid-body (the naive-grid cell_size bug fixed in 53c6915).
    # Symptom: the bbox spans most of the cell AND touches both opposing
    # edges (left+right span = horizontal slice, top+bottom span =
    # vertical slice). A single edge touch is normal -- arms can extend
    # past one side in an action pose, ground-line anchoring intentionally
    # puts feet near cell bottom. We only flag the "sliced clean through"
    # pattern.
    violations: list[dict] = []
    span_threshold = 0.85  # bbox must cover >=85% of axis to count as a "slice"
    for row in range(grid_rows):
        for col in range(grid_cols):
            x0, y0 = col * cell_size, row * cell_size
            cell = arr[y0 : y0 + cell_size, x0 : x0 + cell_size]
            alpha = cell[..., 3]
            ys, xs = np.where(alpha > 0)
            if len(ys) == 0:
                continue  # empty cell, fine
            bbox_top = int(ys.min())
            bbox_bot = int(ys.max())
            bbox_left = int(xs.min())
            bbox_right = int(xs.max())

            top_hit = bbox_top < edge_margin_px
            bot_hit = bbox_bot > cell_size - 1 - edge_margin_px
            left_hit = bbox_left < edge_margin_px
            right_hit = bbox_right > cell_size - 1 - edge_margin_px

            h_span = (bbox_right - bbox_left + 1) / cell_size
            v_span = (bbox_bot - bbox_top + 1) / cell_size

            # "Sliced left-to-right": left+right both hit AND span is large
            horizontal_slice = left_hit and right_hit and h_span >= span_threshold
            # "Sliced top-to-bottom" (excluding ground-line + small char):
            # top+bottom both hit AND span is large. Ground-line alone hits
            # bottom only, so top+bottom together implies real slicing.
            vertical_slice = top_hit and bot_hit and v_span >= span_threshold

            if horizontal_slice or vertical_slice:
                violations.append(
                    {
                        "row": row,
                        "col": col,
                        "pattern": "horizontal_slice" if horizontal_slice else "vertical_slice",
                        "bbox": [bbox_left, bbox_top, bbox_right, bbox_bot],
                        "h_span": round(h_span, 3),
                        "v_span": round(v_span, 3),
                        "edges_hit": [
                            s
                            for s, hit in [
                                ("top", top_hit),
                                ("bottom", bot_hit),
                                ("left", left_hit),
                                ("right", right_hit),
                            ]
                            if hit
                        ],
                    }
                )

    # Tolerate up to violation_tolerance isolated violations. The naive-grid
    # cell_size bug produced 30+ violations across the whole sheet (a slice
    # cut every character). A single big-character cell is normal art and
    # should not hard-fail the verification gate.
    return {
        "violations": violations,
        "passed": len(violations) <= violation_tolerance,
        "violation_count": len(violations),
        "tolerance": violation_tolerance,
    }


def _slice_grid_into_cells(img: Image.Image, cols: int, rows: int) -> list[Image.Image]:
    """Strict integer slice for an exact-size sheet (final-sheet.png).

    Different from `slice_grid_cells` (which derives pitch from raw size for
    image-gen output). The verifier's input is the canonical post-processed
    final-sheet whose pitch IS cell_size by construction.
    """
    w, h = img.size
    cw, ch = w // cols, h // rows
    cells: list[Image.Image] = []
    for r in range(rows):
        for c in range(cols):
            cells.append(img.crop((c * cw, r * ch, (c + 1) * cw, (r + 1) * ch)))
    return cells


def verify_anchor_consistency(
    img: Image.Image | Path | str,
    grid_cols: int,
    grid_rows: int,
    cell_size: int,
    max_centroid_y_stddev_px: float = 8.0,
    iqr_outlier_multiplier: float = 2.0,
) -> dict:
    """Per-frame mass-centroid Y stddev gate. Catches the "hop" failure class.

    Why this gate exists: under bbox-bottom anchoring, frames whose bbox-bottom
    is a fist (lunge) or an extended leg (kick) get the wrong body part pinned
    to the ground line. The visible result is the trunk floating up by 30-50px
    on those frames — the user's "hop" reproduction. bbox-bottom-Y stddev is
    0 (the anchor IS pinning it!), so the existing verifier passes; the visible
    motion lives in the centroid.

    Flags:
      - centroid-Y stddev > max_centroid_y_stddev_px → fail (broad drift)
      - any frame's centroid more than IQR*multiplier from median → outlier

    Tuning: 8px stddev is the empirical "barely visible" threshold for 256px
    cells; tighten to 4px for portrait-loops where the camera is fixed and
    drift would be jarring.
    """
    if not HAS_NUMPY:
        return {"passed": True, "stddev": 0, "outliers": [], "error": "numpy required"}
    if isinstance(img, (str, Path)):
        img = Image.open(img)
    img = img.convert("RGBA")
    cells = _slice_grid_into_cells(img, grid_cols, grid_rows)
    centroids: list[float] = []
    for cell in cells:
        c = find_alpha_mass_centroid(cell)
        if c is None:
            centroids.append(float("nan"))
        else:
            centroids.append(c[1])
    valid = [c for c in centroids if not np.isnan(c)]
    if len(valid) < 2:
        return {
            "passed": True,
            "stddev": 0.0,
            "outliers": [],
            "centroid_y_per_cell": centroids,
            "valid_count": len(valid),
        }
    arr = np.array(valid)
    stddev = float(arr.std(ddof=0))
    median = float(np.median(arr))
    q1 = float(np.percentile(arr, 25))
    q3 = float(np.percentile(arr, 75))
    iqr = max(q3 - q1, 1.0)
    cutoff = iqr * iqr_outlier_multiplier
    outliers: list[dict] = []
    for i, c in enumerate(centroids):
        if np.isnan(c):
            continue
        if abs(c - median) > cutoff:
            outliers.append(
                {
                    "cell_index": i,
                    "centroid_y": round(c, 2),
                    "median": round(median, 2),
                    "delta_from_median": round(abs(c - median), 2),
                }
            )
    # Hard fail: stddev > threshold (broad drift across the cycle).
    # Hard fail: any outlier whose delta from median exceeds ABSOLUTE
    #   px threshold = max_stddev * 2 (so delta > 16px on default config).
    #   This catches a single-frame "hop" where one frame is dramatically
    #   shifted — the user's 05 powerhouse case had outlier deltas of
    #   ~40px under bbox-bottom anchor.
    # Soft signal: smaller outliers (delta in [stddev_threshold, 2x]) are
    #   surfaced but pass — they cover legitimate aerial frames.
    abs_outlier_threshold = max_centroid_y_stddev_px * 2
    big_outliers = [o for o in outliers if o["delta_from_median"] > abs_outlier_threshold]
    passed = stddev <= max_centroid_y_stddev_px and not big_outliers
    return {
        "passed": passed,
        "stddev": round(stddev, 3),
        "median": round(median, 2),
        "iqr": round(iqr, 2),
        "outliers": outliers,
        "big_outliers": big_outliers,
        "max_stddev_threshold": max_centroid_y_stddev_px,
        "abs_outlier_threshold_px": abs_outlier_threshold,
        "centroid_y_per_cell": [round(c, 2) if not np.isnan(c) else None for c in centroids],
    }


# TODO(ADR-207 RC-3 follow-up): verify_frames_have_content checks alpha
# pixel count on the FINAL only. It does not cross-reference the raw
# silhouette per cell. ADR-207 partially closes this with the new
# verify_raw_vs_final_cell_parity gate, which IS the raw-vs-final
# cross-check. A future RC-3 closure would unify the two gates: a single
# gate that examines per-cell alpha-coverage in the FINAL, conditioned on
# raw silhouette presence, with a unified diagnostic. Tracked as an
# RC-3 follow-up; not in scope for ADR-207.
def verify_frames_have_content(
    img: Image.Image | Path | str,
    grid_cols: int,
    grid_rows: int,
    cell_size: int,
    min_alpha_pixel_pct: float = 2.0,
    max_blank_count: int = 0,
    expected_empty_cells: list[tuple[int, int]] | None = None,
) -> dict:
    """Per-cell alpha-coverage gate. Catches blank-cell failure class.

    A cell with <min_alpha_pixel_pct% opaque pixels is considered blank.

    When this gate fires: the post-processing extracted a blank cell. DO NOT
    regenerate via Codex as a fix. Codex output is ground truth -- the raw
    almost certainly has content in that cell. The bug is in our slicer's
    grid pitch math (raw_size / grid_dim mismatch), the connected-components
    centroid-to-cell mapping, or the despill chain over-trimming the
    silhouette. Open the raw at the corresponding cell coordinates to confirm
    content exists, then trace which post-processing step lost it.

    See references/error-catalog.md "Anti-pattern: Codex Regeneration as a
    Post-Processing Fix" for the full diagnostic procedure.

    The default (max_blank_count=0) is strict; relax for assets where one
    blank frame is a deliberate art choice.

    Args:
        expected_empty_cells: List of (row, col) tuples for cells that are
            intentionally empty (e.g. per-row mode padding). These cells are
            excluded from the blank-cell check entirely.
    """
    if not HAS_NUMPY:
        return {"passed": True, "blank_cells": [], "error": "numpy required"}
    if isinstance(img, (str, Path)):
        img = Image.open(img)
    img = img.convert("RGBA")
    cells = _slice_grid_into_cells(img, grid_cols, grid_rows)
    # Build a set of linear cell indices to skip (per-row padding cells).
    skip_indices: set[int] = set()
    if expected_empty_cells:
        for row, col in expected_empty_cells:
            skip_indices.add(row * grid_cols + col)
    blanks: list[dict] = []
    pcts: list[float] = []
    for i, cell in enumerate(cells):
        arr = np.array(cell)
        alpha = arr[..., 3]
        pct = float((alpha > 16).sum()) / max(alpha.size, 1) * 100.0
        pcts.append(round(pct, 2))
        if i in skip_indices:
            continue
        if pct < min_alpha_pixel_pct:
            blanks.append({"cell_index": i, "alpha_pct": round(pct, 2)})
    result: dict = {
        "passed": len(blanks) <= max_blank_count,
        "blank_cells": blanks,
        "alpha_pct_per_cell": pcts,
        "min_alpha_pct_threshold": min_alpha_pixel_pct,
    }
    if blanks:
        # Actionable failure message: never recommend regenerating Codex.
        result["actionable_message"] = (
            "post-processing extracted a blank cell -- debug slicer alignment for this "
            "asset's grid (raw_size x grid pitch math), connected-components centroid "
            "mapping, or despill over-trim. Codex output is ground truth; do NOT "
            "regenerate the raw. See references/error-catalog.md 'Anti-pattern: Codex "
            "Regeneration as a Post-Processing Fix'."
        )
    return result


def _dhash(img: Image.Image, size: int = 8) -> int:
    """Difference-hash for perceptual similarity (homemade, no imagehash dep).

    Reduces image to (size+1) by size grayscale, then encodes pairwise horizontal
    differences as bits. Hamming distance between two dHashes correlates with
    perceptual similarity. dHash is robust to small color/lighting changes
    while remaining sensitive to silhouette shape — appropriate for catching
    near-duplicate animation frames.
    """
    if HAS_NUMPY:
        small = img.convert("L").resize((size + 1, size), Image.Resampling.LANCZOS)
        arr = np.array(small)
        diff = arr[:, 1:] > arr[:, :-1]
        bits = 0
        for v in diff.flatten():
            bits = (bits << 1) | int(v)
        return bits
    # pure-python fallback
    small = img.convert("L").resize((size + 1, size), Image.Resampling.LANCZOS)
    px = small.load()
    bits = 0
    for y in range(size):
        for x in range(size):
            bits = (bits << 1) | (1 if px[x + 1, y] > px[x, y] else 0)
    return bits


def _hamming(a: int, b: int) -> int:
    return bin(a ^ b).count("1")


def verify_frames_distinct(
    img: Image.Image | Path | str,
    grid_cols: int,
    grid_rows: int,
    cell_size: int,
    hamming_threshold: int = 4,
    max_duplicate_pct: float = 10.0,
    skip_blank_cells: bool = True,
    blank_alpha_pct: float = 2.0,
    expected_empty_cells: list[tuple[int, int]] | None = None,
) -> dict:
    """Perceptual-hash duplicate-frame gate. Catches "two frames merged" failure.

    Pairs with `verify_frames_have_content`: blank cells are dropped from the
    duplicate analysis (skip_blank_cells=True default), because two blank
    cells would falsely register as a duplicate pair.

    Behavior:
      - Compute dHash for every cell with content.
      - Pair-wise Hamming distance: any pair with distance < hamming_threshold
        counts as a duplicate.
      - Fail if duplicate_pct > max_duplicate_pct.

    Tuning: idle loops (subtle breath/blink) often have legitimate hamming
    distances around 2-3, so default threshold 4 + tolerance 10% leaves
    headroom. Action cycles should hit far higher distances; if dup_pct
    exceeds threshold, the cycle is broken (frames repeated).

    Args:
        expected_empty_cells: List of (row, col) tuples for cells that are
            intentionally empty (e.g. per-row mode padding). These cells are
            excluded from duplicate analysis regardless of skip_blank_cells.

    Returns the involved cell indices for diagnosis.
    """
    if not HAS_NUMPY:
        return {"passed": True, "duplicate_pairs": [], "error": "numpy required"}
    if isinstance(img, (str, Path)):
        img = Image.open(img)
    img = img.convert("RGBA")
    cells = _slice_grid_into_cells(img, grid_cols, grid_rows)
    # Build a set of linear cell indices to skip (per-row padding cells).
    skip_indices: set[int] = set()
    if expected_empty_cells:
        for row, col in expected_empty_cells:
            skip_indices.add(row * grid_cols + col)
    if skip_blank_cells:
        # Pre-filter to cells with content so blank vs blank doesn't pollute.
        valid_cells: list[tuple[int, Image.Image]] = []
        for i, c in enumerate(cells):
            if i in skip_indices:
                continue
            arr = np.array(c)
            pct = float((arr[..., 3] > 16).sum()) / max(arr[..., 3].size, 1) * 100.0
            if pct >= blank_alpha_pct:
                valid_cells.append((i, c))
    else:
        valid_cells = [(i, c) for i, c in enumerate(cells) if i not in skip_indices]
    hashes = [(i, _dhash(c)) for i, c in valid_cells]
    duplicates: list[dict] = []
    cells_in_dup: set[int] = set()
    for ai in range(len(hashes)):
        for bi in range(ai + 1, len(hashes)):
            i1, h1 = hashes[ai]
            i2, h2 = hashes[bi]
            d = _hamming(h1, h2)
            if d < hamming_threshold:
                duplicates.append({"a_index": i1, "b_index": i2, "hamming_distance": d})
                cells_in_dup.add(i1)
                cells_in_dup.add(i2)
    n = len(cells)
    # Pct = fraction of cells participating in at least one dup pair.
    # This is bounded [0, 100]. Earlier formula (pairs * 2 / n) explodes
    # past 100% on action sheets where every pair fires.
    dup_pct = len(cells_in_dup) / max(n, 1) * 100.0
    return {
        "passed": dup_pct <= max_duplicate_pct,
        "duplicate_pairs": duplicates,
        "duplicate_pct": round(dup_pct, 2),
        "max_duplicate_pct_threshold": max_duplicate_pct,
        "hamming_threshold": hamming_threshold,
        "valid_cell_count": len(hashes),
        "cells_in_duplicate_pairs": sorted(cells_in_dup),
    }


def verify_pixel_preservation(
    raw_path: Path | str,
    final_sheet_path: Path | str,
    grid_cols: int,
    grid_rows: int,
    cell_size: int,
    chroma_threshold: int = 90,
    min_pixel_ratio: float = 0.40,
    min_raw_pixels_per_cell: int = 200,
    max_lossy_cells_pct: float = 25.0,
) -> dict:
    """Compare raw cell silhouette pixel count against final cell pixel count.

    Catches the "effects clipped" failure (asset 27 dragon flame breath,
    where the fire breath is despilled to oblivion) AND the "entire silhouette
    lost" failure (asset 19 painted veteran, where pass2 over-floods).

    Methodology (intentionally conservative against painted-style halo):
      - Use chroma_threshold=90 for the raw count (matches pass2 cutoff).
        Pixels with sum-of-abs-diff to magenta < 90 are halo, not silhouette.
        This avoids the false-positive where antialiased magenta-fringe
        inflates raw_count and makes preservation look bad.
      - For each cell, ratio = final_visible / raw_silhouette.
      - Fail when more than max_lossy_cells_pct of cells lose >60% of their
        silhouette (ratio < 0.40). This is the "the despill chain ate the
        character" signal, not the noise of normal halo trimming.

    Cells with raw_silhouette < min_raw_pixels_per_cell are skipped (they're
    too sparse to evaluate ratio meaningfully).
    """
    if not HAS_NUMPY:
        return {"passed": True, "lossy_cells": [], "error": "numpy required"}
    raw = Image.open(raw_path).convert("RGBA")
    fin = Image.open(final_sheet_path).convert("RGBA")
    rw, rh = raw.size
    raw_cell_w = rw / grid_cols
    raw_cell_h = rh / grid_rows
    # Normalize: when raw cell area differs from final cell area (e.g. Codex
    # returns 1254x1254 for a 512x512 target), the raw silhouette pixel
    # count is N times the final's even at 100% preservation, where
    # N = raw_cell_area / final_cell_area. Account for this so the ratio
    # measures REAL silhouette preservation, not area scale.
    area_ratio = (raw_cell_w * raw_cell_h) / max(cell_size * cell_size, 1)
    raw_cells: list[Image.Image] = []
    for r in range(grid_rows):
        for c in range(grid_cols):
            x0 = round(c * raw_cell_w)
            y0 = round(r * raw_cell_h)
            x1 = round((c + 1) * raw_cell_w)
            y1 = round((r + 1) * raw_cell_h)
            raw_cells.append(raw.crop((x0, y0, x1, y1)))
    fin_cells = _slice_grid_into_cells(fin, grid_cols, grid_rows)
    chroma = np.array((255, 0, 255))
    ratios: list[dict] = []
    lossy: list[dict] = []
    n_evaluated = 0
    for i, (rc, fc) in enumerate(zip(raw_cells, fin_cells)):
        ra = np.array(rc.convert("RGBA"))
        rgb = ra[..., :3].astype(int)
        diff = np.abs(rgb - chroma).sum(axis=-1)
        raw_n = int((diff > chroma_threshold).sum())
        fa = np.array(fc.convert("RGBA"))
        fin_n = int((fa[..., 3] > 16).sum())
        # Expected final pixels under 100% preservation: raw_n / area_ratio
        expected_final = raw_n / max(area_ratio, 1e-6)
        if expected_final < min_raw_pixels_per_cell:
            ratios.append({"cell_index": i, "raw": raw_n, "final": fin_n, "ratio": None, "skipped": True})
            continue
        # Area-normalized ratio = how much of the expected silhouette survived.
        ratio = fin_n / max(expected_final, 1)
        # Cap at 1.0; ratios > 1 just mean more pixels survived than the raw
        # silhouette had (legitimate when bg-removal cleans halo and the area-
        # normalized estimate is conservative).
        ratio = min(ratio, 2.0)
        ratios.append(
            {
                "cell_index": i,
                "raw": raw_n,
                "final": fin_n,
                "expected": round(expected_final, 1),
                "ratio": round(ratio, 3),
            }
        )
        n_evaluated += 1
        if ratio < min_pixel_ratio:
            lossy.append(
                {
                    "cell_index": i,
                    "raw_silhouette": raw_n,
                    "final_visible": fin_n,
                    "expected_final": round(expected_final, 1),
                    "ratio": round(ratio, 3),
                }
            )
    lossy_pct = (len(lossy) / max(n_evaluated, 1)) * 100.0
    result: dict = {
        "passed": lossy_pct <= max_lossy_cells_pct,
        "lossy_cells": lossy,
        "lossy_pct": round(lossy_pct, 2),
        "ratios": ratios,
        "area_ratio_raw_to_final": round(area_ratio, 3),
        "min_pixel_ratio_threshold": min_pixel_ratio,
        "max_lossy_pct_threshold": max_lossy_cells_pct,
    }
    if not result["passed"]:
        result["actionable_message"] = (
            "Content extends past the conceptual cell boundary in the raw "
            "(Codex paints fire jets, projectile trails, auras that cross "
            "cell pitch). For LEGITIMATE EFFECTS ASSETS (fire breath, plasma "
            "trails, projectile auras), pass --effects-asset on the spec to "
            "opt INTO content-aware routing on a dense grid. ADR-207 RC-1: "
            "do NOT enable content_aware_extraction on dense character grids "
            "(>= 4x4 with >= 16 cells) -- the slicer dispatch will downgrade "
            "it to strict-pitch with a warning. For dense-grid blank-cell "
            "diagnostics, see verify_raw_vs_final_cell_parity instead. "
            "Codex output is ground truth; do NOT regenerate the raw."
        )
    return result


def verify_raw_vs_final_cell_parity(
    raw_path: Path | str,
    final_sheet_path: Path | str,
    grid_cols: int,
    grid_rows: int,
    cell_size: int,
    chroma_threshold: int = 80,
    min_raw_pixels_per_cell: int = 200,
    min_final_alpha_pixels_per_cell: int = 200,
) -> dict:
    """Per-cell parity gate: if raw cell has content, final cell MUST have content.

    ADR-207 Rule 3 / RC-1: catches the smoking-gun blank-cell failure mode.
    `verify_pixel_preservation` measures silhouette-survival ratio (how
    much of the raw silhouette landed in the final). This gate is the
    conservative complement: it only asks "did SOMETHING land?" When the
    raw has > `min_raw_pixels_per_cell` non-magenta pixels in a cell, the
    final's corresponding cell MUST have > `min_final_alpha_pixels_per_cell`
    visible alpha pixels.

    The two thresholds are intentionally symmetric (200 each) so the gate
    fires precisely when the cell went from "has content" to "blank" --
    the RC-1 failure signature. Cells the raw legitimately leaves empty
    (e.g. an animation pose where the character is briefly off-frame)
    skip the check because the precondition is not met.

    Pure numpy. Returns:
      passed: bool
      blank_cells: list[{cell_index, raw_silhouette, final_visible}]
      total_cells_with_raw_content: int
      ratio_pass: float (cells with content -> cells preserved / total)
    """
    if not HAS_NUMPY:
        return {"passed": True, "blank_cells": [], "error": "numpy required"}
    raw = Image.open(raw_path).convert("RGBA")
    fin = Image.open(final_sheet_path).convert("RGBA")
    rw, rh = raw.size
    raw_cell_w = rw / grid_cols
    raw_cell_h = rh / grid_rows
    raw_cells: list[Image.Image] = []
    for r in range(grid_rows):
        for c in range(grid_cols):
            x0 = round(c * raw_cell_w)
            y0 = round(r * raw_cell_h)
            x1 = round((c + 1) * raw_cell_w)
            y1 = round((r + 1) * raw_cell_h)
            raw_cells.append(raw.crop((x0, y0, x1, y1)))
    fin_cells = _slice_grid_into_cells(fin, grid_cols, grid_rows)
    chroma = np.array((255, 0, 255))
    blanks: list[dict] = []
    cells_with_raw_content = 0
    cells_preserved = 0
    for i, (rc, fc) in enumerate(zip(raw_cells, fin_cells)):
        ra = np.array(rc.convert("RGBA"))
        rgb = ra[..., :3].astype(int)
        diff = np.abs(rgb - chroma).sum(axis=-1)
        raw_n = int((diff > chroma_threshold).sum())
        if raw_n <= min_raw_pixels_per_cell:
            # Raw cell is essentially empty; gate's precondition not met.
            continue
        cells_with_raw_content += 1
        fa = np.array(fc.convert("RGBA"))
        fin_n = int((fa[..., 3] > 16).sum())
        if fin_n <= min_final_alpha_pixels_per_cell:
            blanks.append(
                {
                    "cell_index": i,
                    "raw_silhouette": raw_n,
                    "final_visible": fin_n,
                }
            )
        else:
            cells_preserved += 1
    ratio = (cells_preserved / cells_with_raw_content) if cells_with_raw_content > 0 else 1.0
    result: dict = {
        "passed": len(blanks) == 0,
        "blank_cells": blanks,
        "total_cells_with_raw_content": cells_with_raw_content,
        "cells_preserved": cells_preserved,
        "preservation_ratio": round(ratio, 3),
        "min_raw_pixels_per_cell": min_raw_pixels_per_cell,
        "min_final_alpha_pixels_per_cell": min_final_alpha_pixels_per_cell,
    }
    if blanks:
        result["actionable_message"] = (
            "ADR-207 RC-1 cell-parity violation: raw cell(s) have content but the "
            "corresponding final cell(s) are blank. Most common cause: the slicer "
            "routed the cell's content to a neighbor cell via centroid drift "
            "(content-aware on a dense Codex raw). Check that the pipeline used "
            "slice_grid_cells (strict-pitch), not slice_with_content_awareness, "
            "for this dense grid. Codex output is ground truth; do NOT regenerate."
        )
    return result


def verify_padding(
    img: Image.Image | Path | str,
    grid_cols: int,
    grid_rows: int,
    cell_size: int,
    max_padding_pct: float = 15.0,
    expected_empty_cells: list[tuple[int, int]] | None = None,
) -> dict:
    """Per-cell padding gate: sprite must not have excessive transparent padding.

    For each frame cell, checks that the sprite doesn't have >max_padding_pct%
    transparent padding on any side. Excessive padding means the sprite is too
    small relative to its cell -- the generator underutilized the frame.

    Args:
        img: Final sheet image (PIL Image, Path, or str).
        grid_cols: Number of columns.
        grid_rows: Number of rows.
        cell_size: Cell size in pixels.
        max_padding_pct: Maximum allowed padding on any side as percentage of
            cell dimension (default 15.0).
        expected_empty_cells: List of (row, col) tuples for intentionally empty
            cells (per-row mode padding). Skipped entirely.

    Returns:
        Dict with passed, frames_with_excess_padding, max_padding_pct fields.
    """
    if not HAS_NUMPY:
        return {"passed": True, "frames_with_excess_padding": [], "max_padding_pct": 0.0, "error": "numpy required"}

    if isinstance(img, (str, Path)):
        img = Image.open(img)
    img = img.convert("RGBA")
    cells = _slice_grid_into_cells(img, grid_cols, grid_rows)

    skip_indices: set[int] = set()
    if expected_empty_cells:
        for row, col in expected_empty_cells:
            skip_indices.add(row * grid_cols + col)

    excess_frames: list[dict] = []
    overall_max_pct = 0.0

    for i, cell in enumerate(cells):
        if i in skip_indices:
            continue

        arr = np.array(cell)
        alpha = arr[..., 3]
        ys, xs = np.where(alpha > 16)

        if len(ys) == 0:
            # Entirely empty -- skip (verify_frames_have_content handles this)
            continue

        bbox_top = int(ys.min())
        bbox_bot = int(ys.max())
        bbox_left = int(xs.min())
        bbox_right = int(xs.max())

        h, w = alpha.shape
        top_pct = (bbox_top / h) * 100.0
        bottom_pct = ((h - 1 - bbox_bot) / h) * 100.0
        left_pct = (bbox_left / w) * 100.0
        right_pct = ((w - 1 - bbox_right) / w) * 100.0

        frame_max = max(top_pct, bottom_pct, left_pct, right_pct)
        overall_max_pct = max(overall_max_pct, frame_max)

        if frame_max > max_padding_pct:
            excess_frames.append(
                {
                    "cell_index": i,
                    "row": i // grid_cols,
                    "col": i % grid_cols,
                    "top_pct": round(top_pct, 1),
                    "bottom_pct": round(bottom_pct, 1),
                    "left_pct": round(left_pct, 1),
                    "right_pct": round(right_pct, 1),
                    "max_side_pct": round(frame_max, 1),
                }
            )

    return {
        "passed": len(excess_frames) == 0,
        "frames_with_excess_padding": excess_frames,
        "max_padding_pct": round(overall_max_pct, 1),
        "threshold_pct": max_padding_pct,
    }


def verifier_verdict_from_passed(passed: bool) -> str:
    """Derive the contracted verifier_verdict string from the passed bool.

    ADR-207 Rule 2: this is the ONLY function that maps verifier outcomes
    to the public verdict string. Consumers (manifest writers, orchestrators)
    MUST derive their `verifier_verdict` field from this function so the
    field is structurally consistent across producers.
    """
    return "PASS" if passed else "FAIL"


def write_manifest_record(path: Path | str, record: dict) -> None:
    """Asserting writer for manifest records (ADR-207 Rule 2).

    Enforces the verifier-truthfulness contract at WRITE time: a record
    with ``verifier_verdict == "PASS"`` AND a non-empty ``verifier_failures``
    is structurally inconsistent and cannot be persisted. Raises ``ValueError``.

    The contract:
      verifier_verdict == "PASS"  =>  verifier_failures empty (or absent)
      verifier_verdict == "FAIL"  =>  verifier_failures non-empty
      verifier_verdict missing    =>  no enforcement (legacy records)

    Consumers (orchestrators, manifest writers) SHOULD use this writer
    instead of writing JSON directly. The street-fighter-demo orchestrator
    is the reference consumer (see scripts/sf-orchestrator.py).
    """
    verdict = record.get("verifier_verdict")
    failures = record.get("verifier_failures") or []
    if verdict == "PASS" and len(failures) > 0:
        raise ValueError(
            f"manifest contract violation (ADR-207 Rule 2): record claims "
            f"verifier_verdict='PASS' but verifier_failures has {len(failures)} "
            f"entries. Re-run the verifier or set verifier_verdict='FAIL'."
        )
    if verdict == "FAIL" and len(failures) == 0:
        raise ValueError(
            "manifest contract violation (ADR-207 Rule 2): record claims "
            "verifier_verdict='FAIL' but verifier_failures is empty. A FAIL "
            "verdict must carry at least one failure entry."
        )
    Path(path).write_text(json.dumps(record, indent=2), encoding="utf-8")


def verify_asset_outputs(
    asset_dir: Path | str,
    mode: str,
    grid: tuple[int, int] | None = None,
    cell_size: int | None = None,
    magenta_strict_threshold: int = 0,
    magenta_wide_threshold: int | None = None,
    has_effects: bool = False,
    allow_frame_duplication: bool = False,
) -> dict:
    """Combined build-time gate: run every verifier on every output file.

    Modes:
      - portrait        : check final.png only (single static image, no grid).
      - portrait-loop   : check final-sheet.png, frames-strip.png, animation.gif,
                          final.webp. Grid is fixed (2,2).
      - spritesheet     : check final-sheet.png, frames-strip.png if exists,
                          animation.gif, final.webp. Grid + cell_size required.

    Returns {passed: bool, failures: [{file, check, details}, ...]}.

    `passed=False` means at least one verifier flagged an issue. The caller
    (run_one in generate.py) records this on meta and the demo HTML hides
    the asset behind a red FAIL badge.
    """
    asset_dir = Path(asset_dir)
    failures: list[dict] = []

    # Per-mode wide-pink defaults. Painted portraits and animated GIF
    # quantization both leave a thin band of legitimate pink-cast pixels;
    # spritesheet final-sheet has crisper transparent edges and tolerates
    # less. The thresholds are tuned against the real asset corpus, NOT
    # synthetic canvases, because painted-style art (slay-the-spire-painted)
    # has dithering halftones that legitimately register as wide-pink.
    if magenta_wide_threshold is None:
        if mode == "portrait":
            magenta_wide_threshold = 50
        elif mode == "portrait-loop":
            magenta_wide_threshold = 80
        else:  # spritesheet
            magenta_wide_threshold = 30
    # has_effects assets paint legitimately-pink content (purple plasma arcs,
    # magenta-cast costumes) that the wide-pink heuristic cannot distinguish
    # from background bleed. We skip interior_neutralize_magenta_spill on these
    # to preserve the effects, so the verifier MUST also tolerate them. A
    # 30x relaxation gives breathing room for ~1000 legitimate pink-cast pixels
    # per cell while still catching the "entire silhouette is magenta" failure.
    # The strict (near-pure 255,0,255) threshold also relaxes from 0 to 200:
    # plasma orbs paint near-pure magenta arcs (255,99,255 is "wide"; 255,0,255
    # is "strict") that are intentional and survive despill skip.
    if has_effects:
        magenta_wide_threshold = magenta_wide_threshold * 30
        magenta_strict_threshold = max(magenta_strict_threshold, 200)
    # Format-specific tolerance: GIF and WebP quantization at silhouette
    # edges of magenta-adjacent assets (e.g. purple-suited managers with
    # magenta bg) is a known limitation of the lossy format -- the
    # adaptive palette / lossy compression resurrects pink pixels even
    # when the source RGBA is clean. PNG (lossless) gets the strict
    # threshold; GIF/WebP get a 10x relaxation because the pipeline cannot
    # eliminate format-induced bleed without dropping format support.
    lossy_wide_threshold = magenta_wide_threshold * 10

    files_to_check: list[tuple[str, str]] = []  # (filename, kind)
    if mode == "portrait":
        files_to_check = [("final.png", "static")]
    elif mode == "portrait-loop":
        if grid is None:
            grid = (2, 2)
        files_to_check = [
            ("final-sheet.png", "sheet"),
            ("frames-strip.png", "strip"),
            ("animation.gif", "anim"),
            ("final.webp", "anim"),
        ]
    elif mode == "spritesheet":
        if grid is None or cell_size is None:
            failures.append(
                {"file": "(spec)", "check": "config", "details": "grid + cell_size required for spritesheet mode"}
            )
            # ADR-208 N3: include verifier_verdict on early-return paths so
            # consumers reading the contract field always have it (matches
            # the late-return path at the bottom of this function).
            return {"passed": False, "verifier_verdict": "FAIL", "failures": failures}
        files_to_check = [
            ("final-sheet.png", "sheet"),
            ("frames-strip.png", "strip"),
            ("animation.gif", "anim"),
            ("final.webp", "anim"),
        ]
    else:
        # ADR-208 N3: include verifier_verdict on early-return paths.
        return {
            "passed": False,
            "verifier_verdict": "FAIL",
            "failures": [{"file": "(spec)", "check": "mode", "details": f"unknown mode {mode!r}"}],
        }

    cols, rows = grid if grid else (1, 1)

    for fname, kind in files_to_check:
        fpath = asset_dir / fname
        if not fpath.exists():
            # Not all files are required for every asset (frames-strip skipped
            # for >4096px width). Only fail on the always-required files:
            # portraits' final.png and modes' final-sheet.png.
            if (
                mode == "portrait"
                and fname == "final.png"
                or mode in ("portrait-loop", "spritesheet")
                and fname == "final-sheet.png"
            ):
                failures.append({"file": fname, "check": "exists", "details": "missing"})
            continue

        # Magenta check on every existing output. GIF/WebP get a relaxed
        # wide-pink threshold because lossy palette/compression resurrects
        # halo pixels at silhouette edges even when the RGBA source is
        # clean (documented in references/output-formats.md).
        is_lossy = fname.endswith((".gif", ".webp"))
        wide_t = lossy_wide_threshold if is_lossy else magenta_wide_threshold
        try:
            mag = verify_no_magenta(
                fpath,
                threshold_strict=magenta_strict_threshold,
                threshold_wide=wide_t,
            )
            if not mag["passed"]:
                failures.append(
                    {
                        "file": fname,
                        "check": "magenta",
                        "details": {
                            "strict_count": mag["strict_count"],
                            "wide_count": mag["wide_count"],
                            "thresholds": [magenta_strict_threshold, wide_t],
                        },
                    }
                )
        except Exception as e:
            failures.append({"file": fname, "check": "magenta", "details": f"error: {e}"})

        # Grid alignment check on the canonical sheet only (frames-strip is
        # 1xN row; alignment math doesn't apply the same way). Tolerance is
        # 5% of cells: legitimate big-character art can occasionally span an
        # edge, but more than that signals a slicing failure or a generator
        # that lost track of cell boundaries. A verifier that confirms success at 50%
        # bad-cell tolerance is a rubber stamp; the threshold must be tight
        # enough that "passed" carries evidence. For an 8x8 sheet that is 3
        # violations; for a 4x4 sheet that is 1 (matching verify_grid_alignment's
        # default tolerance of 1).
        if kind == "sheet" and mode in ("portrait-loop", "spritesheet"):
            if cell_size is None:
                cell_size = 512 if mode == "portrait-loop" else None
            if cell_size is not None:
                total_cells = cols * rows
                grid_tolerance = max(1, int(total_cells * 0.05))
                try:
                    grid_check = verify_grid_alignment(
                        fpath,
                        rows,
                        cols,
                        cell_size,
                        violation_tolerance=grid_tolerance,
                    )
                    violation_count = grid_check.get(
                        "violation_count",
                        len(grid_check.get("violations", [])),
                    )
                    if not grid_check["passed"]:
                        failures.append(
                            {
                                "file": fname,
                                "check": "grid_alignment",
                                "details": {
                                    "violations": grid_check.get("violations", [])[:5],
                                    "violation_count": violation_count,
                                    "tolerance": grid_check.get("tolerance"),
                                    "error": grid_check.get("error"),
                                },
                            }
                        )
                except Exception as e:
                    failures.append({"file": fname, "check": "grid_alignment", "details": f"error: {e}"})

                # New v8 gates (anchor-consistency, blank-frames,
                # distinct-frames, pixel-preservation). These run on the
                # canonical sheet only; lossy formats (gif/webp) are subject
                # to format-induced drift so re-checking centroids there
                # produces noise. The gates are tuned to catch the user's
                # 8-asset failure set without flagging legitimate art.
                # Tunings rationale:
                #   anchor stddev <= 8 px: visible threshold; the 05
                #     powerhouse "hop" measured 15.84px under bbox-bottom
                #     anchor, so 8 is a tight but achievable target with
                #     mass-centroid anchoring.
                #   max blank cells = 0: blanks are always errors; a
                #     deliberately empty cell would be a separate spec.
                #   duplicate threshold 4 + max 25%: idle loops have
                #     legitimately similar frames (subtle breath); 25% is
                #     "1 of 4" tolerated for portrait-loop and "4 of 16"
                #     for action sheets, which corresponds to legitimate
                #     stand-alone repeated-stance frames (asset 06 idle
                #     loop has 4 near-identical idle frames between taunt
                #     gestures).
                #   pixel preservation 0.40 ratio: under 60% silhouette
                #     loss is the "despill chain ate the character"
                #     symptom; gradual 30-40% trim is normal halo removal.
                # Per-mode gate selection:
                #   portrait-loop: stddev=4 (tighter — fixed camera, drift
                #     is obvious); allow 100% dup pct (every cell is
                #     supposed to be near-identical by construction).
                #   spritesheet: stddev=8, dup_pct=25.
                if mode == "portrait-loop":
                    anchor_stddev = 4.0
                    dup_pct_max = 100.0
                else:
                    anchor_stddev = 8.0
                    # ADR-208 RC-3: dup_pct_max tightened from 100.0 to 70.0.
                    # The forensic post-mortem on PR #530 found the 100.0
                    # value rendered the gate a no-op: it fired only on the
                    # "every single cell is identical" pathological case,
                    # which frames_have_content already catches via blank-
                    # cell detection. With 100.0 the gate could not detect
                    # the layout-drift failure mode where 60-90% of cells
                    # land on the same pose due to centroid mis-routing.
                    #
                    # 70.0 calibrated against the corpus:
                    #   - Action sheets (locomotion, kicks, punches): ~15-50%
                    #     duplicate pct under proper extraction; 70 leaves
                    #     headroom.
                    #   - 8x8 specials sheets containing a 4-frame anim
                    #     repeated 16 times: ~75-100% duplicate pct.
                    #     These need --allow-frame-duplication explicitly.
                    #   - The RC-1 layout-drift signature: 60-90% of cells
                    #     land on a few near-identical poses. 70 catches
                    #     this without false-positive on real animation.
                    #
                    # Idle loops (8 frames repeated to fill the sheet) opt
                    # out via --allow-frame-duplication on the spec, which
                    # passes through to dup_pct_max=100.0 for that asset.
                    dup_pct_max = 70.0
                    if has_effects:
                        # Effects assets (fire jets, plasma trails) often
                        # have repeated near-identical frames between
                        # animation peaks; relax to 100.0 like the legacy
                        # behavior.
                        dup_pct_max = 100.0
                    if allow_frame_duplication:
                        # Spec-level opt-out: idle loops, taunt poses, or
                        # 8-frame anims tiled across an 8x8 sheet
                        # legitimately have 70-100% duplicate-pct.
                        dup_pct_max = 100.0
                try:
                    anc = verify_anchor_consistency(
                        fpath,
                        cols,
                        rows,
                        cell_size,
                        max_centroid_y_stddev_px=anchor_stddev,
                    )
                    if not anc["passed"]:
                        failures.append(
                            {
                                "file": fname,
                                "check": "anchor_consistency",
                                "details": {
                                    "stddev": anc.get("stddev"),
                                    "threshold": anchor_stddev,
                                    "outliers": anc.get("outliers"),
                                    "median": anc.get("median"),
                                },
                            }
                        )
                except Exception as e:
                    failures.append({"file": fname, "check": "anchor_consistency", "details": f"error: {e}"})

                try:
                    blanks = verify_frames_have_content(
                        fpath,
                        cols,
                        rows,
                        cell_size,
                    )
                    if not blanks["passed"]:
                        failures.append(
                            {
                                "file": fname,
                                "check": "frames_have_content",
                                "details": {
                                    "blank_cells": blanks.get("blank_cells"),
                                    "alpha_pct_per_cell": blanks.get("alpha_pct_per_cell"),
                                },
                            }
                        )
                except Exception as e:
                    failures.append({"file": fname, "check": "frames_have_content", "details": f"error: {e}"})

                try:
                    dups = verify_frames_distinct(
                        fpath,
                        cols,
                        rows,
                        cell_size,
                        max_duplicate_pct=dup_pct_max,
                    )
                    if not dups["passed"]:
                        failures.append(
                            {
                                "file": fname,
                                "check": "frames_distinct",
                                "details": {
                                    "duplicate_pct": dups.get("duplicate_pct"),
                                    "threshold": dup_pct_max,
                                    "duplicate_pairs": dups.get("duplicate_pairs", [])[:5],
                                },
                            }
                        )
                except Exception as e:
                    failures.append({"file": fname, "check": "frames_distinct", "details": f"error: {e}"})

                # Pixel preservation: requires raw.png next to final-sheet.
                raw_path = asset_dir / "raw.png"
                if raw_path.exists():
                    try:
                        preservation = verify_pixel_preservation(
                            raw_path,
                            fpath,
                            cols,
                            rows,
                            cell_size,
                        )
                        if not preservation["passed"]:
                            failures.append(
                                {
                                    "file": fname,
                                    "check": "pixel_preservation",
                                    "details": {
                                        "lossy_pct": preservation.get("lossy_pct"),
                                        "lossy_cells": preservation.get("lossy_cells"),
                                        "threshold_pct": preservation.get("max_lossy_pct_threshold"),
                                        "min_ratio": preservation.get("min_pixel_ratio_threshold"),
                                    },
                                }
                            )
                    except Exception as e:
                        failures.append({"file": fname, "check": "pixel_preservation", "details": f"error: {e}"})

                    # ADR-207 Rule 3: cell-parity gate. Conservative blank-cell
                    # check that catches RC-1 directly (raw has content, final
                    # lost it). Runs alongside verify_pixel_preservation; both
                    # can fire on the same underlying failure with distinct
                    # diagnostics.
                    try:
                        parity = verify_raw_vs_final_cell_parity(
                            raw_path,
                            fpath,
                            cols,
                            rows,
                            cell_size,
                        )
                        if not parity["passed"]:
                            failures.append(
                                {
                                    "file": fname,
                                    "check": "verify_raw_vs_final_cell_parity",
                                    "details": {
                                        "blank_cells": parity.get("blank_cells"),
                                        "total_cells_with_raw_content": parity.get("total_cells_with_raw_content"),
                                        "preservation_ratio": parity.get("preservation_ratio"),
                                    },
                                }
                            )
                    except Exception as e:
                        failures.append(
                            {"file": fname, "check": "verify_raw_vs_final_cell_parity", "details": f"error: {e}"}
                        )

    # ADR-207 Rule 2: include the contracted verifier_verdict alongside the
    # legacy 'passed' field so consumers can derive their status fields from
    # an authoritative producer-side string. Legacy callers reading 'passed'
    # continue to work unchanged.
    passed = len(failures) == 0
    return {
        "passed": passed,
        "verifier_verdict": verifier_verdict_from_passed(passed),
        "failures": failures,
    }


def cmd_verify_asset(args: argparse.Namespace) -> int:
    """CLI: scan an asset dir and print PASS/FAIL with details.

    Reads meta.json from the asset_dir to learn mode/grid/cell_size if not
    overridden by flags. This is the user's no-loop deterministic check:

        python3 -m sprite_process verify-asset /abs/path/to/asset_dir

    For convenience, callers may export `SPRITE_DEMO_ROOT` and pass a bare
    slug; the resolver then tries `$SPRITE_DEMO_ROOT/assets/<slug>/`.
    """
    asset_dir = Path(args.asset_dir)
    if not asset_dir.is_absolute() and not asset_dir.exists():
        demo_root = os.environ.get("SPRITE_DEMO_ROOT")
        if demo_root:
            candidate = Path(demo_root) / "assets" / args.asset_dir
            if candidate.exists():
                asset_dir = candidate

    if not asset_dir.exists():
        logger.error("asset dir %s does not exist", asset_dir)
        return 2

    meta_path = asset_dir / "meta.json"
    mode = args.mode
    grid: tuple[int, int] | None = None
    cell_size = args.cell_size
    if meta_path.exists():
        meta = json.loads(meta_path.read_text(encoding="utf-8"))
        mode = mode or meta.get("mode")
        if not args.grid:
            g = meta.get("grid")
            if g and len(g) == 2:
                grid = (int(g[0]), int(g[1]))
        if cell_size is None:
            cell_size = meta.get("cell_size")
    if args.grid:
        cols, rows = _parse_grid(args.grid)
        grid = (cols, rows)
    if mode is None:
        logger.error("--mode required (no meta.json at %s)", meta_path)
        return 2

    # ADR-208 RC-3: --allow-frame-duplication relaxes the dup_pct_max gate
    # for spec-known idle-loop / taunt-pose / 8-into-64 sheets. Read from
    # CLI arg first; fall back to meta.json for sheets generated with the
    # spec opt-in.
    allow_dup = bool(getattr(args, "allow_frame_duplication", False))
    if not allow_dup and meta_path.exists():
        meta = json.loads(meta_path.read_text(encoding="utf-8"))
        allow_dup = bool(meta.get("allow_frame_duplication", False))

    result = verify_asset_outputs(
        asset_dir,
        mode,
        grid=grid,
        cell_size=cell_size,
        allow_frame_duplication=allow_dup,
    )
    print(json.dumps({"asset": str(asset_dir), "mode": mode, "grid": grid, "cell_size": cell_size, **result}, indent=2))
    # Exit code 2 == "verifier gates failed" per ADR-199; same code regardless
    # of standalone-CLI vs orchestrator surface.
    return 0 if result["passed"] else 2
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 321kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall