content icon: --strict, --min-contrast and optional --ocr checks (#57)

CHANGELOG.md

@@ -8,6 +8,10 @@ All notable changes to `github-showcase-skill` are recorded here. Versions follo
 
 - `content icon normalize` auto mode keys any uniform ground to transparent unless it is a dark night tile (luminance < 0.2 and not within dE 12 of the card colour), so a flat pale ground on a dark card no longer needs `--ground transparent`; `--ground keep|transparent` are unchanged. New `--ground-tolerance DE` (default 3.0) widens the corner match for slightly vignetted grounds (e.g. `--ground-tolerance 5`); above it `icon-ground` names the measured corner dE and the flag. A raised tolerance widens the keying threshold only above 3.0 and flattens a kept night tile so QA accepts it. Auto falls back to keying when a kept night tile would exceed the 300 KB budget; non-finite or negative `--ground-tolerance` is a usage error, and `--ground-tolerance 0` accepts identical corners as one ground (a positive tolerance keeps the strict boundary). The option A icon prompt (bundled and estate-format templates) states the exact flat `card_fill` ground with no vignette, texture, gradient, shadow or glow; the estate BACKGROUND heading now says one flat ground (not the avatar night tile), and the exact ground clause is now appended whenever a BACKGROUND replacement removed it (checked after all replacements). The soft 3 dE key alpha ramp applies only with a raised `--ground-tolerance`; the default transparent key is unchanged (original 0/255 step).
 - `content icon normalize` flattens a vignetted kept night tile with a feathered ramp (6 dE) instead of a hard threshold, and the transparent key uses a soft alpha ramp, so a glow around a solid glyph keeps its continuity with no hard outer ring; the glyph edge stays hard. `--ground-tolerance` is covered through the CLI (a raised value is applied; `nan` and negative values exit 2), and the estate-template numbered BACKGROUND paragraph is replaced by the flat-ground wording, including explicit colour or radial-gradient text.
+- `content icon check` and `content icon normalize` take `--ocr` (opt-in, off by default) to read the icon with `tesseract` on `PATH` for text: words of 2 or more alphanumerics warn (fail with `--strict`); without the tool the check is skipped with `needs-input:ocr-unavailable` and `no-text` stays a manual review, so the result and exit code do not change. An unreadable or undecodable PNG (bad structure, or valid structure with corrupt compressed data) fails the icon as a structured `png` check, so `content icon check` then prints a JSON result with a `logs` list and exits 1 (bad arguments still exit 2); `logs` names the unreadable image as `unreadable-image:<path>`, with and without `--ocr`; the command never ends in a traceback. `content icon normalize` handles an unreadable or undecodable `--in` candidate the same way (exit 1, no file written, with and without `--ocr`; `logs` names the `--in` source as `unreadable-image:<path>` plus `art-fail:icon-qa`); a missing `--in` file stays a usage error (exit 2).
+- `content icon check` and `content icon normalize` now report a PNG with a trailing empty `iCCP` chunk, which made Pillow raise `IndexError`, as the structured PNG failure (exit 1, `unreadable-image` log) instead of a traceback.
+- `content icon check` and `content icon normalize` take `--min-contrast` (and the family key `icon_min_contrast`, range 1 to 21) to set the contrast floor of the icon ink on the card. Precedence is the flag, then the family key, then the default 3.0, so existing results do not change. 4.5:1 is recommended for the card plate but is not the default.
+- `content icon check` and `content icon normalize` take `--strict` (and the family key `icon_strict_family_ink: true`, off by default) to fail instead of warn when the dominant icon ink is not a family ink. Without a family palette the family-ink check is still not emitted.
 - `org labels ORG --repos-from-gh` plans labels across accessible repositories without the private estate registry, with paginated read-only GitHub capture, optional verified local checkouts, unchanged reference guards, and a documented org-default-forms-first workflow. Registry-backed plans still require the org registry row, and checkout repository names match GitHub case-insensitively, including resolved pending renames. Registry-free runs also isolate lazy brand lookups from estate decision files, and held reference rewrites retain their file/line guidance with an incomplete result. Workflow/labeler/release/Renovate references remain final skips rather than unresolved input requests. Missing Windows device-named checkouts fall back to captured metadata instead of aborting the org plan. Pending transfers check the repository's current owner's default issue forms and hold renames when that evidence is unavailable. Sparse or partially missing checkouts retain reference holds based on captured paths and the Git index, while unrelated omitted files remain allowed.
 
 ### Fixed

SKILL.md

@@ -223,6 +223,7 @@ project estate-plan [--copied FILE] [--user-id ID] [--source OWNER/N] [--jobs FI
 content social [--out PATH] [--title TEXT] [--icon PATH] [--job] [--allow-unmeasured] [--allow-hold]
 content icon prompt|normalize|check [--option A|B] [--glyph FILE] [--art-direction FILE] [--in PNG]
     [--ground auto|transparent|keep] [--ground-tolerance DE] [--out PATH] [--preview PATH]
+    [--strict] [--min-contrast RATIO] [--ocr]
 content links [FILE...] [--readme-path PATH] [--base-ref REF] [--online] [--cache FILE] [--strict] [--diff]
 content linguist [--min-share 0.02] [--language NAME]
 content actions [--runs FILE] [--workflows FILE] [--pages FILE] [--changed PATH...] [--approval WORKFLOW=ID]

references/brand.schema.json

@@ -223,6 +223,14 @@
     },
     "icon_pixel_art": {
      "type": "boolean"
+    },
+    "icon_strict_family_ink": {
+     "type": "boolean"
+    },
+    "icon_min_contrast": {
+     "type": "number",
+     "minimum": 1,
+     "maximum": 21
     }
    }
   },

references/content.md

@@ -27,8 +27,8 @@ Every action also takes `--report FILE` (the JSON result), `--jobs FILE` (append
 |---|---|---|---|
 | `social` | R10 | The 1280×640 repository social preview (the contract name; the top-level `social-preview` is a hidden, deprecated alias with the same options and file), plus with `--job` the `browser` upload job (Settings → Social preview → Edit → Upload, then a read-only `usesCustomOpenGraphImage` check). Public T1 and T2 repositories only, the personal-profile capstone and backups included; forks, archived, `.github` and Pages repositories get no job. The image's footer reads `github.com/<current login>/<repo>`, the slug the job uploads to (after an approved org rename, never the former login); when the rendered footer and the job's slug differ, the job is withheld (`needs-input:social-login`, exit 1). | `--out` |
 | `icon prompt` | RT-04 | Fills the repository-icon prompt from the art direction (option A: the Neon Night glyph; option B: the isometric illustration) and the repository's facts. The glyph itself is the writer's: `needs-writer` (exit 1) until `--glyph` supplies `glyph_name`, `glyph_description`, `spark_placement` and `size_class`; nothing is written before then. Option B appends the family addition (the trademark negatives in `references/art-direction.md`, such as the TCG one) found under any login of the org (CQ-03) or its display name, so a re-keyed `brand.yaml` row keeps it; when the org's addition is not in the art direction, the prompt is refused (`needs-input:family-additions`) rather than written without it. | `--out` |
-| `icon normalize` | RT-04 | Keys a returned candidate to transparency (or keeps an opaque night tile full-bleed), trims and fits it to the 688 px live area of a 1024 px RGBA PNG, then runs the QA. A failing QA writes nothing (`art-fail:icon-qa`, exit 1). | `--out` (default `assets/icon.png` in the checkout), `--preview` |
-| `icon check` | RT-04 | Automated icon QA: size, byte budget, alpha, live area, coverage, contrast on the card, family inks, not the org glyph, one file. OCR and the 48 px set sheet stay manual. | nothing |
+| `icon normalize` | RT-04 | Keys a returned candidate to transparency (or keeps an opaque night tile full-bleed), trims and fits it to the 688 px live area of a 1024 px RGBA PNG, then runs the QA. A failing QA writes nothing (`art-fail:icon-qa`, exit 1). | `--out` (default `assets/icon.png` in the checkout), `--preview`, `--strict`, `--min-contrast`, `--ocr` |
+| `icon check` | RT-04 | Automated icon QA: size, byte budget, alpha, live area, coverage, contrast on the card (floor set by `--min-contrast`, default 3:1), family inks, not the org glyph, one file. OCR is opt-in with `--ocr`; the 48 px set sheet stays manual. | `--strict`, `--min-contrast`, `--ocr` |
 | `links` | CQ-04, RP-09 | Every relative link, anchor and image target in the displayed README (GitHub's `.github/`, root, `docs/` precedence, or `--readme-path`), `docs/**`, `.github/*.md` and the org profile. With `--base-ref`, only breakage the change introduces fails; `--strict` fails any. `--online` adds cached, polite remote checks (HEAD first, one request per host per `--delay` seconds, at most `--max-remote`) and `gh` `full_name` checks for GitHub links, so a renamed org or repository is proposed under its current name. Offline, a link to this repository under its former slug (a transfer left its badges, release and clone URLs on the old org) is `moved` with a rewrite proposal only when an approved repository `rename` or `transfer` action in `decisions/estate-actions.json` records that exact move (the resolver's `repo_before`, CQ-03); a repository of the same name under another org is a different repository and is never rewritten (every org has its own `.github`). Every URL `references/brand.yaml` holds (the decision 18 footer's href and logo URLs, the brand and hub sites) is fixed content: it is still checked, but no org rename, transfer or online `full_name` answer proposes rewriting it. Rewrites match whole targets, so `…/tests.yml` never half-rewrites `…/tests.yml/badge.svg`. Broken links carry proposals; `--diff` prints them as a unified diff that is never applied. | `--cache` |
 | `linguist` | RP-07, CQ-08 | Paths that distort the language bar (vendored, generated, docs and example trees), the proposed append-only `# ct-std linguist` block for `.gitattributes`, the bar before and after, and the primary language a chip, card dot or badge may show (manifest runtime, then a `language:` override, then the corrected top language). | nothing |
 | `actions` | RP-06, RP-01, CQ-13 | Red runs and README status badges for failing workflows, upstream-only automation in forks (CLA, stale, labeler), and what a README merge would start (deploys first). Workflow on/off changes are proposals that need a `workflow-toggle` approval (`--approval WORKFLOW=ID`, keyed by the workflow file name); the job's argv names the workflow file (`gh workflow disable stale.yml -R OWNER/REPO`), never its numeric id, because the guard matches the approval's `detail` against it. | nothing |
@@ -50,6 +50,12 @@ Each action prints one JSON object (`command: "content"`, `action`, `owner`, `re
 
 None by default. `links --online` and `images --online` make cached, rate-limited HEAD/GET requests to the hosts the files link to and read-only `gh api` GETs; `--cache` is the only state they keep. Local, private-network and `example.*` hosts are allowlisted and never fetched.
 
+`--strict` (on `icon check` and `icon normalize`, also set by the family key `icon_strict_family_ink: true` in `references/brand.yaml`, which is off by default) makes the family-ink check fail instead of warn when the icon's dominant ink is not a family ink. Without the flag it stays a warning and the exit code is unchanged. With no family palette (`icon_ink` and `icon_spark` absent) the family-ink check is not emitted, so `--strict` has no effect there and `needs-input:icon-palette` is still logged.
+
+`--min-contrast` sets the contrast floor of the icon's dominant ink on the card plate (on `icon normalize` and `icon check`). The precedence is the CLI flag, then the family key `icon_min_contrast` in `references/brand.yaml`, then the default 3.0. The default stays 3:1 because a higher floor would change results that already pass. The recommended floor for the card plate is 4.5:1 (WCAG AA body text); set it with `--min-contrast 4.5` or `icon_min_contrast: 4.5` for a family. The valid range is 1 to 21; any other value, or a non-number, is a usage error (exit 2). A failing contrast check fails the icon (exit 1), as the other failing icon checks do.
+
+`--ocr` (on `icon check` and `icon normalize`, off by default) adds an optional text check: when `tesseract` is on `PATH`, the icon is composited on the configured family card colour (card_fill) and read with it, and words of 2 or more alphanumeric characters count as text. Found text warns (`no-text`, detail `OCR found text: ...`) and fails the icon with `--strict`; no text passes. Single characters and punctuation are ignored. Without `--ocr`, or without `tesseract`, nothing changes: `no-text` stays a manual review, and an absent tool logs `needs-input:ocr-unavailable` without changing the result or the exit code (a tool that fails to run logs `needs-input:ocr-failed`). The tool is never installed by this package. An unreadable or undecodable PNG (bad structure, or valid structure with corrupt compressed data) fails the `png` check and returns a `logs` list naming the image (`unreadable-image:<path>`), with and without `--ocr`. On `icon normalize`, an unreadable or undecodable `--in` candidate also fails the `png` check (exit 1, `out` null, nothing written; `logs` names the `--in` source as `unreadable-image:<in path>` plus `art-fail:icon-qa`), while a missing `--in` file stays a usage error (exit 2). The 48 px set sheet stays manual.
+
 ## Without the estate bundle
 
 For an older custom `--config` that omits `icon_ink` or `icon_spark`, normalization