From 6ee9b53aab40de85d1bb6826c04fddf66d092edf Mon Sep 17 00:00:00 2001 From: wshallwshall Date: Tue, 4 Aug 2026 11:04:19 -0500 Subject: [PATCH 1/2] =?UTF-8?q?docs(claude):=20no=20glyphs=20or=20emoji=20?= =?UTF-8?q?in=20prose=20=E2=80=94=20say=20the=20word?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Owner-directed. Words survive grep, copy-paste, a cp1252 terminal and a screen reader; a pictograph does none of those reliably. WHY THIS IS A CORRECTNESS RULE, NOT A STYLE PREFERENCE. A glyph's meaning is POSITIONAL, and that is invisible to anyone who learns it from examples rather than from its definition. Measured 2026-08-04: the backlog's closed-marker means "this item is closed" ONLY in the leading blockquote -- quoted in an item's prose it is narrative. Two parsers of the same file disagreed on exactly that, one asking "does the glyph appear in this item" and the other "does this item declare closed status", and they AGREED ON THE CURRENT CORPUS BY LUCK because no item happens to have the discriminating shape. A word carries its scope in the sentence around it; a bare glyph does not, so it invites presence-equals-meaning reading and hides the ambiguity from review. Secondary but real: emoji need variation-selector handling in every regex that touches them, and raise UnicodeEncodeError on a stock Windows cp1252 console -- four separate failures in one session. ONE HOLDOUT, STATED AS A CONTRACT RATHER THAN AN EXEMPTION. docs/BACKLOG.md and its archive encode item status as a banner alphabet that backlog_status_check.py parses and backlog-hygiene.yml quotes: 283 banners across the two files, 12 referencing files. Changing it is a migration with its own item, not a doc edit. Until then those five glyphs stay, no NEW glyph vocabulary may be introduced anywhere, and nothing outside those two files may adopt one. And the rule that would have prevented the divergence: when reading that alphabet, import parse_items -- never re-derive it. It DEFINES item status (the banner block ends at the first line that is neither blank nor a blockquote), so a hand-rolled scan is a second, silently different definition. Same single-source discipline ledger_check.py already states for PUBLIC_BACKLOG_FLOOR. Recorded honestly: removing glyphs does NOT by itself fix the defect that prompted it. A status marker is distinguishable from a quotation only by position, and `SHIPPED:` in prose is as ambiguous as the glyph was. The parser-single-sourcing above is the fix; the glyph ban is justified on its own merits. NOTE FOR THE MERGE: CLAUDE.md is also edited by PR #177 (a new section 0). This change is in section 11 with a cross-reference in section 12, far from it, but the branch will need a rebase if #177 lands first. --- CLAUDE.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 9498dd91..8a179409 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -459,6 +459,35 @@ harness process only.) ## 11. Documentation +- **NO GLYPHS OR EMOJI — in prose, comments, commit messages, PR bodies, or anything written back to + the user.** Say the word. `SHIPPED`, `BLOCKED`, `WARNING`, `DO NOT` all survive grep, copy-paste, + a cp1252 terminal and a screen reader; a pictograph does none of those reliably. + + **Why this is a correctness rule and not a style preference.** A glyph's meaning is *positional*, and + that is invisible to anyone who learns it from examples rather than from its definition. Measured + 2026-08-04: the backlog's `✅` means "this item is closed" **only** in the leading blockquote — quoted + in an item's prose it is narrative. Two parsers of the same file disagreed on exactly that, one + reading "the glyph appears in this item" and the other "this item declares closed status", and they + **agreed on the current corpus by luck** because no item happens to have the discriminating shape. + Words carry their scope in the sentence around them; a bare glyph does not, so it invites + presence-equals-meaning reading and hides the ambiguity from review. + + Secondary but real: emoji need variation-selector handling (`️`) in every regex that touches + them, and they raise `UnicodeEncodeError` on a stock Windows cp1252 console — which cost four + separate failures in one session. + + ⚠️ **ONE HOLDOUT, and it is a machine-parsed contract, not an exemption.** `docs/BACKLOG.md` and + `docs/archive/backlog/BACKLOG-CLOSED.md` encode item status as a banner alphabet + (`scripts/docs/backlog_status_check.py`: `_CLOSED = "✅⛔🪦"`, `_OPEN = "🔢🚧"`), and + `.github/workflows/backlog-hygiene.yml` quotes it in its remediation text. **283 banners across the + two files and 12 referencing files** — changing it is a migration with its own item, not a doc edit, + and until it lands those five glyphs stay. **No NEW glyph vocabulary may be introduced anywhere**, + and nothing outside those two files may adopt one. + + **When you must read that alphabet, import `parse_items` from `backlog_status_check.py`. Never + re-derive it.** It *defines* item status — the banner block ends at the first line that is neither + blank nor a blockquote — and a hand-rolled scan is a second, silently different definition. That is + the same single-source rule `ledger_check.py` already states for `PUBLIC_BACKLOG_FLOOR`. - Specs/requirements in **Markdown**, kept consistent across the project. - Document each connector/transport and transform with its config schema and an example message. @@ -518,3 +547,7 @@ harness process only.) **declined-by-design (v0.2+)**: no real feed demand, outside the HL7/FHIR/X12/DICOM scope ([`docs/BACKLOG.md`](docs/BACKLOG.md) #27, [`docs/CONNECTIONS.md`](docs/CONNECTIONS.md)). - Don't keep grinding in a polluted context — `/clear` after repeated failures. +- Don't use **glyphs or emoji** in prose, comments, commit messages, PR bodies or replies — say the + word (§11). The backlog status-banner alphabet is the one machine-parsed holdout; read it with + `parse_items`, never a hand-rolled scan, and introduce no new glyph vocabulary anywhere. + From 6294a31a9d36d309ae8c7ec5afec6c09bf5d2866 Mon Sep 17 00:00:00 2001 From: wshallwshall Date: Tue, 4 Aug 2026 11:24:51 -0500 Subject: [PATCH 2/2] docs(claude): no glyphs or emoji in prose, and sweep section 0 in the same change Owner-directed. Words survive grep, copy-paste, a cp1252 terminal and a screen reader; a pictograph does none of those reliably. Rebased onto main after #177. SWEEPING SECTION 0 HERE IS THE POINT, NOT AN EXTRA. #177 added CLAUDE.md section 0 (the not-deployed context) carrying two prose glyphs. This branch predated it, so it would have merged cleanly on distance and left the file self-contradictory: section 11 banning prose glyphs while section 0 used them, introduced by the very commit that bans them. The coordinator caught it and offered to fix it themselves; it belongs here, in the de-glyphing commit, rather than as an unexplained edit in an unrelated PR -- and this branch is docs-only at roughly 2 minutes per CI cycle against their 31. AND THE RULE CAUGHT ME WRITING IT. My own text used a warning glyph to mark the holdout paragraph. Removed. A style rule whose statement violates itself teaches the exception, not the rule. WHY THIS IS A CORRECTNESS RULE, NOT STYLE. A glyph's meaning is POSITIONAL, and that is invisible to anyone who learns it from examples rather than its definition. The backlog's closed marker means "this item is closed" ONLY in the leading blockquote; quoted in an item's prose it is narrative. Two parsers of the same file disagreed on exactly that and AGREED ON THE CURRENT CORPUS BY LUCK, because no item has the discriminating shape. A reviewer's hand-rolled checker did worse: three different wrong answers in one session, the last confidently reporting three open items as closed. The glyph looked like status wherever it appeared. Corroboration, independent of the argument: four cp1252 encode failures in one session, every one on an emoji, twice inside census checkers where the crash cost the measurement. ONE ALLOWED USE, stated explicitly because leaving it implicit would reproduce the ambiguity this rule exists to remove: quoting a glyph as a token, in backticks, to name the thing under discussion. That is code, not decoration. ONE HOLDOUT, written as a contract rather than an exemption: the backlog status-banner alphabet is machine-parsed -- 283 banners across two ledger files, 12 referencing files, and backlog-hygiene.yml quotes it in its remediation text. Changing it is a migration with its own item. Until then those five glyphs stay, no NEW glyph vocabulary anywhere, and nothing outside those two files may adopt one. Recorded honestly: banning glyphs does NOT fix the parser defect that prompted it. "SHIPPED:" in prose is as ambiguous as the glyph was. The parse_items single-sourcing guard is the fix; this stands on its own merits. Two independent changes that happened to arrive together. --- CLAUDE.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8a179409..2923f414 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -16,7 +16,7 @@ stops matching the code, fix the doc. ## 0. Deployment status — read this before writing any severity claim -> ⛔ **MessageFoundry is a NOT-DEPLOYED beta. There are ZERO production instances. Nobody is +> **CRITICAL — MessageFoundry is a NOT-DEPLOYED beta. There are ZERO production instances. Nobody is > running it.** **Published to PyPI is *not* deployed** — a release artifact on an index is not a > running instance, and the two get conflated constantly. Distinguish **shipped** (on `main`, on > PyPI), **deployable**, and **deployed**: only the first two are true today. @@ -38,7 +38,7 @@ across the repo. **Two consequences, and they pull in opposite directions — ap of a breaking change is currently **zero**. Prefer the simple, correct end state over a staged migration or compatibility shim; those are real costs paid to protect users who do not exist. -⛔ **It cuts one way only — never cite "not deployed" to relax a rule.** It removes false urgency +**IT CUTS ONE WAY ONLY — never cite "not deployed" to relax a rule.** It removes false urgency and vacuous costs. It does **not** downgrade a fix, justify skipping a gate, weaken a control, or make a finding unimportant. The security, PHI (§9) and leak-gate rules exist so the **first** deployment is safe; zero deployments is why there is still time to get them right, not permission @@ -463,6 +463,10 @@ harness process only.) the user.** Say the word. `SHIPPED`, `BLOCKED`, `WARNING`, `DO NOT` all survive grep, copy-paste, a cp1252 terminal and a screen reader; a pictograph does none of those reliably. + **The one allowed use is QUOTING a glyph as a token, in backticks** — naming the thing under + discussion, as this rule does below. That is code, not decoration, and it is how you talk about the + banner alphabet without adopting it. + **Why this is a correctness rule and not a style preference.** A glyph's meaning is *positional*, and that is invisible to anyone who learns it from examples rather than from its definition. Measured 2026-08-04: the backlog's `✅` means "this item is closed" **only** in the leading blockquote — quoted @@ -476,7 +480,7 @@ harness process only.) them, and they raise `UnicodeEncodeError` on a stock Windows cp1252 console — which cost four separate failures in one session. - ⚠️ **ONE HOLDOUT, and it is a machine-parsed contract, not an exemption.** `docs/BACKLOG.md` and + **ONE HOLDOUT, and it is a machine-parsed contract, not an exemption.** `docs/BACKLOG.md` and `docs/archive/backlog/BACKLOG-CLOSED.md` encode item status as a banner alphabet (`scripts/docs/backlog_status_check.py`: `_CLOSED = "✅⛔🪦"`, `_OPEN = "🔢🚧"`), and `.github/workflows/backlog-hygiene.yml` quotes it in its remediation text. **283 banners across the