diff --git a/AGENTS.md b/AGENTS.md index cf841daa..dd47be6b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -855,11 +855,11 @@ over rewrites; preserve the existing structure and the `doctoc` TOC markers (if you rename a heading, update its TOC entry in the same change). Use em dashes sparingly; do not add emojis. -The full editorial playbook — reporter-facing tone, email brevity, -Gmail threading, ASF-security-relay drafting, the "point to the -Security Model, don't re-explain it" rule, dependency-claim phrasing, -and the CVE / tracker-issue / PR link formats — lives in -[`docs/editorial-guidelines.md`](docs/editorial-guidelines.md). +Format prose across the repository (skills, docs, canned responses) using **semantic line breaks** ([SemBr](https://sembr.org)). +Break lines at natural linguistic boundaries — specifically one sentence per line (or at clause boundaries when helpful). +Because English is the programming language of Magpie skills, single-sentence changes produce single-line diffs rather than paragraph re-wraps. + +The full editorial playbook — reporter-facing tone, email brevity, Gmail threading, ASF-security-relay drafting, the "point to the Security Model, don't re-explain it" rule, dependency-claim phrasing, semantic line breaks, and the CVE / tracker-issue / PR link formats — lives in [`docs/editorial-guidelines.md`](docs/editorial-guidelines.md). **Load that file before drafting or editing any reporter-facing or tracker-facing text.** The load-bearing rules each external surface references are summarised below. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f28fec79..681b93f3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -100,7 +100,7 @@ classify a PR, mentor a contributor, allocate a CVE — is encoded in English-language skill files. That is the project's bet, and it is the bet you need to internalise before contributing. -Three practical consequences: +Four practical consequences: - **A change to a skill file is a code change.** Treat it like one. Run the eval suite. Think about boundary conditions. Add @@ -110,6 +110,10 @@ Three practical consequences: - **A change to a tool's `tool.md` is a code change.** Tool contracts in markdown are read by the skills at runtime; rewording the contract is rewording the API. +- **English code uses semantic line breaks ([SemBr](https://sembr.org)).** + Most programming language styles format one statement per line. + Because Magpie skills and documents are programs written in English, they follow the same convention: lines break at natural linguistic boundaries (one sentence per line, or at clause boundaries where appropriate). + This makes single-sentence edits produce single-line git diffs without rewrapping entire paragraphs. - **You author both layers agentically** — see [Authoring with an agent](#authoring-with-an-agent) below. The loop is the same whether the artefact is an English skill file diff --git a/docs/editorial-guidelines.md b/docs/editorial-guidelines.md index eb1b11eb..fef494e4 100644 --- a/docs/editorial-guidelines.md +++ b/docs/editorial-guidelines.md @@ -20,6 +20,7 @@ - [Confidentiality applies to *contents*, not to identifiers](#confidentiality-applies-to-contents-not-to-identifiers) - [Editing rules](#editing-rules) - [Mentioning project maintainers and security-team members](#mentioning-project-maintainers-and-security-team-members) + - [Semantic line breaks (SemBr)](#semantic-line-breaks-sembr) - [Other editorial guidelines](#other-editorial-guidelines) @@ -474,6 +475,24 @@ status comments they post as an `@` handle. Before publishing a status comment, the skills must grep for names of known people and flag any bare-name occurrence to the user. +## Semantic line breaks (SemBr) + +Prose across this repository — skill instructions (`SKILL.md`), tool contracts, documentation, and canned responses — uses **semantic line breaks** ([https://sembr.org](https://sembr.org)). + +Most programming language styles enforce one statement per line. +Because English is the primary programming language for Magpie skills, prose follows the same discipline: + +1. **One sentence per line.** + Break lines after full stops, question marks, and exclamation marks. +2. **Break at natural clause boundaries.** + Where sentences are long or complex, break at independent or dependent clauses (after commas, semicolons, colons, or conjunctions). +3. **No hard-wrapping at arbitrary column limits.** + Avoid hard-wrapping at 72 or 80 characters mid-sentence. + +**Why:** +Semantic line breaks ensure that single-sentence changes produce single-line git diffs. +This makes skill code and documentation changes easy to review without rewrapping entire paragraphs or causing unnecessary merge conflicts. + ## Other editorial guidelines - Project-specific naming rules (e.g. acronym casing, diff --git a/skills/write-skill/SKILL.md b/skills/write-skill/SKILL.md index bfd64e7a..0bb91788 100644 --- a/skills/write-skill/SKILL.md +++ b/skills/write-skill/SKILL.md @@ -239,6 +239,9 @@ Hard rules, References. Apply the framework's conventions: [`tools/dev/check-placeholders.sh`](../../tools/dev/check-placeholders.sh) prek hook catches the obvious cases but it is a backstop, not a substitute for getting the placeholder right at write time. +- **Semantic line breaks ([SemBr](https://sembr.org)).** + Format prose in the skill using semantic line breaks — break lines at natural linguistic boundaries (one sentence per line, or clause boundaries). + Just as traditional code formats one statement per line, writing skills in English means treating single sentences as atomic lines so that git diffs remain minimal and easy to review without rewrapping paragraphs. - **Adopter overrides.** Every skill consults `/.apache-magpie-overrides/.md` at runtime; the preamble that