testsAndMisc/docs/superpowers/evidence/artgate-phase3-routes-2026-08-15.json

{
  "intent": "Close the two CPU-only cells of the art bake-off (route (a) procedural, route (d) code-as-art/vector) and build the finishing stage that every continuous-tone route needs, so the diffusion cell has a proven bridge waiting for it.",
  "scope": [
    "python_pkg/artgate/subjects.py - the fixed 12-subject set with its measured easy/hard split",
    "python_pkg/artgate/routes/{procedural,shapes,vector}.py - two route generators",
    "python_pkg/artgate/finish.py - the shared downscale/binarize/quantize bridge",
    "python_pkg/artgate/tests/{test_finish,test_routes}.py - 35 new tests",
    "NON-GOAL: no diffusion model downloaded or run; no 3D cell; no judgement of which icons look good"
  ],
  "changes": [
    "Pinned the bake-off to the same twelve subjects item-icons measured (key/scroll/book/bone/gem/bomb passed; potion/sword/shield/coin/ring/meat failed), so routes are compared on one task rather than on a convenient subject list. This makes the subject-routing rule falsifiable: a generator route is predicted to lift specifically the six human-prior failures.",
    "Route (a) draws all twelve subjects deterministically from a 7-colour locked palette, giving each shape a distinguishing feature up front because item-icons measured that plain primitives read as placeholders.",
    "Route (d) emits SVG as text and rasterises via rsvg-convert, adding no Python dependency (cairosvg/svgwrite are absent and stay absent).",
    "finish.py binarises alpha BEFORE quantising colour, mirroring the gate order: quantising first would blend transparent pixels' arbitrary RGB into the palette.",
    "MAX_ROUNDS = 2 encoded in code, because item-icons ran two redraw rounds and stayed at 6/12, so a third is not evidence-backed."
  ],
  "verification": [
    {
      "command": "python -m pytest python_pkg/artgate/tests/ --cov=python_pkg.artgate --cov-branch",
      "result": "pass",
      "evidence": "92 passed. 100% branch coverage on all ten modules including procedural.py, shapes.py, vector.py, finish.py, subjects.py. Zero suppressions."
    },
    {
      "command": "generate 12 procedural icons and gate each against styles/pixel_icon.toml",
      "result": "pass",
      "evidence": "12/12 machine-gate PASS. Noted explicitly: this proves 'not malformed', NOT quality - a procedural generator satisfies palette/alpha/canvas constraints trivially. The human contact sheet is the real verdict."
    },
    {
      "command": "render 5 vector subjects, gate raw, then gate after the finishing stage",
      "result": "pass",
      "evidence": "RAW: 0/5 pass - every one FAILs ALPHA_NOT_BINARY (+ TOO_MANY_COLORS on 4). AFTER finishing: 5/5 PASS. This is the structural finding: continuous-tone routes are generators feeding a finisher, not pixel-art generators."
    },
    {
      "command": "byte-comparison of all 12 icons before/after the lint refactor",
      "result": "pass",
      "evidence": "12/12 byte-identical. The PLR2004 fixes (OPAQUE constant, _GEM_WAIST) changed no pixels - verified rather than assumed."
    },
    {
      "command": "pre-commit run --files python_pkg/artgate/*.py python_pkg/artgate/routes/*.py python_pkg/artgate/tests/*.py",
      "result": "pass",
      "evidence": "ALL HOOKS PASS: ruff select=ALL, ruff-format, mypy strict, pylint, bandit, codespell, no-noqa, pytest+coverage."
    }
  ],
  "risks": [
    "Route (a) output is gate-clean by construction, so its machine-gate column is uninformative by design. Reading a 12/12 as 'route (a) wins' would be exactly the misreading the plan warns about; the decision table must weight human accept rate.",
    "The vector route currently covers 5 of the 12 subjects. The remaining 7 need SVG shapes before that cell's number is comparable to route (a)'s.",
    "The finishing stage's quality depends on the downscale filter; BOX was chosen for straight-alpha safety, but a different filter may suit painterly sources better and is untested.",
    "I reached for a `python - <<PY` heredoc twice for throwaway patch scripts, which this repo's CLAUDE.md forbids for real logic. Not committed, but the habit is worth breaking."
  ],
  "rollback": [
    "Delete python_pkg/artgate/routes/, finish.py, subjects.py and their tests; the gate harness from da8ca6d stands alone without them.",
    "After rollback, confirm pytest still reports 100% branch coverage for the remaining artgate modules and that no other package regressed."
  ]
}