fix(framework): ride the existing communicationStyle enum, drop the no-op USER.md edit (mos-dt review #960)

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 <[email protected]>
This commit is contained in:
2026-07-30 15:24:17 -05:00
co-authored by Claude Fable 5
parent 6cc093afdb
commit caf40afc01
3 changed files with 25 additions and 25 deletions
@@ -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`. - 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. - 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. - 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. - **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) ### Secrets handling (HARD RULE)
@@ -26,18 +26,6 @@ It is loaded globally and applies regardless of runtime or project.
- No sycophancy - No sycophancy
- Executive summaries and tables for overview - 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 ## Personal Boundaries
(Add any personal boundaries or preferences agents should respect.) (Add any personal boundaries or preferences agents should respect.)
@@ -58,7 +58,8 @@ it certifies the defect.
### 3.1 Sentence rules ### 3.1 Sentence rules
1. Keep sentences short. Use 20 words or fewer for a procedure. Use 25 words or 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. 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 3. Use the active voice. Write "Run the script." Do not write "The script should
be run." 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 ## 5. User-facing comms — a per-user choice
Mosaic is multi-user. Different users want different comms styles. Read the Mosaic is multi-user. Different users want different comms styles. The framework
`USER.md` "Communication Preferences" section and match the declared style. 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, Read the declared style in `USER.md` and match it:
readable-first.
- **Declared style wins.** If the user declares prose, warmth, or a specific | `communicationStyle` | User-facing output |
register, match it. The user's preference outranks the MOS-STE default for |---|---|
user-facing comms. It does not change the documentation standard (§3). | `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 ## 6. Enforcement
- **Now:** human review plus the pre-push gate. Reviewers check output against the - **Now:** human review only. **No mechanical prose check exists today.** The
scope table and the MOS-STE rules. pre-push gate runs typecheck, lint, build, and tests; it inspects no prose.
- **Future:** an MOS-STE lint check and a Google-style linter in the pre-push Reviewers check output against the scope table and the MOS-STE rules by hand.
gate. - **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.