Merge PR #706: feat(convention): add built-in slidev convention (plan 2606270013)

Author: merge-queue-bot

PLAN.md

@@ -234,6 +234,7 @@ footer: |
 | 2606260211 | ✅     | sonnet | [Add dedicated unit tests for layer0_html.go helpers](plan/2606260211_arch-fix-layer0-html-helper-tests.md)                                             |
 | 2606260614 | ✅     | sonnet | [arch-fix: add dedicated unit tests for lineclass_scan.go HTML-scanning helpers](plan/2606260614_arch-fix-lineclass-scan-helper-tests.md)               |
 | 2606260615 | ✅     | sonnet | [Add dedicated unit tests for unexported helpers in cue/cuelite/engine.go](plan/2606260615_arch-fix-cuelite-engine-helper-tests.md)                     |
+| 2606270013 | ✅     | sonnet | [Add built-in Slidev convention](plan/2606270013_slidev-convention.md)                                                                                  |
 | 2606280208 | ✅     | opus   | [External URL link checking rule (MDS072)](plan/2606280208_external-link-check.md)                                                                      |
 | 2606292015 | 🔲     | opus   | [Scope the LSP workspace singleton per client so instances coexist](plan/2606292015_lsp-multi-instance-coexistence.md)                                  |
 | 2607022118 | 🔲     | sonnet | [General occurrence rule — bound how often a pattern appears per scope](plan/2607022118_occurrence-rule.md)                                             |
@@ -253,6 +254,7 @@ footer: |
 | 2607082052 | ✅     | sonnet | [SARIF output format for `mdsmith check`](plan/2607082052_check-sarif-output.md)                                                                        |
 | 2607121915 | ✅     | sonnet | [Resolve the internal/linkgraph purity-contract mismatch for wikilink resolution](plan/2607121915_arch-fix-linkgraph-wikilink-purity.md)                |
 | 2607170527 | 🔳     | opus   | [External link checking on WASM hosts (MDS072)](plan/2607170527_wasm-external-link-check.md)                                                            |
+| 2607171900 | 🔳     | opus   | [Slidev structure rule (MDS073) — validate layouts, slots, fields, and frontmatter keys per slide](plan/2607171900_slidev-structure-rule.md)            |
 | 2607191917 | 🔲     | haiku  | [Add dedicated unit tests for printInitCatalog and setInitUsage](plan/2607191917_arch-fix-printinitcatalog-unit-test.md)                                |
 | 2607191918 | 🔲     | haiku  | [Deduplicate isClaimed between internal/schema and requiredstructure](plan/2607191918_arch-fix-isclaimed-dedup.md)                                      |
 <?/catalog?>

docs/background/concepts/flavor-rule-convention-kind.md

@@ -45,14 +45,14 @@ conventions or kinds.
 
 ### Convention
 
-A convention is a named bundle that pairs a flavor
-with a set of rule presets. Selecting a convention
-applies both: MDS034 runs against the named flavor,
-and the named rule presets are applied as a base
-layer beneath the user's own rule config. The
+A convention is a named bundle of rule presets that
+optionally pins a flavor. Selecting a convention
+applies both: when a flavor is pinned, MDS034 runs
+against it; the named rule presets are applied as a
+base layer beneath the user's own rule config. The
 built-in conventions are `portable`, `github`,
-`obsidian`, `plain`, `no-llm-tells`, and four
-`<linter>-parity` conventions. Each one runs the
+`obsidian`, `plain`, `no-llm-tells`, `slidev`, and
+four `<linter>-parity` conventions. Each one runs the
 rule set a peer linter (gomarklint, mado, rumdl,
 markdownlint) enables by default, so `mdsmith check`
 matches that peer's work for a like-for-like

docs/reference/conventions.md

@@ -37,14 +37,17 @@ config key, sibling to `rules:`, `kinds:`, and
 `overrides:`. An unknown name is a config error.
 
 Built-in values: `portable`, `github`, `obsidian`,
-`plain`, `no-llm-tells`, and the four
+`plain`, `no-llm-tells`, `slidev`, and the four
 `<linter>-parity` conventions below. 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
-agree — a convention that requires `commonmark`
-rejects `flavor: gfm` at config load.
+agree — a convention that pins a flavor (e.g.
+`portable` requires `commonmark`) rejects a
+conflicting `flavor:` at config load. Conventions
+that pin no flavor (`slidev`, `no-llm-tells`) do not
+enforce this check.
 
 ## Built-in conventions
 
@@ -113,13 +116,10 @@ plus `allow-comments: false` on `no-inline-html` so
 HTML comments do not leak through as literal
 `<!-- ... -->` text.
 
-A truly plaintext-faithful convention needs three
-more rules. One forbids `*` and `_` runs. One
-requires indented code blocks. One inverts
-`no-bare-urls` so bare URLs are preferred over
-Markdown links. Those rules don't exist yet. When
-they ship, the `plain` convention gains them and
-diverges from `portable`.
+Three additional rules (forbid `*`/`_` runs,
+require indented code blocks, prefer bare URLs) do
+not exist yet. When they ship, `plain` gains them
+and diverges from `portable`.
 
 ### `<linter>-parity`
 
@@ -162,6 +162,26 @@ project's terms join rather than replace them.
 
 [slop]: ../../.claude/skills/docs-author/slop-patterns.md
 
+### `slidev`
+
+Disables eight default-on rules that produce false
+positives on [Slidev](https://sli.dev) files, and
+enables `slide-structure` (MDS073) to validate
+per-slide layouts, slots, fields, and keys. Slidev
+uses `---` as a slide separator (parsed as a setext
+underline); headings restart per slide. Pins no flavor.
+
+| Rule                                          | Why disabled                               |
+| --------------------------------------------- | ------------------------------------------ |
+| `heading-style` (MDS002)                      | `---` separator parsed as setext underline |
+| `heading-increment` (MDS003)                  | Each slide restarts at H1                  |
+| `first-line-heading` (MDS004)                 | Front matter before first heading          |
+| `no-duplicate-headings` (MDS005)              | Same title on multiple slides              |
+| `blank-line-around-headings` (MDS013)         | Layout blocks interfere                    |
+| `no-trailing-punctuation-in-heading` (MDS017) | Stylistic slide titles                     |
+| `no-emphasis-as-heading` (MDS018)             | Bold used for slide emphasis               |
+| `empty-section-body` (MDS030)                 | Layout-only slides have no body            |
+
 ## How presets layer with user config
 
 Convention presets sit between built-in defaults
@@ -177,19 +197,13 @@ oldest → newest, is:
    effective list
 5. `overrides[i]` — each matching override entry
 
-Each layer deep-merges onto the previous one.
-Scalars at a leaf are replaced by the later layer;
-maps recurse key by key; lists replace by default.
-A convention preset provides the floor; your
-explicit `rules:` block overrides on top.
-
-The `default` and `user` layers come from the same
-`cfg.Rules` map. mdsmith splits them around the
-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 override the convention's
-`Enabled: true`.
+Each layer deep-merges: scalar leaves replace, maps
+recurse key by key, lists replace by default. The
+convention provides the floor; your `rules:` block
+overrides on top. mdsmith splits `default` and
+`user` around the convention so a convention can
+enable an opt-in rule without being overridden by
+the default's `Enabled: false`.
 
 For example, the `github` convention sets
 `no-inline-html.allow: [details, summary]`. To
@@ -210,20 +224,11 @@ and always appends — see [word-list files](wordlist-files.md).
 
 ## Disabling MDS034
 
-A convention applies its rule presets at config
-load time. Disabling `markdown-flavor` itself does
-not disable the rules a convention turned on.
-
-```yaml
-convention: portable
-rules:
-  markdown-flavor: false
-```
-
-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.
+Convention presets apply at config load. A bool-only
+`markdown-flavor: false` entry in `rules:` toggles
+`enabled` without erasing preset settings — the rule
+is gated off but the other convention rules are
+untouched.
 
 ## User-defined conventions
 
@@ -272,32 +277,27 @@ convention "our-team" rule "no-inline-html": no-inline-html: unknown setting "al
 ### Reserved names
 
 The built-in names `portable`, `github`,
-`obsidian`, `plain`, `no-llm-tells`, and the four
-`<linter>-parity` conventions are reserved. Defining
-a `conventions.portable` entry is a config error.
-This keeps the built-in names stable across docs and
-tutorials.
+`obsidian`, `plain`, `no-llm-tells`, `slidev`, and
+the four `<linter>-parity` conventions are reserved.
+Defining a `conventions.portable` entry is a config
+error. This keeps the built-in names stable across
+docs and tutorials.
 
-### Resolution order
+### Resolution order and layering
 
 The lookup checks user-defined conventions first,
-then falls back to the built-in table. Collisions with
-reserved names are rejected at load time, so shadowing
-is impossible. When neither table matches, the error
-lists both sets:
+then the built-in table. A collision with a reserved
+name is a config error — shadowing is impossible.
+When neither matches, the error lists both sets:
 
 ```text
-unknown convention "bogus" (valid: github, gomarklint-parity, mado-parity, markdownlint-parity, no-llm-tells, obsidian, our-team, plain, portable, rumdl-parity)
+unknown convention "bogus" (valid: github, gomarklint-parity, mado-parity, markdownlint-parity, no-llm-tells, obsidian, our-team, plain, portable, rumdl-parity, slidev)
 ```
 
-### Interaction with top-level rules
-
 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.
+the built-ins. A top-level `rules:` entry overrides
+the convention preset; `mdsmith kinds resolve <file>`
+labels user-convention layers with a `(user)` suffix.
 
 ## Inspecting an effective convention
 

docs/research/markdownlint-coverage/README.md

@@ -826,6 +826,7 @@ row-expr: |
 | [MDS067](../../../internal/rules/MDS067-callout-type/README.md) callout-type                 | —                          | —                          | —                       | —       | —               | —          |
 | [MDS069](../../../internal/rules/MDS069-unique-frontmatter/README.md) unique-frontmatter     | —                          | —                          | —                       | —       | —               | —          |
 | [MDS071](../../../internal/rules/MDS071-required-frontmatter/README.md) required-frontmatter | —                          | —                          | —                       | —       | —               | —          |
+| [MDS073](../../../internal/rules/MDS073-slide-structure/README.md) slide-structure           | —                          | —                          | —                       | —       | —               | —          |
 <?/catalog?>
 
 ## Generated sections (directives) (mdsmith-only)

internal/config/convention_test.go

@@ -141,6 +141,48 @@ func TestApplyConvention_NoLLMTells_EnablesRulesWithSettings(t *testing.T) {
 	assert.True(t, dlt.Enabled)
 }
 
+func TestApplyConvention_Slidev_FlavorAnyAllowsUserFlavor(t *testing.T) {
+	// slidev uses FlavorAny — it imposes no renderer requirement and
+	// must not reject a user's markdown-flavor setting.
+	cfg := &Config{
+		Convention: "slidev",
+		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_Slidev_DisablesEightRulesInPreset(t *testing.T) {
+	cfg := &Config{Convention: "slidev"}
+	require.NoError(t, applyConvention(cfg))
+	require.NotNil(t, cfg.ConventionPreset)
+
+	disabledRules := []string{
+		"heading-style",
+		"heading-increment",
+		"first-line-heading",
+		"no-duplicate-headings",
+		"blank-line-around-headings",
+		"no-trailing-punctuation-in-heading",
+		"no-emphasis-as-heading",
+		"empty-section-body",
+	}
+	for _, rule := range disabledRules {
+		p, ok := cfg.ConventionPreset[rule]
+		if assert.True(t, ok, "slidev preset must contain rule %q", rule) {
+			assert.False(t, p.Enabled, "slidev preset must disable rule %q", rule)
+		}
+	}
+
+	// slidev also enables the opt-in slide-structure rule.
+	ss, ok := cfg.ConventionPreset["slide-structure"]
+	if assert.True(t, ok, "slidev preset must contain slide-structure") {
+		assert.True(t, ss.Enabled, "slidev preset must enable slide-structure")
+	}
+}
+
 func TestApplyConvention_FlavorAgreeAccepted(t *testing.T) {
 	cfg := &Config{
 		Convention: "github",

internal/convention/convention.go

@@ -181,6 +181,49 @@ var conventions = map[string]Convention{
 			},
 		},
 	},
+	// slidev disables the eight default-on rules that produce false
+	// positives on Slidev presentation Markdown files. Slidev uses
+	// `---` as a slide separator, which causes heading rules to fire
+	// across slide boundaries: heading level restarts per slide,
+	// the same H1 title may appear on multiple slides, layout blocks
+	// are parsed as setext headings, emphasis stands in for headings,
+	// and layout-only slides have no body text. The eight disabled
+	// rules are: heading-style (MDS002), heading-increment (MDS003),
+	// first-line-heading (MDS004), no-duplicate-headings (MDS005),
+	// blank-line-around-headings (MDS013),
+	// no-trailing-punctuation-in-heading (MDS017),
+	// no-emphasis-as-heading (MDS018), and empty-section-body (MDS030).
+	//
+	// Flavor is FlavorAny: Slidev authors may render with GFM,
+	// CommonMark, or any other flavor, and the convention must not
+	// force a flavor change. The convention does not enable
+	// markdown-flavor (MDS034); the loader skips the flavor-conflict
+	// guard for a convention whose flavor is FlavorAny.
+	//
+	// Parser-level handling of `---` as a page separator is out of
+	// scope for the disabled rules above.
+	//
+	// Beyond silencing false positives, the convention enables
+	// slide-structure (MDS073): a Slidev-aware rule that adds checks
+	// the built-in rules cannot express — unmatched ::slot:: markers,
+	// unknown layouts, missing layout-required fields, and typo'd
+	// per-slide frontmatter keys. MDS073 is opt-in (off by default),
+	// so the convention is what turns it on for decks.
+	"slidev": {
+		Name:   "slidev",
+		Flavor: FlavorAny,
+		Rules: map[string]RulePreset{
+			"heading-style":                      {Enabled: false},
+			"heading-increment":                  {Enabled: false},
+			"first-line-heading":                 {Enabled: false},
+			"no-duplicate-headings":              {Enabled: false},
+			"blank-line-around-headings":         {Enabled: false},
+			"no-trailing-punctuation-in-heading": {Enabled: false},
+			"no-emphasis-as-heading":             {Enabled: false},
+			"empty-section-body":                 {Enabled: false},
+			"slide-structure":                    {Enabled: true},
+		},
+	},
 	// 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

internal/convention/convention_test.go

@@ -244,13 +244,48 @@ func TestLookup_UnknownListsUserAndBuiltin(t *testing.T) {
 	assert.Contains(t, err.Error(), "portable", "error must list built-in name")
 }
 
+func TestLookup_Slidev(t *testing.T) {
+	c, err := Lookup("slidev", nil)
+	require.NoError(t, err)
+	assert.Equal(t, "slidev", c.Name)
+	assert.Equal(t, FlavorAny, c.Flavor)
+
+	disabledRules := []string{
+		"heading-style",
+		"heading-increment",
+		"first-line-heading",
+		"no-duplicate-headings",
+		"blank-line-around-headings",
+		"no-trailing-punctuation-in-heading",
+		"no-emphasis-as-heading",
+		"empty-section-body",
+	}
+	for _, rule := range disabledRules {
+		p, ok := c.Rules[rule]
+		if assert.True(t, ok, "slidev convention must mention rule %q", rule) {
+			assert.False(t, p.Enabled, "slidev convention must disable rule %q", rule)
+		}
+	}
+
+	// Beyond the eight disabled rules, slidev enables the opt-in
+	// slide-structure rule (MDS073) — the additive Slidev check.
+	ss, ok := c.Rules["slide-structure"]
+	if assert.True(t, ok, "slidev convention must mention slide-structure") {
+		assert.True(t, ss.Enabled, "slidev convention must enable slide-structure")
+	}
+
+	require.Len(t, c.Rules, len(disabledRules)+1,
+		"slidev convention rule count drifted")
+}
+
 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", "gomarklint-parity", "mado-parity", "markdownlint-parity",
 		"no-llm-tells", "obsidian", "plain", "portable", "rumdl-parity",
+		"slidev",
 	}, names)
 }
 

internal/integration/perrule_bench_test.go

@@ -315,6 +315,7 @@ var perRuleAllocCeiling = map[string]float64{
 	"MDS071": 4,   // required-frontmatter: 0 allocs (inert without fields)
 	// MDS072 (external-link-check) is network-bound and excluded from
 	// this gate via isNetworkBound; it has no alloc ceiling here.
+	"MDS073": 4, // slide-structure: 0 allocs (inert without slide markers)
 }
 
 // init pins MDS043's allocs ceiling from the build-tagged

internal/integration/rules_test.go

@@ -76,6 +76,7 @@ import (
 	_ "github.com/jeduden/mdsmith/internal/rules/samefileanchor"
 	_ "github.com/jeduden/mdsmith/internal/rules/singleh1"
 	_ "github.com/jeduden/mdsmith/internal/rules/singletrailingnewline"
+	_ "github.com/jeduden/mdsmith/internal/rules/slidevstructure"
 	_ "github.com/jeduden/mdsmith/internal/rules/tableformat"
 	_ "github.com/jeduden/mdsmith/internal/rules/tablereadability"
 	_ "github.com/jeduden/mdsmith/internal/rules/toc"

internal/integration/testdata/rule_walk_audit.json

@@ -779,5 +779,16 @@
     "is_node_checker": false,
     "uses_ast_walk": true,
     "reads_file_ast": true
+  },
+  {
+    "id": "MDS073",
+    "name": "slide-structure",
+    "category": "A-no-skipping",
+    "nil_ast_safe": true,
+    "code_block_sensitive": false,
+    "fired": true,
+    "is_node_checker": false,
+    "uses_ast_walk": false,
+    "reads_file_ast": false
   }
 ]