Skip to content

πŸ“– docs: README copy in plain speech, cards as crisp PNGs with embedded font - #14788

Merged
clubanderson merged 5 commits into
v5from
docs/readme-text-numbers
Oct 29, 2026
Merged

clubanderson merged 5 commits into
v5from
docs/readme-text-numbers

Conversation

@clubanderson

@clubanderson clubanderson commented Oct 28, 2026 •

Copy link
Copy Markdown
Member

Fixes #14786.

Rebased onto v5 after #15100. The footer keeps the CNCF sandbox project wording and Code of Conduct link, in plain speech, inside the 300 word budget.

What changed

Copy. The README prose and every card headline, side note and footnote are rewritten as short full sentences in plain speech: one idea each, second person, numbers inside the sentence, no semicolons, no "Numbers below:" labels. The section sentences are generated from the report so they stay in step with the cards. Sections are Accuracy, Security, Cost, And the rest. TestReadmeVocabulary now rejects semicolons and label lines in the README prose and in the card text. Prose is 299 words of the 300 budget, 7 H2.

Cards. The outcome cards are crisp 2Γ— PNGs rendered in Go with an embedded OFL mono face (IBM Plex Mono, pkg/outcomebench/fonts/), instead of SVGs that GitHub rendered in whatever monospace the reader's machine had. Each card is drawn once from an op list into both an SVG (vector source) and a PNG (what the README embeds). The PNG carries the SHA-256 of its SVG twin in a tEXt chunk and the drift test checks that hash plus dimensions, so the test is tool-independent and stable across amd64/arm64.

  • flat amber figures, no glow or gradient
  • bold 28 px headline sentence is the largest text, 48 px padding
  • one figure per stat card (2 in 3 Β· 97% Β· $2) with the remaining numbers in a muted side column
  • the three stat cards share one fixed height; "And the rest" is four tiles in the order consistency / readability / efficiency / speed
  • light and dark variants

Pipeline. hivectl evidence benchmark --from-json <report> re-renders cards from the committed report without the evidence tree; scripts/outcome-benchmark.sh --rerender --readme wraps it. The <!-- outcomes:start/end --> block is regenerated and byte-idempotent.

README prose (verbatim)

You know the one. Reads every pull request. Never lets red merge. Sends it back with one line, and the line is right. Hive puts that person between your coding agents and main.

If you run CI you know the shape. The job is an AI coding agent. The gate is an AI review plus your own CI.

Everything below comes from 11,571 live pull requests in 10 repositories and 15,054 reviews (oct '26).

Accuracy β€” The review agent sent 563 pull requests back. Two out of three came back fixed and approved, usually within 24 minutes.

Security β€” We planted 63 texts that try to redirect an agent in issues and files. Hive caught 61 before an agent read a word. One harmless text in 12 got flagged by mistake. Agents run as a GitHub App, not on your token.

Cost β€” Agents spent about $6,125 to merge 2,869 pull requests. Call it $2 a merge, our estimate (aug–oct '26).

And the rest β€” Every pull request gets the same one-line review, in your style guide's voice. It adds about 15 minutes to a merge.

Humans still merge. Start with "open PRs only". When you trust it, turn it up and it merges on green, like a merge queue that reads the code.

Reverts are too new to report. How we count β†’

Run it β€” The quick start explains each line. Podman and Kubernetes too.

That maintainer now reads every repo. Only run images from ghcr.io/hivecommons/hive. Anything else is not ours.

Before / after / reference (same width)

Dark:

before, after and reference cards side by side, dark

Light (the reference has no light variant and is shown dark):

before, after and reference cards side by side, light

Full page, dark, 1280 wide:

before, after and reference full README pages, dark

Verification

  • go test ./pkg/outcomebench/ ./pkg/hivectl/commands/ β€” pass (incl. TestReadmeProseBudget, TestReadmeVocabulary, TestCommittedReportMatchesReadme, TestCardPNGs, TestPNGTextRoundTrip)
  • bash scripts/outcome-benchmark.sh --rerender --readme twice β€” identical output
  • Rendered this branch's README on github.com at 1280/1600, light and dark. The embedded face and line breaks match the local render.

@kubestellar-prow kubestellar-prow Bot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Oct 28, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign kellyaa for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubestellar-prow kubestellar-prow Bot added dco-signoff: yes Indicates the PR's author has signed the DCO. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. labels Oct 28, 2026
@github-actions

github-actions Bot commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

No conflicting open PRs or same-file overlaps were found.

@hivecommons-hive hivecommons-hive Bot added the author/human A person pushed this PR themselves label Oct 28, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor
00f2b9e

ℹ️ Sentinel notice β€” informational; author is trusted (owner), merge is not blocked

Hive flagged this PR (author @clubanderson, head 00f2b9ed97f9) because it matches behaviors that can override security controls, escalate privileges or damage the codebase. This is a heuristic, not an accusation β€” a maintainer should confirm the change is intended before it merges.

  • sensitive_path β€” changes 1 sensitive path(s) (Touches a sensitive path (OWNERS, workflows, policies, hive config, security docs, …))
    • src/go.mod

Hive did not add the sentinel-alert label because this author is trusted. The finding remains recorded for audit and the dashboard Security tab; set sentinel.trusted_authors_block: true to require the blocking label for trusted authors too.

@github-actions github-actions Bot added the conflicts-with-open-pr Open PR has a merge conflict with another open PR label Oct 28, 2026
@clubanderson clubanderson changed the title πŸ“– docs: README outcome cards as crisp PNGs with embedded font πŸ“– docs: README copy in plain speech, cards as crisp PNGs with embedded font Oct 28, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor
800775e

ℹ️ Sentinel notice β€” informational; author is trusted (owner), merge is not blocked

Hive flagged this PR (author @clubanderson, head 800775e671a7) because it matches behaviors that can override security controls, escalate privileges or damage the codebase. This is a heuristic, not an accusation β€” a maintainer should confirm the change is intended before it merges.

  • sensitive_path β€” changes 1 sensitive path(s) (Touches a sensitive path (OWNERS, workflows, policies, hive config, security docs, …))
    • src/go.mod

Hive did not add the sentinel-alert label because this author is trusted. The finding remains recorded for audit and the dashboard Security tab; set sentinel.trusted_authors_block: true to require the blocking label for trusted authors too.

@hivecommons-hive

Copy link
Copy Markdown
Contributor
a9f0cfb

ℹ️ Sentinel notice β€” informational; author is trusted (owner), merge is not blocked

Hive flagged this PR (author @clubanderson, head a9f0cfb7d637) because it matches behaviors that can override security controls, escalate privileges or damage the codebase. This is a heuristic, not an accusation β€” a maintainer should confirm the change is intended before it merges.

  • sensitive_path β€” changes 1 sensitive path(s) (Touches a sensitive path (OWNERS, workflows, policies, hive config, security docs, …))
    • src/go.mod

Hive did not add the sentinel-alert label because this author is trusted. The finding remains recorded for audit and the dashboard Security tab; set sentinel.trusted_authors_block: true to require the blocking label for trusted authors too.

Draw every README card twice from one op list: the SVG (vector source)
and a 2x PNG rasterised in Go with embedded IBM Plex Mono (OFL), so the
cards no longer depend on the reader's monospace fallback or on browser
filter support. Flat amber, no gradient or glow; more whitespace; the
three stat cards share one height and show one figure each, with the
rest of the picture in a side column. The README <picture> now embeds
the PNGs. Each PNG carries the SHA-256 of its SVG in a tEXt chunk and the
drift test checks that hash plus dimensions instead of pixels.

Add hivectl evidence benchmark --from-json and outcome-benchmark.sh
--rerender to redraw the committed assets and README block from the
committed outcomes JSON without the evidence tree.

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
Rewrite the README prose and every card headline, side note and
footnote as short full sentences a person would say: one idea each,
numbers inside the sentence, no semicolons, no label lines. The
section sentences are generated from the report so they stay in step
with the cards. Headings are Accuracy, Security, Cost, And the rest.

TestReadmeVocabulary now rejects semicolons and "Numbers below:"
style labels in the README prose and in the card text. Prose is 299
words of the 300 budget.

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
Signed-off-by: Andrew Anderson <andy@clubanderson.com>
Keep the CNCF sandbox project wording and Code of Conduct link from #15100,
drop the semicolons, and stay inside the 300 word prose budget.

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
@clubanderson
clubanderson force-pushed the docs/readme-text-numbers branch from a9f0cfb to f7fc76c Compare October 29, 2026 01:30
@clubanderson
clubanderson marked this pull request as ready for review October 29, 2026 01:30
@kubestellar-prow kubestellar-prow Bot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Oct 29, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor

@clubanderson is auto-promoted for contributor-lane merging on this PR: the last 5 merged PRs by this author in this hive's repositories have no revert or sentinel-alert evidence. CI, reviewer verdict, diff fences, soak, holds and branch protection still apply.

@hivecommons-hive hivecommons-hive Bot added dco All commits are DCO signed-off role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Oct 29, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor
f7fc76c

ℹ️ Sentinel notice β€” informational; author is trusted (owner), merge is not blocked

Hive flagged this PR (author @clubanderson, head f7fc76c4397b) because it matches behaviors that can override security controls, escalate privileges or damage the codebase. This is a heuristic, not an accusation β€” a maintainer should confirm the change is intended before it merges.

  • sensitive_path β€” changes 1 sensitive path(s) (Touches a sensitive path (OWNERS, workflows, policies, hive config, security docs, …))
    • src/go.mod

Hive did not add the sentinel-alert label because this author is trusted. The finding remains recorded for audit and the dashboard Security tab; set sentinel.trusted_authors_block: true to require the blocking label for trusted authors too.

@clubanderson
clubanderson merged commit cbeb63d into v5 Oct 29, 2026
74 of 75 checks passed
@kubestellar-prow
kubestellar-prow Bot deleted the docs/readme-text-numbers branch October 29, 2026 02:02
@github-actions

Copy link
Copy Markdown
Contributor

Thank you for your contribution! Your PR has been merged.

We'd love to hear how your experience was: share feedback

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed β€” no findings from this perspective.

β€” hive: agent=adjudicator-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Style review (head 0971a6f) β€” three findings, worst first.

1. README prose and card wording are copy-pasted, not shared (medium). The body says the section sentences "stay in step with the cards", but nothing enforces it: the same strings are built twice by hand.

  • false-alarm sentence: cards.go:589-591 and readme.go:119-121
  • per-merge figure ($%.0f / %dΒ’): cards.go:607-609, cards.go:685-687, readme.go:131-133
  • accuracy sentence: cards.go:548-555 vs readme.go:100-112

TestReadmeBlockRoundTrip checks literals, not equality with the card, so editing one copy silently splits the README prose from the card headline. Suggested shape:

--- a/src/pkg/outcomebench/readme.go
+++ b/src/pkg/outcomebench/readme.go
+// perMergeFigure is the one cost figure every surface shows: "$2" or "40Β’".
+func perMergeFigure(per float64) string {
+	if per < 1 {
+		return fmt.Sprintf("%dΒ’", int(math.Round(per*100)))
+	}
+	return fmt.Sprintf("$%.0f", per)
+}
+
+// falseAlarmSentence is the benign-text sentence shared by the card and the prose.
+func falseAlarmSentence(rt *RedTeam) string {
+	if rt.FalseAlarms == 1 {
+		return fmt.Sprintf("One harmless text in %d got flagged by mistake.", rt.Benign)
+	}
+	return fmt.Sprintf("%d harmless texts in %d got flagged by mistake.", rt.FalseAlarms, rt.Benign)
+}

then accuracyCard takes head, _ := r.accuracySentences(), and costCard/alsoTiles/costSentences/promptInjectionCard call the helpers.

2. Stranded comment in readme_budget_test.go:106-111 (low). The new readmeLabelLine was inserted between the "Dates in the README and cards are …" comment and readmeForbiddenDates, so that comment now sits on the wrong var.

// A prose line that is one or two words followed by a colon is a label, not
// a sentence ("Numbers below:"). Headings and link rows are exempt because
// they have no colon.
var readmeLabelLine = regexp.MustCompile(`^\s*[a-z][a-z' -]{0,24}:\s`)

// Dates in the README and cards are "(oct '26)" or "(aug–oct '26)"; never
// ISO dates or bare four-digit years.
var readmeForbiddenDates = []*regexp.Regexp{

3. Two small drifts from the PNG-of-record change (low).

  • cards.go:403 documents an 'r' rect op kind, but no op emits it and neither SVG() (cards.go:487-507) nor PNG() (raster.go:97-110) handles it. Drop it from the comment.
  • cards.go:665 one-story footnote says "The right column links to the pull request", but the README now embeds the PNG (readme.go:157-158) and PNG() skips 'a' ops, so for README readers no link exists. Latent today (the committed report has two stories, which take the other branch), but the sentence should go: foot := "Times from Hive's review records."

β€” hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed β€” no findings from this perspective.

β€” hive: agent=adjudicator backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Hive filed review findings that do not block this PR as backlog items:

Cap: 10 backlog item(s) per PR per day.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

author/human A person pushed this PR themselves dco All commits are DCO signed-off dco-signoff: yes Indicates the PR's author has signed the DCO. role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. stage/050-review-pending Review swarm requested; awaiting a verdict for the current head

Projects

None yet

Development

Successfully merging this pull request may close these issues.

README: outcome cards render with fallback fonts and glow; rasterize to PNG

1 participant