fix(#18): use the selected Open Herd icon-only avatar

[PeterGuy326]

Tracking record

Refs #18, consumed revision R2 — Open Herd icon only, explicitly selected by the owner on 2026-09-09. Decision and verified live correction.

Summary

The owner selected the Open Herd icon without its wordmark, but the canonical README and export script still pointed to the superseded black horned B. Following those stale instructions caused an incorrect live restoration. This change makes the selected icon the canonical avatar source and export, and marks the old B variants as historical.

The original Open Herd SVG is preserved byte-for-byte alongside its existing icon-only equivalent. The export scales proportionally onto an opaque white 1024×1024 canvas. Validation checks source identity, all nine shape attributes and original colors, absence of text in the icon, the approved PNG, and crop padding. The current live avatar already uses this exact PNG; organization settings were corrected separately under the owner's direct instruction.

Acceptance criteria and validation ledger

Requirement / criterion	Implementation and evidence
R2 REQ-001 / AC-001	Original source and icon-only SVG; all 4 paths and 5 rectangles match after resolving fill variables; no text in the icon
R2 REQ-002–003 / AC-002	Original blue/purple/ink/white palette, proportional scaling and white padding; 1024×1024 RGB PNG, SHA-256 aefe9f3494bff30ff93809f929b04f709f5f36eedbfabdb5f5764efe78578461
R2 REQ-004 / AC-003	README names Open Herd as current, old B as historical; export and validator agree. Commands below passed on candidate head 94766dca09dcc30c1bbbe0fd0f788a1a48866fdd
R2 REQ-003–004 / AC-004–005	Already verified through owner UI and public readback; exact evidence. Protected public fields unchanged

Reproduce

Environment: macOS arm64, Ruby 2.6.10, ImageMagick 7.1.2-22, Git. From the repository root:

ruby scripts/validate-governance.rb
ruby scripts/validate-brand-assets.rb
brand/bytefolk/render-avatar.sh --check
git diff --check origin/main...HEAD

Expected: every command exits 0; source geometry and colors match, no text is present in the icon, the tracked PNG matches a fresh proportional render, and circular crop safety passes. CI runs the repository's existing Governance workflow. Renderer versions may differ in antialiasing or PNG encoding; the documented version reproduces the exact tracked artifact.

Tests and coverage

The existing brand validator is extended to reject the superseded avatar and mismatched source/icon geometry or colors. This is an asset and reproduction-instruction correction; there is no runtime code or coverage metric. The source PNG and public avatar were both visually inspected. GitHub serves a resized/re-encoded 460px derivative and keeps the same avatar URL, so byte or pixel equality between source and live derivative is not claimed. CI does not monitor the remote avatar endpoint.

No software CHANGELOG exists in this organization-profile repository; #18 R2 and this PR record the visible correction. Historical R1 SVGs remain unchanged.

Change classification

• User-visible behavior
• Documentation and asset reproduction/validation
• Breaking change

Risk and rollback

Low risk, limited to organization brand assets. No dependencies, workflow, permissions, profile copy, or product behavior changes. Fix repository regressions with a reviewed follow-up PR. Do not restore the old black B under R1: the owner's R2 selection supersedes it. Any live rollback must respect the latest owner-selected source and avoid overwriting a concurrent update.

Breaking or security notes

None. SVG script/external-resource checks are retained. No credentials, private data, or settings screenshots are included. Codex assisted with implementation and independent preflight; human approval remains a separate merge gate.

Reviewer notes

Verify the icon against the original open-herd-mark group, check the export remains proportional and text-free, and confirm the old black B PNG is rejected. Independent automated preflight passed on head 94766dca09dcc30c1bbbe0fd0f788a1a48866fdd, including temporary negative cases for the old black B, added text, script, and external resource. Required Governance CI passed in check suite 92935256827 on that same head. Human CODEOWNER approval is still pending.

[PeterGuy326]

Independent preflight — PASS

Candidate head: 94766dca09dcc30c1bbbe0fd0f788a1a48866fdd.
Base: 7aa4a5b65d43fd77b6cd61b0f587911ffcf0d1aa.

An independent automated reviewer inspected the complete six-file diff after implementation stopped and reran the following:

• Source SVG and repository copy: byte-for-byte match.
• Independent XML comparison: 4 paths, 5 rectangles, original 4 colors, no wordmark/text in the icon.
• Visual PNG inspection: correct Open Herd icon, proportional scale, opaque white padding.
• ruby scripts/validate-governance.rb: PASS.
• ruby scripts/validate-brand-assets.rb: PASS; 5 SVGs, opaque 1024×1024 RGB, 0 pixels outside the safe circle; max ink radius 453.3px.
• brand/bytefolk/render-avatar.sh --check: PASS, byte equality.
• git diff --check origin/main...HEAD: PASS.
• Independent temporary negative cases: the old black B PNG, added text, script, and external-resource attribute were all rejected. The candidate tree remained clean.
• No unrelated edits or sensitive content found; commit email is GitHub noreply.

No blocking findings. This is automated PREFLIGHT PASS, not a human GitHub approval. Required CI and the repository's independent CODEOWNER approval remain separate merge gates.

The remote commit equals the reviewed local commit exactly. Standard git push exited 128 without diagnostic output in this environment, so the six identical blobs, identical tree, and identical commit were published through the authenticated GitHub Git-data API to a newly created feature ref. No existing ref was overwritten; main was not changed.

[waterbro-8]

Approved. Not a merge request, not an auto-merge change, not a close of #18, and no label or assignee is implied by this ticket.

Reviewed object: head 94766dca09dcc30c1bbbe0fd0f788a1a48866fdd (base = main tip 7aa4a5b65d43fd77b6cd61b0f587911ffcf0d1aa, ahead 1 / behind 0, 6 files +136/−39). All six files were fetched individually from that exact head and their blob SHAs re-checked against git hash-object on my copies before measuring anything, so every number below is a reading of the bytes this PR proposes, not of a working copy.

What I checked, and how

I have no ruby and no ImageMagick locally, and installing either is out of scope on this machine. So instead of running scripts/validate-brand-assets.rb, I re-implemented its assertions independently in Python — a from-scratch PNG decoder (IHDR parse, zlib IDAT inflate, per-row Unzip of filters 0–4 including Paeth) over the tracked avatar-1024.png, and an XML comparison over both SVGs. Then I compared my results against the CI job log for this head.

The CI run of ruby scripts/validate-brand-assets.rb on 94766dca09 printed Validated 5 ByteFolk SVGs and one opaque 1024x1024 RGB avatar. and Circular crop: outside-circle ink=0; center=(511.5,511.5); safe radius=496.0px; max ink radius=453.3px. — my independent decode gives the same 453.3 / 496.0 / 0. Two independent implementations agreeing on the same crop numbers is the reason I treat the rest of my measurements as trustworthy, and it also confirms CI exercised the new code rather than an inherited path.

My decode of avatar-1024.png (15097 B, blob a023ee161de8f71b3d2b43e8350f0060da117a57): 1024×1024, 8-bit, color type 2, non-interlaced, 572 unique colors; all four palette colors present as flat fields — #ffffff 759,986 px, #1677ff 155,251 px, #722ed1 62,343 px, #141414 59,902 px; ink bounding box x 137..874 / y 194..829, so margins [137, 194, 149, 194], all ≥ the 100 px floor at :208-211.

The validator's rule change is necessary, not cosmetic. That PNG contains 226,483 non-gray pixels. The requirement this PR removes (red == green && blue, plus darkest == 20) would reject the shipped artifact on the first channel comparison. The palette check at :204-207 and the ink test at :191 (next if [red,green,blue].min >= INK_THRESHOLD) are what replace it, and they are what the numbers above actually satisfy.

Geometry parity (:102-104) reproduced: the mark and the source's #open-herd-mark group each have 9 children (4 <path> + 5 <rect>), and running the validator's own normalize() semantics (:92-99: expand var(--bf-*), #fff→#ffffff, compare [name, sorted attrs, child count]) gives equal. The mark has 0 <text>, 0 <style>, 0 elements from PROHIBITED_ELEMENTS, and 0 external or executable attribute values; its root attributes are exactly xmlns, viewBox="0 0 142 116", role, aria-label.

Cross-check on identity: three separate sources pin the same bytes and all three agree with the files — #18's Source identity icon-only SHA-256 f7d58df169d6270ff40da11b038d64d6f7c5f7435851eb32f2fe1554c578f32a, this PR's SOURCE_SHA256 160c6f108e25d5f6d2a06ae68bd3cc11715f4580c0a0d9d02060d016a4526e49, and AVATAR_SHA256 aefe9f3494bff30ff93809f929b04f709f5f36eedbfabdb5f5764efe78578461. I computed all three from the head files with sha256sum.

The claim #18's AC-004 leaves open — GitHub's served pixels — I closed. GET /orgs/bytefolk gives id 309981672; https://avatars.githubusercontent.com/u/309981672?v=4 returns HTTP 200, 5563 bytes, SHA-256 86b69ad8314961d2ce5270878a36b3cee6ef672241c4ee9cf313d9a01af9552b, byte-identical to the readback recorded on #18. Decoding it: 460×460 RGB, 21.8 % non-gray, #1677ff / #722ed1 / #141414 present at exact values, color proportions within 0.2 pp of the tracked export, ink margins [61, 87, 66, 87] against [61.5, 87.1, 66.9, 87.1] predicted by scaling this 1024 file down, ink bbox 333×286 against 331.5×285.7 predicted. The live avatar is a faithful downscale of this exact tracked, icon-only export — which is the last thing either the README or the issue said was unverified.

On the README (brand/bytefolk/README.md, blob 437b0e2808f277db5cb686a6c5d141b9c482a7b7): the one new relative destination, bytefolk-concept-c-open-herd.svg at line 6, is filesystem-checked — scripts/validate-governance.rb:328-329 skips only empty / # / / / // and scheme-bearing destinations, and :341-347 expands a relative target against the Markdown file's own directory and asserts existence. The target resolves to brand/bytefolk/bytefolk-concept-c-open-herd.svg, present at this head (1732 B, blob 6e4e928212ca6575584de66e2555578efdf0f700). Worth stating explicitly because it is not the usual outcome here: the last time I audited a README in this organization, its link check validated zero of thirty destinations.

R2 acceptance criteria, as this head stands

• AC-001 — ✅ verified above at execution level (9/9 elements equal after var() expansion; no text node).
• AC-002 — ✅ verified above, by independent decode rather than by the repo's own validator.
• AC-003 — partial. Source, artifact, docs and validation provably agree on Open Herd; Governance is completed / success on this exact head. The "render command" leg is not CI-covered — see the first gap below.
• AC-004 — ✅ for the download-and-inspect half, done here. The owner-settings UI confirmation is the owner's own record, not something I can observe.
• AC-005 — not mine to establish: I cannot enumerate the before values of protected organization fields, so "no unrelated field changed" is not something I verified. #18 remaining open is consistent with this criterion as written.

Three gaps I'd like recorded — none of them a reason to hold this PR

1. No workflow anywhere runs render-avatar.sh --check. .github/workflows/ contains only validate.yml, and grepping it for render-avatar / magick returns nothing. CI therefore pins the PNG by hash but never proves the PNG is derivable from the SVG: a hand-edited raster plus an updated AVATAR_SHA256 passes for as long as the pixel properties hold. Byte-for-byte export reproducibility is currently a manual gate backed by a manual claim. A follow-up that runs --check on a runner with ImageMagick would make the reproducibility statement an enforced one; the command -v magick || exit 1 guard means it would also be honest on runners that lack it.
2. <text> is not in PROHIBITED_ELEMENTS. The "without text" guarantee is carried entirely by geometry equality — which does hold, and holds for a strong reason (a <text> node changes the child count and breaks :102-104). I note it only because the error message reads as if a text element were explicitly forbidden, so a future reader may over-trust the mechanism.
3. The external-reference scan inspects attribute values, not <style> text content. Bounded in practice today: the only file in this PR carrying a <style> block is bytefolk-concept-c-open-herd.svg, which is SHA-pinned, and adding a <style> to the mark would break geometry parity. Named so that the bound stays visible if the source ever stops being pinned.

What I did not verify

scripts/validate-governance.rb and scripts/validate-brand-assets.rb were not executed locally (no ruby); where I needed their verdicts I used this head's CI job log, and everything else above is my own Python re-derivation, labelled as such. render-avatar.sh — including its --check mode — was never run by anything: no magick here, and no CI job that calls it. AC-005's protected-field comparison and AC-004's owner-settings UI are the owner's evidence, not mine.

No action taken beyond this review: no merge, no close, no label or assignee change, no "Update branch", no auto-merge touched. Merging remains the maintainers' call.