Merge PR #509: feat(convention): built-in no-llm-tells convention with append-mode forbidden lists

Author: merge-queue-bot

.claude/skills/docs-author/SKILL.md

@@ -416,6 +416,15 @@ a non-native reader can parse on a first read.
 
 ## Anti-slop pass
 
+The banned-word and opener lists from
+`slop-patterns.md` ship as the built-in
+`no-llm-tells` convention. Set `convention:
+no-llm-tells` in `.mdsmith.yml` and MDS056 and
+MDS055 enforce them in CI with no model in the
+loop. This skill still owns the structural, tone,
+and formatting passes. Those need context that a
+substring check cannot provide.
+
 Run after the global-English pass. The catalog
 lives in `slop-patterns.md`. Load it, then walk
 the draft against each category. The catalog

.claude/skills/docs-author/slop-patterns.md

@@ -21,7 +21,18 @@ by recasting the sentence — swapping the word
 leaves the same shape behind, and that shape is
 the tell.
 
+The mechanical sections — "Vocabulary tells",
+"Phrasal tells", and "Sentence openers" — also
+ship as the built-in [`no-llm-tells`
+convention][conv], which MDS056 and MDS055 enforce
+in CI and the editor without a model in the loop. A
+drift-checker test keeps the convention's lists a
+subset of this catalog. The structural, tone, and
+formatting sections below need contextual judgement
+and stay skill-only.
+
 [wp-signs]: https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing
+[conv]: ../../../docs/reference/conventions.md
 
 ## Vocabulary tells
 

PLAN.md

@@ -138,7 +138,7 @@ footer: |
 | 210 | ✅     | opus   | [Single source of truth for product messaging via `mdsmith extract`](plan/210_messaging-source-of-truth.md)                             |
 | 211 | 🔳     | opus   | [`<?include?>` projects any typed value of any kind via `extract`](plan/211_include-extract-value.md)                                   |
 | 212 | ✅     | opus   | [`mdsmith extract` projects paragraph inline spans as data](plan/212_extract-inline-spans.md)                                           |
-| 213 | 🔲     | opus   | [Built-in `no-llm-tells` convention with append-mode forbidden lists](plan/213_anti-slop-convention.md)                                 |
+| 213 | 🔳     | opus   | [Built-in `no-llm-tells` convention with append-mode forbidden lists](plan/213_anti-slop-convention.md)                                 |
 | 214 | ✅     | sonnet | [MDS019 catalog: CUE-expression row templates](plan/214_catalog-cue-row-expressions.md)                                                 |
 | 214 | ⛔     | opus   | [Obsidian plugin via hand-rolled LSP bridge](plan/214_obsidian-plugin.md)                                                               |
 | 215 | ✅     | opus   | [mdsmith public engine API and WASM bindings](plan/215_engine-api-wasm.md)                                                              |

docs/reference/conventions.md

@@ -12,11 +12,9 @@ settings that pairs a Markdown flavor with a set of
 style choices. Setting `convention:` at the top of
 your `.mdsmith.yml` selects one of the built-in
 bundles; the rule presets in that bundle are applied
-as a base layer beneath your own rule config.
-
-Conventions answer "what kind of Markdown does this
-project write?" with one config knob instead of
-eight.
+as a base layer beneath your own rule config. It
+answers "what kind of Markdown does this project
+write?" with one config knob instead of eight.
 
 A convention is distinct from a flavor. Flavor is a
 property of the *renderer* (CommonMark, GFM,
@@ -36,12 +34,11 @@ convention: portable
 That single line pins a flavor and a curated set of
 style-rule settings. `convention:` is a top-level
 config key, sibling to `rules:`, `kinds:`, and
-`overrides:`. Setting an unknown name is a config
-error at load time.
+`overrides:`. An unknown name is a config error.
 
 Built-in values: `portable`, `github`, `obsidian`,
-`parity`, `plain`. The key is optional; omit it for no
-convention.
+`parity`, `plain`, `no-llm-tells`. The key is
+optional; omit it for no convention.
 
 You may also set `flavor:` inside `markdown-flavor`
 alongside `convention:`. If both are set, they must
@@ -130,16 +127,32 @@ markdownlint-compatible tools (mado, rumdl) check
 it: `flavor: gfm` plus every mdsmith-only rule
 turned off, leaving the structural style class
 those tools also run. Use it for a like-for-like
-comparison, or as a fast check-only markdownlint
-gate before you adopt the cross-file and
-generated-section layer. The disabled-rule list is
-generated from the convention so it never drifts —
-see the [benchmark doc][parity-list]. Unlike the
-other built-ins, `parity` leaves `markdown-flavor`
+comparison, or as a fast markdownlint gate before
+you adopt the cross-file and generated-section
+layer. The disabled-rule list is generated from the
+convention, so it never drifts — see the
+[benchmark doc][parity-list]. Unlike the other
+built-ins, `parity` leaves `markdown-flavor`
 (MDS034) opt-in.
 
 [parity-list]: ../research/benchmarks/README.md
 
+### `no-llm-tells`
+
+Flags mechanical LLM-prose tells in CI. MDS056
+blocks vocabulary and phrasal tells; MDS055 blocks
+banned sentence openers; MDS023 and MDS024 tighten
+readability budgets. Lists are sourced from
+[`slop-patterns.md`][slop]; a drift-checker test
+keeps the two in sync.
+
+Pins no flavor and does not enable `markdown-flavor`
+(MDS034). The `contains` and `starts` lists merge by
+**append**: a project's own entries join the
+convention's list instead of replacing it.
+
+[slop]: ../../.claude/skills/docs-author/slop-patterns.md
+
 ## How presets layer with user config
 
 Convention presets sit between built-in defaults
@@ -166,9 +179,8 @@ The `default` and `user` layers come from the same
 convention so a convention can enable a rule that
 is opt-in by default (e.g. `convention: portable`
 turns on MDS034). Without the split, the default's
-`Enabled: false` would land on top of the
-convention's `Enabled: true` and silently disable
-the rule.
+`Enabled: false` would override the convention's
+`Enabled: true`.
 
 For example, the `github` convention sets
 `no-inline-html.allow: [details, summary]`. To
@@ -199,24 +211,15 @@ rules:
   markdown-flavor: false
 ```
 
-The `convention:` selector lives at the top level.
-So the user can disable MDS034 cleanly with a
-bool-only `markdown-flavor: false` entry in the
-rules block. The convention preset has already
-populated the merged config at load time. A
-bool-only later layer toggles `enabled` without
-erasing the preset's settings. The rule stays
-configured but its `Check()` is gated off. The
-other rules in the preset are untouched.
-
-This split keeps MDS034 focused on "what does this
-renderer interpret as a feature." Conventions
-orchestrate style separately.
+A bool-only `markdown-flavor: false` entry toggles
+`enabled` without erasing the preset's settings. The
+rule stays configured but its `Check()` is gated
+off. The other rules in the preset are untouched.
 
 ## User-defined conventions
 
-The three built-in conventions cover common cases.
-Teams that need something custom define it inline in
+The built-in conventions cover common cases. Teams
+that need something custom define it inline in
 `.mdsmith.yml`. The top-level `conventions:` key holds
 the map:
 
@@ -260,10 +263,10 @@ convention "our-team" rule "no-inline-html": no-inline-html: unknown setting "al
 ### Reserved names
 
 The built-in names `portable`, `github`,
-`obsidian`, `parity`, and `plain` are reserved.
-Defining a `conventions.portable` entry is a config
-error. This keeps the built-in names stable across
-docs and tutorials.
+`obsidian`, `parity`, `plain`, and `no-llm-tells`
+are reserved. Defining a `conventions.portable`
+entry is a config error. This keeps the built-in
+names stable across docs and tutorials.
 
 ### Resolution order
 
@@ -274,25 +277,17 @@ is impossible. When neither table matches, the error
 lists both sets:
 
 ```text
-unknown convention "bogus" (valid: github, obsidian, our-team, parity, plain, portable)
+unknown convention "bogus" (valid: github, no-llm-tells, obsidian, our-team, parity, plain, portable)
 ```
 
 ### Interaction with top-level rules
 
-User-defined conventions apply as a base layer, exactly
-like the built-in conventions. A top-level `rules:`
-entry overrides the convention preset for that rule.
-The rest of the preset remains.
-
-### Inspecting user conventions
-
-`mdsmith kinds resolve <file>` labels user convention
-layers with a `(user)` suffix. Built-in conventions
-carry no suffix. Example merge-chain output:
-
-```text
-convention.our-team (user)   set    {flavor: gfm}
-```
+User-defined conventions apply as a base layer, like
+the built-in conventions. A top-level `rules:` entry
+overrides the convention preset for that rule; the
+rest of the preset remains. `mdsmith kinds resolve
+<file>` labels user-convention layers with a
+`(user)` suffix.
 
 ## Inspecting an effective convention
 

internal/config/config_test.go

@@ -27,6 +27,8 @@ import (
 	_ "github.com/jeduden/mdsmith/internal/rules/fencedcodelanguage"
 	_ "github.com/jeduden/mdsmith/internal/rules/fencedcodestyle"
 	_ "github.com/jeduden/mdsmith/internal/rules/firstlineheading"
+	_ "github.com/jeduden/mdsmith/internal/rules/forbiddenparagraphstarts"
+	_ "github.com/jeduden/mdsmith/internal/rules/forbiddentext"
 	_ "github.com/jeduden/mdsmith/internal/rules/headingincrement"
 	_ "github.com/jeduden/mdsmith/internal/rules/headingstyle"
 	_ "github.com/jeduden/mdsmith/internal/rules/horizontalrulestyle"

internal/config/convention.go

@@ -46,7 +46,10 @@ func applyConvention(cfg *Config) error {
 	if err != nil {
 		return fmt.Errorf("convention: %w", err)
 	}
-	if rc, ok := cfg.Rules["markdown-flavor"]; ok {
+	if rc, ok := cfg.Rules["markdown-flavor"]; ok && conv.Flavor != convention.FlavorAny {
+		// A convention with FlavorAny is renderer-agnostic (e.g.
+		// no-llm-tells); it imposes no flavor and never conflicts with a
+		// user's markdown-flavor selection, so the guard is skipped.
 		userFlavor, err := stringSetting(
 			rc.Settings, "flavor", "rules.markdown-flavor.flavor",
 		)

internal/config/convention_test.go

@@ -96,6 +96,51 @@ func TestApplyConvention_FlavorMismatchErrors(t *testing.T) {
 	assert.Contains(t, err.Error(), "gfm")
 }
 
+func TestApplyConvention_FlavorUnsetConventionAllowsAnyUserFlavor(t *testing.T) {
+	// no-llm-tells leaves its flavor unset (FlavorAny). A project that
+	// also pins markdown-flavor to gfm must not be rejected: the
+	// convention is renderer-agnostic and does not enable markdown-flavor.
+	cfg := &Config{
+		Convention: "no-llm-tells",
+		Rules: map[string]RuleCfg{
+			"markdown-flavor": {Enabled: true, Settings: map[string]any{"flavor": "gfm"}},
+		},
+	}
+	require.NoError(t, applyConvention(cfg))
+	require.NotNil(t, cfg.ConventionPreset)
+}
+
+func TestApplyConvention_NoLLMTells_EnablesRulesWithSettings(t *testing.T) {
+	cfg := &Config{Convention: "no-llm-tells"}
+	require.NoError(t, applyConvention(cfg))
+
+	ft, ok := cfg.ConventionPreset["forbidden-text"]
+	require.True(t, ok, "preset must contain forbidden-text")
+	assert.True(t, ft.Enabled)
+	contains, ok := ft.Settings["contains"].([]any)
+	require.True(t, ok, "contains must be []any")
+	assert.Contains(t, contains, "delve")
+	assert.Contains(t, contains, "it's important to note that")
+
+	fps, ok := cfg.ConventionPreset["forbidden-paragraph-starts"]
+	require.True(t, ok, "preset must contain forbidden-paragraph-starts")
+	starts, ok := fps.Settings["starts"].([]any)
+	require.True(t, ok)
+	assert.Contains(t, starts, "Moreover,")
+
+	ps, ok := cfg.ConventionPreset["paragraph-structure"]
+	require.True(t, ok)
+	assert.Equal(t, 25, ps.Settings["max-words-per-sentence"])
+
+	pr, ok := cfg.ConventionPreset["paragraph-readability"]
+	require.True(t, ok)
+	assert.Equal(t, 12.0, pr.Settings["max-index"])
+
+	dlt, ok := cfg.ConventionPreset["descriptive-link-text"]
+	require.True(t, ok)
+	assert.True(t, dlt.Enabled)
+}
+
 func TestApplyConvention_FlavorAgreeAccepted(t *testing.T) {
 	cfg := &Config{
 		Convention: "github",
@@ -166,6 +211,49 @@ func TestEffectiveRules_UserSettingDeepMergesOverConvention(t *testing.T) {
 	assert.Equal(t, true, rc.Settings["require-blank-lines"], "preset sibling preserved")
 }
 
+func TestEffectiveRules_NoLLMTells_UserForbiddenTextUnionsWithConvention(t *testing.T) {
+	// A project pins no-llm-tells and adds its own forbidden phrase.
+	// MDS056 opts contains: into MergeAppend, so the user's list unions
+	// with the convention's instead of replacing it.
+	cfg := &Config{
+		Convention: "no-llm-tells",
+		Rules: map[string]RuleCfg{
+			"forbidden-text": {
+				Enabled:  true,
+				Settings: map[string]any{"contains": []any{"synergy"}},
+			},
+		},
+		ExplicitRules: map[string]bool{"forbidden-text": true},
+	}
+	require.NoError(t, applyConvention(cfg))
+
+	got := Effective(cfg, "doc.md", nil, nil)
+	contains, ok := got["forbidden-text"].Settings["contains"].([]any)
+	require.True(t, ok)
+	assert.Contains(t, contains, "delve", "convention entry survives")
+	assert.Contains(t, contains, "synergy", "user entry is added")
+}
+
+func TestEffectiveRules_NoLLMTells_UserOpenersUnionWithConvention(t *testing.T) {
+	cfg := &Config{
+		Convention: "no-llm-tells",
+		Rules: map[string]RuleCfg{
+			"forbidden-paragraph-starts": {
+				Enabled:  true,
+				Settings: map[string]any{"starts": []any{"We "}},
+			},
+		},
+		ExplicitRules: map[string]bool{"forbidden-paragraph-starts": true},
+	}
+	require.NoError(t, applyConvention(cfg))
+
+	got := Effective(cfg, "doc.md", nil, nil)
+	starts, ok := got["forbidden-paragraph-starts"].Settings["starts"].([]any)
+	require.True(t, ok)
+	assert.Contains(t, starts, "Moreover,", "convention entry survives")
+	assert.Contains(t, starts, "We ", "user entry is added")
+}
+
 func TestProvenance_ConventionLayerVisible(t *testing.T) {
 	cfg := &Config{Convention: "portable"}
 	require.NoError(t, applyConvention(cfg))

internal/convention/convention.go

@@ -179,6 +179,52 @@ var conventions = map[string]Convention{
 			},
 		},
 	},
+	// no-llm-tells ships the mechanical layer of the docs-author
+	// anti-slop catalog as a one-key convention. It enables MDS056
+	// (forbidden-text) with a curated list of LLM vocabulary and phrase
+	// tells, MDS055 (forbidden-paragraph-starts) with the banned
+	// sentence openers, and tightens MDS023 (max-words-per-sentence) and
+	// MDS024 (paragraph-readability max-index) for non-native readers.
+	// MDS027 (descriptive-link-text) rounds out the bundle.
+	//
+	// Flavor is left unset (FlavorAny): anti-slop is renderer-agnostic,
+	// so the convention must not force a GFM or Obsidian project off its
+	// flavor. The convention does not enable markdown-flavor (MDS034), so
+	// the flavor field never reports; the loader skips the flavor-conflict
+	// guard for a convention whose flavor is FlavorAny.
+	//
+	// The curated lists live in nollmtells.go; their source of truth is
+	// .claude/skills/docs-author/slop-patterns.md, kept in sync by the
+	// drift-checker integration test.
+	"no-llm-tells": {
+		Name:   "no-llm-tells",
+		Flavor: FlavorAny,
+		Rules: map[string]RulePreset{
+			"forbidden-text": {
+				Enabled: true,
+				Settings: map[string]any{
+					"contains": toAnySlice(llmVocabularyAndPhrases()),
+				},
+			},
+			"forbidden-paragraph-starts": {
+				Enabled: true,
+				Settings: map[string]any{
+					"starts": toAnySlice(llmParagraphOpeners()),
+				},
+			},
+			"paragraph-structure": {
+				Enabled: true,
+				Settings: map[string]any{
+					"max-words-per-sentence": 25,
+				},
+			},
+			"paragraph-readability": {
+				Enabled:  true,
+				Settings: map[string]any{"max-index": 12.0},
+			},
+			"descriptive-link-text": {Enabled: true},
+		},
+	},
 	// parity restricts mdsmith to the markdownlint-compatible rule
 	// class — the structural style rules the Rust markdownlint ports
 	// (mado, rumdl) also run — by turning off every mdsmith-only rule:

internal/convention/convention_test.go

@@ -199,7 +199,7 @@ func TestNamesSorted(t *testing.T) {
 	names := Names()
 	assert.True(t, sort.StringsAreSorted(names),
 		"Names should return a sorted slice; got %v", names)
-	assert.ElementsMatch(t, []string{"github", "obsidian", "parity", "plain", "portable"}, names)
+	assert.ElementsMatch(t, []string{"github", "no-llm-tells", "obsidian", "parity", "plain", "portable"}, names)
 }
 
 // parityDisabledRules is the canonical set of rules the built-in