--- name: utf8-write-safety description: HARD MACHINE CONSTRAINT — never write non-ASCII files via PowerShell on this machine (it double-encodes); use UTF-8-safe writes; the gate guards mojibake metadata: node_type: memory originSessionId: 0b7c5f41-bb34-4ab4-93be-fdb363f5eb40 --- ROOT-CAUSE RULE (bug hit 2026-06-29, owner directed prevention): NEVER write a file containing non-ASCII characters via PowerShell on this machine. PowerShell's default Latin-1 read + UTF-8 write DOUBLE-ENCODES the bytes — it silently corrupts em-dashes (— → â€"), arrows (→ → â†'), box-drawing (▲ → â–²), and emoji (⚠ → âš , 🛑 → ðŸ›'). **THE INCIDENT:** this silently corrupted an entire source file (`js/api.js`) end-to-end and the corruption was *shipped* before anyone noticed — the file looked fine in the diff at a glance. That is why the rule is absolute rather than a preference: the failure is invisible at write time. **The app is FULL of non-ASCII** (⚙ ▶ ▲ ▼ ░▒▓, box-drawing ── │, [████] limb bars, æ/¡ in data, em-dashes/arrows in the system directive) — so this is a constant risk. **How to apply (in every build dispatch + my own edits):** - For ANY file with non-ASCII, use UTF-8-safe writes: the Edit tool, or Node `fs.writeFileSync(path, content, 'utf8')` / `git show <ref>:<file> | node` pipes. NEVER PowerShell `Set-Content`/`Out-File`/`WriteAllText`-with-wrong-encoding for non-ASCII content. - ENFORCEMENT (in place): a gate suite in both runners fails the build if any tracked source file contains U+FFFD (�) or the `â€`/`â–` double-encoding mojibake patterns. This is the [[self-improving-code]] pattern applied — the class was closed with a guard, not just fixed. For the suite's identity and current state, see `rules/`. *Corrected 2026-07-20: removed the hardcoded suite number, the protocol number, and the suite-numbering to-do — all derivable from `rules/`. The constraint and the incident stand unchanged.*