schema: unify section entry shape under heading: discriminator (plan 156)

Collapse the section-entry vocabulary to a single discriminator
(`heading:` — null, string, or mapping) with one matcher (`regex:`,
a CUE raw-interpolation string with `digits` and `fmvar(name)`
helpers) and one cardinality field (`repeat: { min, max }`).
`sequential:` lives inside the mapping. The schema-level
`require.filename:` flattens to top-level `filename:`.

Removed keys parse-error with a "removed; see plan 156" diagnostic
naming the replacement:
- `required:` → `repeat: { min: 0, max: 1 }` (or omit)
- `aliases:` → encode disjunction in `regex:`
- scope-level `repeats:`/`sequential:`/`min:`/`max:` → `heading.repeat`
- `heading: { unlisted: true }` → `heading: { regex: '.+', repeat: { min: 0 } }`
- top-level `require:` → top-level `filename:`

The five inline kinds in `.mdsmith.yml` and the MDS020 fixtures are
rewritten to the new shape. The legacy proto.md heading-row tokens
(`# ?`, `## ...`, `## Step {n}`, `## {id}`) desugar to the same
matcher shape the inline form produces. `mdsmith check .` and
`go tool golangci-lint run` both pass clean.

https://claude.ai/code/session_012GGH62fZUzLuzP8T4ocGkJ

Author: claude

.mdsmith.yml

@@ -328,9 +328,9 @@ kinds:
       closed: false
       sections:
         - heading: null
-          required: false
         - heading:
-            unlisted: true
+            regex: '.+'
+            repeat: { min: 0 }
   cli-command:
     schema:
       frontmatter:
@@ -339,9 +339,9 @@ kinds:
       closed: false
       sections:
         - heading: null
-          required: false
         - heading:
-            unlisted: true
+            regex: '.+'
+            repeat: { min: 0 }
   release-channel:
     schema:
       frontmatter:
@@ -353,9 +353,9 @@ kinds:
       closed: false
       sections:
         - heading: null
-          required: false
         - heading:
-            unlisted: true
+            regex: '.+'
+            repeat: { min: 0 }
   secret-rotation:
     schema:
       frontmatter:
@@ -371,23 +371,22 @@ kinds:
       closed: false
       sections:
         - heading: null
-          required: false
         - heading:
-            unlisted: true
+            regex: '.+'
+            repeat: { min: 0 }
   audit-log:
     schema:
       frontmatter:
         title: 'string & != ""'
         "summary?": 'string'
         audit-from: '=~"^[0-9a-f]{7,40}$"'
-      require:
-        filename: "architecture-audit.md"
+      filename: "architecture-audit.md"
       closed: false
       sections:
         - heading: null
-          required: false
         - heading:
-            unlisted: true
+            regex: '.+'
+            repeat: { min: 0 }
   website-page:
     # Hugo content pages under website/content/. Scoped to the
     # top level only (no **) so the kind covers hand-authored
@@ -410,9 +409,9 @@ kinds:
       closed: false
       sections:
         - heading: null
-          required: false
         - heading:
-            unlisted: true
+            regex: '.+'
+            repeat: { min: 0 }
     rules:
       first-line-heading: false
       heading-increment: false

PLAN.md

@@ -84,7 +84,7 @@ footer: |
 | 154 | ✅     | sonnet | [arch-fix: extract cross-rule helpers](plan/154_arch-fix-rule-helper-extraction.md)                                       |
 | 155 | ✅     | sonnet | [arch-fix: relocate convention types out of markdownflavor](plan/155_arch-fix-convention-config-ownership.md)             |
 | 156 | 🔲     | opus   | [Composable required-structure schemas across multiple kinds](plan/156_kind-schema-composition.md)                        |
-| 156 | 🔲     | opus   | [Section schema — unify entry shape under `heading:` discriminator](plan/156_schema-entry-unification.md)                 |
+| 156 | ✅     | opus   | [Section schema — unify entry shape under `heading:` discriminator](plan/156_schema-entry-unification.md)                 |
 | 157 | 🔳     | sonnet | [Catalog filter by front matter property](plan/157_catalog-where-filter.md)                                               |
 | 160 | 🔲     | sonnet | [Claude Code plugin extensions — skills, agents, hooks](plan/160_claude-code-skills-agents-hooks.md)                      |
 | 161 | 🔲     | sonnet | [Expose rule maintainability patterns via CLI help and LSP](plan/161_rule-pattern-metadata.md)                            |

docs/guides/schemas.md

@@ -37,24 +37,20 @@ templated body content.
 kinds:
   rfc:
     schema:
+      filename: "RFC-[0-9][0-9][0-9][0-9].md"
       frontmatter:
         id: '=~"^RFC-[0-9]{4}$"'
         status: '"draft" | "ratified" | "deprecated"'
         authors: '[...string] & len(authors) >= 1'
-      require:
-        filename: "RFC-[0-9][0-9][0-9][0-9].md"
       closed: true
       sections:
         - heading: null
-          required: false
         - heading: "Overview"
-          required: true
         - heading: "Decision"
-          required: true
         - heading:
-            unlisted: true
+            regex: '.+'
+            repeat: { min: 0 }
         - heading: "References"
-          required: true
 ```
 
 The `frontmatter:` mapping reuses CUE expressions per
@@ -68,40 +64,83 @@ the ISO regex; see
 [Schema field types](../reference/schema-types.md)
 for the registered names and how they are matched.
 
-`require.filename:` is a glob the document basename
-must match.
+`filename:` is a glob the document basename must
+match. It sits at the top of the schema block (no
+`require:` wrapper).
 
 `closed: true` makes the scope strict — unlisted
 headings produce a diagnostic. `closed: false` (the
 default) tolerates unlisted headings between listed
-sections.
+sections. `closed:` is only meaningful when the
+schema declares `sections:`; setting it on a
+frontmatter-only kind is a parse error.
 
-### The `heading:` field
+### The `heading:` discriminator
 
 Every section-array entry sets `heading:`. The value
 takes one of three shapes:
 
-- **string** — literal heading text. Example:
-  `heading: "Overview"`. The doc must have a heading
-  whose text equals that string (or an alias).
 - **`null`** — the preamble: content from line 1 up
   to the first heading. Only valid as the first entry
-  in a section list. Carries `required:` /
-  `closed:` / `rules:` for that range; cannot carry
-  `aliases:` or nested `sections:`.
-- **mapping** — typed match. Today only
-  `{unlisted: true}` is accepted, declaring a slot
-  that absorbs zero or more sections the schema did
-  not list by name. The slot is positional, but
-  out-of-order detection still claims a heading whose
-  text matches a later listed scope, so the slot only
-  absorbs truly-unlisted sections. Slots are
-  positional-only — they cannot carry `aliases:`,
-  `sections:`, `rules:`, `closed:`, or `required:`;
-  the parser rejects those keys. Future work can
-  extend the mapping form with shapes like
-  `{any: true}` (match any heading text) or
-  `{pattern: "..."}` (match a placeholder pattern).
+  in a section list. Carries `closed:` / `rules:` /
+  `content:` for that range; rejects `sections:`.
+- **string** — sugar for a literal match. The string
+  is regex-escaped and used as the matcher's pattern,
+  so `heading: "(WIP)"` matches a heading whose text
+  is exactly `(WIP)` with the parens taken literally.
+  Cardinality is one.
+- **mapping** — the full form:
+  `{ regex, repeat?, sequential? }`. `regex:` is
+  required and is the body of a CUE
+  raw-interpolation string. `repeat:` bounds the
+  run; `sequential:` (with the `digits` helper)
+  asserts ordering.
+
+### The matcher mapping
+
+```yaml
+sections:
+  - heading:
+      regex: 'Step \#(digits)'
+      repeat: { min: 1, max: 5 }
+      sequential: true
+    sections: [...]
+    content: [...]
+  - heading:
+      regex: '\#(fmvar(id)): \#(fmvar(name))'
+  - heading:
+      regex: '.+'
+      repeat: { min: 0 }
+```
+
+`regex:` is whole-string anchored against the
+heading's rendered plain text (inline emphasis stripped,
+link wrappers unwrapped, code-span backticks dropped).
+Backslashes pass through to RE2; interpolation uses
+`\#(expr)`. Two helpers are in scope:
+
+- **`digits`** — expands to the named capture
+  `(?P<n>[0-9]+)`. One per pattern. With
+  `sequential: true` the validator asserts the
+  captured numbers are strictly increasing without
+  gaps.
+- **`fmvar(name)`** — looks up the document's
+  frontmatter field `name`, regex-escapes its value,
+  and substitutes it.
+
+`repeat:` bounds how many consecutive matching
+headings the matcher claims. Omitting `repeat:`
+means exactly one; `{ min: 0 }` is zero-or-more;
+`{ min: 0, max: 1 }` is optional; `{ min: 1 }` is
+one-or-more; bounded forms enforce both bounds.
+`repeat: { max: 0 }` and `repeat: { min > max }`
+each parse-error.
+
+The wildcard-slot shape — `regex: '.+'` with
+`repeat: { min: 0 }` — is positional: it absorbs
+zero or more unlisted sections at its slot. A
+heading whose text matches a later listed entry is
+claimed for that entry, not absorbed by the slot.
 
 ### Nested sections
 
@@ -112,29 +151,25 @@ expresses that as:
 
 ```yaml
 sections:
-  - heading: "Symptoms"
-    required: true
-    aliases: ["Indicators"]
+  - heading:
+      regex: 'Symptoms|Indicators'
   - heading: "Diagnosis"
-    required: true
     sections:
       - heading: "Step"
-        required: true
         sections:
           - heading: "Check"
-            required: true
           - heading: "Expected"
-            required: true
-          - heading: "If different"
-            required: false
-  - heading: "References"
-    required: false
+          - heading:
+              regex: 'If different'
+              repeat: { min: 0, max: 1 }
+  - heading:
+      regex: 'References'
+      repeat: { min: 0, max: 1 }
 ```
 
-`aliases:` lets a heading match alternate texts. A
-required scope that lists `aliases: ["Indicators"]`
-matches both `## Symptoms` and `## Indicators` in a
-document.
+A scope that accepts alternate heading texts encodes
+the disjunction in its regex: `regex: 'A|B'` matches
+a heading whose text is `A` or `B`.
 
 ### Section content
 
@@ -179,10 +214,10 @@ ordered/min/max) emit their own diagnostics but
 still consume the slot. Missing required entries
 anchor at the section's heading line.
 
-`content:` is not accepted on slot scopes
-(`heading: {unlisted: true}`) or on the `?`
-wildcard heading — the parser rejects those
-shapes today.
+`content:` is rejected on a slot scope (the
+wildcard-slot shape has no fixed identity to
+constrain). Set `content:` only on entries that
+match named sections.
 
 ### Per-scope rule overrides
 
@@ -197,7 +232,6 @@ document" without scattering glob overrides.
 ```yaml
 sections:
   - heading: "Decision"
-    required: true
     rules:
       paragraph-readability:
         max-index: 12.0
@@ -364,9 +398,11 @@ filename: "MDS*-*.md"
 The `# ?` (or `# {field}: {field}` form) acts as the
 title placeholder. `## ...` rows mark wildcard slots.
 Front-matter keys map directly to CUE expressions.
-`<?require?>` declares the filename pattern. See
-[enforcing document structure](directives/enforcing-structure.md)
-for the full file-based reference.
+`<?require?>` declares the filename pattern. The
+heading-row tokens desugar to the same matcher
+shape the inline form uses; see the
+[section-schema reference](../reference/section-schema.md#protomd-file-syntax)
+for the row-by-row mapping.
 
 ## Choosing a source
 
@@ -394,6 +430,8 @@ mismatch`, and `out of order` mean.
 
 ## See also
 
+- [Section schema reference](../reference/section-schema.md)
+  — the entry-shape grammar in full.
 - [File kinds](file-kinds.md) — how kinds attach
   schemas (and other rule config) to file groups.
 - [Enforcing document structure with schemas](directives/enforcing-structure.md)

docs/reference/section-schema.md

@@ -10,16 +10,6 @@ summary: >-
 ---
 # Section schema
 
-> **Status: upcoming.** This page documents the
-> shape defined by
-> [plan 156](../../plan/156_schema-entry-unification.md).
-> It is not yet implemented. The current parser
-> accepts the older shape documented in the
-> [schema guide](../guides/schemas.md). When plan
-> 156 lands, this notice is removed and the guide
-> is rewritten to drop every reference to the old
-> shape.
-
 A **section schema** describes the heading
 structure mdsmith expects in a document. It
 pairs with frontmatter and filename constraints