From 10055787f344efccea096bbb151ba8b5b86d78a3 Mon Sep 17 00:00:00 2001 From: mhodzic93 Date: Mon, 10 Aug 2026 05:55:53 -0700 Subject: [PATCH] docs: sync EXTERNAL-VOICE.md with the entity-dash rule Our own PR reviewer caught an `—` rendering as a visible em-dash on the Runners pricing page while the guard passed clean, because the entity is seven ASCII bytes and nothing was looking for it. The canonical doc now bans the entity forms explicitly and explains the second reason they are worse than the literal character: inside a multi-line JSX text run an entity makes the transform drop the space after an adjacent expression. The doc also now states the known gap plainly, that the in-product dashboard copy in web-client is in scope but not yet swept, so a green guard is not read as the whole product being clean. Doc-only, and identical to the copies in the other three repos. No entity dashes exist in this repo; this keeps the four copies from drifting. Co-Authored-By: Claude Opus 5 (1M context) --- EXTERNAL-VOICE.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/EXTERNAL-VOICE.md b/EXTERNAL-VOICE.md index cf57205..d9b1b6e 100644 --- a/EXTERNAL-VOICE.md +++ b/EXTERNAL-VOICE.md @@ -36,6 +36,13 @@ it reads as a find-and-replace job rather than a rewrite. significant spaces get trimmed by a formatter, which silently inverts what the rule says.) +And no HTML entity dashes: `—`, `—`, `—`, or a spaced +`–`. They render as exactly the characters above, but they are plain ASCII +in source, so a search for the character does not find them. In JSX they are +worse than a rendering nit: an entity inside a multi-line text run makes the +transform drop the space after an adjacent expression, which has already shipped +`vs the 30before` to production once. + ## How to rewrite, by job An em-dash does at least five different jobs. Each has its own correct fix. @@ -90,3 +97,13 @@ model swaps in a spaced hyphen and you have gained nothing. Anything not in that table is on the author. The guards exempt this file, since it necessarily quotes the character it bans, and they exempt fenced code blocks, because a dash inside sample output belongs to the code and not to our voice. + +### Known gap + +`web-client/src/app/organizations/**` is in scope by this document and is NOT +yet swept: roughly 90 literal em-dashes remain in the in-product dashboard copy. +The guard covers marketing, the explainer prompts, and the invitation emails, +and it bans entity dashes across all of `src`, so the untouched copy cannot get +worse in the way that is hardest to see. Sweeping the dashboard tree is +follow-up work, deliberately not folded into the PR that installed the rule. +Do not read the guard passing as the whole product being clean.