From caf40afc01b421824b3eb408ea4675ac53b441c0 Mon Sep 17 00:00:00 2001 From: Jarvis Date: Thu, 30 Jul 2026 15:24:17 -0500 Subject: [PATCH] fix(framework): ride the existing communicationStyle enum, drop the no-op USER.md edit (mos-dt review #960) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit F1: defaults/USER.md is never installed (generated from templates/USER.md.template via buildCommunicationPrefs). Editing it was a no-op asserting a phantom setting — exactly the false-green §2 warns against. Reverted. F2: the framework already has communicationStyle (direct|friendly|formal). §5 now maps THOSE values to output instead of inventing technical|prose|brief (rule 9). Minor: §6 states no mechanical prose check exists today; rule 1 points at §3.4. Written-by: jarvis (dragon-lin) Co-Authored-By: Claude Fable 5 --- .../mosaic/framework/defaults/STANDARDS.md | 2 +- packages/mosaic/framework/defaults/USER.md | 12 ------- .../mosaic/framework/guides/WRITING-STYLE.md | 36 ++++++++++++------- 3 files changed, 25 insertions(+), 25 deletions(-) diff --git a/packages/mosaic/framework/defaults/STANDARDS.md b/packages/mosaic/framework/defaults/STANDARDS.md index b35ed86e..03c54083 100644 --- a/packages/mosaic/framework/defaults/STANDARDS.md +++ b/packages/mosaic/framework/defaults/STANDARDS.md @@ -32,7 +32,7 @@ Master/slave model: - Technical documentation follows **MOS-STE** (Mosaic Simplified Technical English — an adapted ASD-STE100 profile): short sentences, one instruction per sentence, active voice, one word per meaning, one term per concept. Full rules: `~/.config/mosaic/guides/WRITING-STYLE.md`. - Apply MOS-STE **hardest to verification artifacts** (acceptance criteria, witness predicates, gate/alarm conditions). There an ambiguous term produces a false green, not just a confused reader. - Source code follows the **Google Style Guide** for the language. -- User-facing comms follow the user's declared style in `USER.md` "Communication Preferences"; the default is technical. The documentation standard does not change with user preference. +- User-facing comms follow the user's declared `communicationStyle` in `USER.md` "Communication Preferences" (`direct` | `friendly` | `formal`, default `direct`); `guides/WRITING-STYLE.md` §5 maps each value to output. The documentation standard does not change with user preference. - **Carve-out:** MOS-STE does NOT apply to content that must carry a specific human voice (letters, personal or marketing prose, voice-matched output). A declared voice profile wins. ### Secrets handling (HARD RULE) diff --git a/packages/mosaic/framework/defaults/USER.md b/packages/mosaic/framework/defaults/USER.md index 7c94526c..2979a265 100644 --- a/packages/mosaic/framework/defaults/USER.md +++ b/packages/mosaic/framework/defaults/USER.md @@ -26,18 +26,6 @@ It is loaded globally and applies regardless of runtime or project. - No sycophancy - Executive summaries and tables for overview -### Comms style (agents read this to choose how they talk to you) - -Choose one. Agents match it for user-facing messages. The default is `technical`. -This setting governs comms only. It does not change the documentation standard -(`guides/WRITING-STYLE.md`), which is always MOS-STE. - -- **`technical`** (default) — MOS-STE structure: short, active, defined terms. -- **`prose`** — full sentences and paragraphs, warmer register, fewer tables. -- **`brief`** — status lines and bullet points, minimum words. - -> Comms style: technical - ## Personal Boundaries (Add any personal boundaries or preferences agents should respect.) diff --git a/packages/mosaic/framework/guides/WRITING-STYLE.md b/packages/mosaic/framework/guides/WRITING-STYLE.md index c338f69e..12a6805e 100644 --- a/packages/mosaic/framework/guides/WRITING-STYLE.md +++ b/packages/mosaic/framework/guides/WRITING-STYLE.md @@ -58,7 +58,8 @@ it certifies the defect. ### 3.1 Sentence rules 1. Keep sentences short. Use 20 words or fewer for a procedure. Use 25 words or - fewer for a description. + fewer for a description. (Reasoning and doctrine prose relaxes this limit — + see §3.4. A future lint enforces §3.1, not §3.4.) 2. Write one instruction per sentence. In a procedure, give one command per step. 3. Use the active voice. Write "Run the script." Do not write "The script should be run." @@ -104,18 +105,29 @@ exists. Keep code comments to the MOS-STE sentence and word rules. ## 5. User-facing comms — a per-user choice -Mosaic is multi-user. Different users want different comms styles. Read the -`USER.md` "Communication Preferences" section and match the declared style. +Mosaic is multi-user. Different users want different comms styles. The framework +already carries the selectable setting: `communicationStyle` (`direct` | +`friendly` | `formal`, default `direct`). `mosaic init` writes it, and the +builder renders it into the generated `USER.md` "Communication Preferences" +section. This guide adds the OUTPUT meaning of each value; do not invent new +values. -- **Default (no preference declared):** technical — MOS-STE structure, - readable-first. -- **Declared style wins.** If the user declares prose, warmth, or a specific - register, match it. The user's preference outranks the MOS-STE default for - user-facing comms. It does not change the documentation standard (§3). +Read the declared style in `USER.md` and match it: + +| `communicationStyle` | User-facing output | +|---|---| +| `direct` (default) | MOS-STE structure — short, active, defined terms, tables for overview. | +| `friendly` | Warmer register. Full sentences, explain reasoning, fewer tables. | +| `formal` | Professional and structured. Thorough, with explicit recommendations. | + +This setting governs **user-facing comms only**. It does not change the +documentation standard (§3), which is always MOS-STE regardless of the value. ## 6. Enforcement -- **Now:** human review plus the pre-push gate. Reviewers check output against the - scope table and the MOS-STE rules. -- **Future:** an MOS-STE lint check and a Google-style linter in the pre-push - gate. +- **Now:** human review only. **No mechanical prose check exists today.** The + pre-push gate runs typecheck, lint, build, and tests; it inspects no prose. + Reviewers check output against the scope table and the MOS-STE rules by hand. +- **Future:** an MOS-STE lint check (built from the §3.1 sentence rules) and a + Google-style linter in the pre-push gate. A future linter enforces §3.1, not + §3.4 — see the note at rule 1.