feat(framework): MOS-STE writing standard + Google-style code + per-user comms choice

Adds the agent output standard to the framework SOT so it injects at launch and is selectable per user (closes the gap: it lived only as a jarvis-brain lab doc + issue #960). - guides/WRITING-STYLE.md: MOS-STE (adapted ASD-STE100) for docs, Google Style for code, verification-artifact emphasis, absolute user-voice carve-out. Written in MOS-STE. - defaults/STANDARDS.md: Output-standards block (always injected via the prompting contract). - defaults/AGENTS.md: routing row so writing/doc/comms work reaches the guide. - defaults/USER.md: per-user 'Comms style' option (technical|prose|brief), default technical. Refs mosaicstack/stack#960. Owner directive (Jason, 2026-07-30): docs->adapted ASD-STE100, code->Google style, resumes/personal carved out, comms style a per-user choice. Written-by: jarvis (dragon-lin) Co-Authored-By: Claude Fable 5 <[email protected]>
2026-07-30 14:19:26 -05:00
parent 6a7fce34bb
commit 6cc093afdb
4 changed files with 142 additions and 0 deletions
@@ -39,6 +39,7 @@ overwritten on upgrade. (Layer model: `constitution/LAYER-MODEL.md`.)
 | TypeScript strict typing                           | `guides/TYPESCRIPT.md`             |
 | QA / test strategy                                 | `guides/QA-TESTING.md`             |
 | Documentation (any code/API/auth/infra change)     | `guides/DOCUMENTATION.md`          |
+| Writing style (docs, comms, any prose)             | `guides/WRITING-STYLE.md`          |
 | Secrets / vault usage                              | `guides/VAULT-SECRETS.md`          |
 | Tool/credential reference (service CLIs, wrappers) | `guides/TOOLS-REFERENCE.md`        |
 | Memory protocol (OpenBrain capture/recall)         | `guides/MEMORY.md`                 |
@@ -27,6 +27,14 @@ Master/slave model:
 - Do not perform destructive git/file actions without explicit instruction.
 - Browser automation (Playwright, Cypress, Puppeteer) MUST run in headless mode. Never launch a visible browser — it collides with the user's display and active session.

+### Output standards (writing + code)
+
+- 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.
+- **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)

 - Vault is the canonical source-of-truth for every secret in every environment. No exceptions.
@@ -26,6 +26,18 @@ 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.)
@@ -0,0 +1,121 @@
+# Writing Style Standard — MOS-STE (MANDATORY)
+
+This guide defines how agents write. It sets one style standard per output type.
+It is written in the standard it defines, as a worked example.
+
+**Adapted, not compliant.** MOS-STE (Mosaic Simplified Technical English) is an
+adapted profile of ASD-STE100. Mosaic does not license or certify against
+ASD-STE100. Mosaic uses the load-bearing rules and fits them to agent work. This
+is the same stance Mosaic takes toward DO-178B/C: use the rigor, do not claim the
+certification.
+
+## Scope — which standard governs which output
+
+| Output type | Standard |
+|---|---|
+| Technical documentation (READMEs, runbooks, PRDs, procedures, ADRs, guides, acceptance criteria, design docs) | **MOS-STE** (this guide) |
+| Source code and code comments | **Google Style Guide** for the language (§4) |
+| Inter-agent comms | MOS-STE by default (concise, technical) |
+| User-facing comms | **Per-user style choice** — read `USER.md` "Communication Preferences" (§5) |
+| End-user prose the user owns (marketing, letters, personal writing, voice-matched content) | The user's declared voice. MOS-STE does NOT apply. |
+
+**The user-voice carve-out is absolute.** Do not apply MOS-STE to content that
+must carry a specific human voice (for example a cover letter, a personal
+message, or marketing copy). That content needs the user's voice. MOS-STE would
+damage it. When a project declares a voice profile, that profile wins.
+
+## 1. Why one standard
+
+Agent documentation drifts across projects. Different agents use different terms,
+sentence styles, and structures for the same concept. Readers lose time.
+Assumptions hide in ambiguous prose. One standard gives agents a clear target. It
+gives reviewers a clear test.
+
+## 2. Where MOS-STE matters most — verification artifacts
+
+Apply MOS-STE hardest to acceptance criteria, witness predicates, gate
+definitions, and alarm conditions. In prose, an ambiguous term produces a
+confused reader. In a verification artifact, an ambiguous term produces a false
+green — a check that passes without testing the claim.
+
+The one-term-one-concept rule (rule 9) is the guard. When one word names two
+concepts in one predicate, the check can test the wrong concept and still pass.
+
+**Worked failure.** A rename used a witness predicate with three clauses: ref A
+present, ref B absent, tip committed from this host. Every clause tested the git
+*ref* (the channel). The claim under test was about a *field inside the payload*.
+The word "beacon" named two concepts in one sentence. Deleting ref B was the next
+scheduled step. That step flips the last clause green and certifies a state in
+which the payload still names the wrong host. The predicate was one planned action
+away from a false green on its normal path. The payload field was never tested.
+
+Rule: when N failure modes share one observable, the observable is not a
+diagnostic. In a verification artifact, that ambiguity does not confuse a reader —
+it certifies the defect.
+
+## 3. MOS-STE rules
+
+### 3.1 Sentence rules
+
+1. Keep sentences short. Use 20 words or fewer for a procedure. Use 25 words or
+   fewer for a description.
+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."
+4. Use the imperative for instructions. Start the sentence with the verb.
+5. Use simple verb tenses. Prefer the present tense. Avoid the perfect and
+   progressive tenses when a simple tense works.
+6. Do not use an `-ing` form when it makes the meaning unclear.
+7. Write positive statements. State what to do, not only what to avoid.
+
+### 3.2 Word rules
+
+8. Use one word for one meaning. Do not use the same word in two senses.
+9. Use one term for one concept. Do not use synonyms for variety. Example: choose
+   `secret`, `credential`, or `key` for each concept, and keep it.
+10. Use articles (`a`, `the`). Do not drop words to save space.
+11. Keep an approved-terms glossary per project. Add each domain noun and each
+    chosen verb. Technical names (for example `Vault`, `cgroup`, `systemd`) are
+    always allowed.
+12. Define an abbreviation at its first use. Then use it consistently.
+
+### 3.3 Structure rules
+
+13. Use a list for parallel items or sequential steps. Do not put them in one long
+    sentence.
+14. Use a table for data with more than two dimensions.
+15. Use parallel structure in headings and steps.
+16. Repeat the noun. Do not use a pronoun when the reference is unclear.
+
+### 3.4 Adaptation notes (where MOS-STE deviates from ASD-STE100, and why)
+
+- **No licensed dictionary.** ASD-STE100 ships a controlled dictionary under
+  copyright. MOS-STE uses per-project glossaries instead (rule 11).
+- **Domain terms are allowed.** MOS-STE keeps every term the work needs.
+- **Reasoning prose gets structure, not amputation.** Apply the sentence and word
+  rules to design and doctrine writing. Allow the length a subtle argument needs.
+  Readable-first beats rule-strict when the two conflict.
+
+## 4. Code — Google Style Guide
+
+Write source code to the Google Style Guide for the language (Python, TypeScript,
+Shell, Go, and so on). Match the existing file when a local convention already
+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.
+
+- **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).
+
+## 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.