diff --git a/packages/mosaic/framework/defaults/AGENTS.md b/packages/mosaic/framework/defaults/AGENTS.md index eb488c38..ca3117a2 100755 --- a/packages/mosaic/framework/defaults/AGENTS.md +++ b/packages/mosaic/framework/defaults/AGENTS.md @@ -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` | diff --git a/packages/mosaic/framework/defaults/STANDARDS.md b/packages/mosaic/framework/defaults/STANDARDS.md index d9ea7f40..03c54083 100644 --- a/packages/mosaic/framework/defaults/STANDARDS.md +++ b/packages/mosaic/framework/defaults/STANDARDS.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 `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) - Vault is the canonical source-of-truth for every secret in every environment. No exceptions. diff --git a/packages/mosaic/framework/guides/WRITING-STYLE.md b/packages/mosaic/framework/guides/WRITING-STYLE.md new file mode 100644 index 00000000..6fae5706 --- /dev/null +++ b/packages/mosaic/framework/guides/WRITING-STYLE.md @@ -0,0 +1,134 @@ +# 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, structured) | +| 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. (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." +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. 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. + +The builder renders the style as prose bullets, not the token name, so match on +the leading bullet the generated `USER.md` actually contains: + +| `USER.md` leading bullet | Style | User-facing output | +| ----------------------------- | ------------------ | ---------------------------------------------------------------------- | +| "Direct and concise" | `direct` (default) | MOS-STE structure — short, active, defined terms, tables for overview. | +| "Warm and conversational" | `friendly` | Warmer register. Full sentences, explain reasoning, fewer tables. | +| "Professional and structured" | `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 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.