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:
@@ -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.
|
||||||
|
|||||||
Reference in New Issue
Block a user