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`.
- 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)
@@ -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.)
@@ -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.