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

Plan 156 collapses the section-entry vocabulary to one
discriminator (`heading:` — null, string, or mapping) with a
single matcher (`regex:` as a Go RE2 body with `\#(digits)` and
`\#(fmvar(name))` helpers) and one cardinality field
(`repeat: { min, max }`). Hard cutover: `aliases:`, `required:`,
`{unlisted: true}`, scope-level `repeats:`/`sequential:`/
`min:`/`max:`, and `require.filename:` all parse-error with a
"removed; see plan 156" diagnostic naming the replacement.

Core changes:
- internal/schema: new Matcher / Repeat structs, parse_inline.go
  / parse_file.go rewritten for the new shape, matcher.go
  centralises RE2 compilation with a bounded cache keyed on the
  pattern plus a frontmatter fingerprint (collision-safe via
  strconv.Quote).
- validate.go: matchScope state machine (step / claimMatch /
  handleNonMatch / flagExtrasBeyondMax / finishRun) drives
  contiguous-run claiming with min/max enforcement, broad-and-
  after-min yield, out-of-order recovery, and non-contiguous
  flagging via claimedScopeMatches (claimCounts tracks per-scope
  occurrences so overlapping matchers don't inflate counts).
- ScopeRunIndices helper shared with validate_content.go,
  acronyms.go's walkRanges, and requiredstructure/scope_rules.go
  so per-scope walkers honour the same run / yield semantics.
- acronyms.go walkRanges surfaces the matched heading text so
  scope-name allowlists work with disjunctive regexes
  (`Symptoms|Indicators` + `scope: ["Indicators"]`).

Config and fixtures:
- .mdsmith.yml inline schemas migrated to the new shape.
- .mdsmith.pinned.yml restates the same inline schemas in the
  pre-156 form so the mdsmith-fixed-version CI gate (pinned at
  v0.15.0) can lint the tree via `-c`; merge-queue.yml swaps it
  in over .mdsmith.yml with `git update-index --skip-worktree`
  to keep the worktree clean for merge-queue-action's git ops.
- MDS020 good/bad fixtures updated to the new shape.
- docs/guides/schemas.md and docs/reference/section-schema.md
  rewritten; the `aliases: [A, B]` → `regex: 'A|B'` row sits in
  prose because GFM's pipe-escape inside code spans renders
  inconsistently.
- Reference acknowledges that MDS020's file-schema path still
  uses the legacy parseSchema pipeline; the new parser is the
  in-memory shape behind inline schemas.

Regression coverage (TestPlan156_*):
  RegexMatchesRenderedPlainText, DigitsCaptureSequential,
  FmvarInterpolates, RepeatBoundsEnforced,
  RepeatMaxEnforcedInOpenSchema, RejectsUnknownInterpHelper,
  RepeatYieldsToOptionalLaterScope, SequentialDiagOnPartialRun,
  FmFingerprintCollisionGuard, RepeatSpansDeeperHeadings,
  FlagExtrasBeyondMaxSkipsDeeper, RejectsMultipleDigitsInline,
  OptionalSpecificClaimsOwnSlot, FlagsExtrasMatchingClaimedScope,
  OutOfOrderSequentialDiagFires, OptionalYieldsToBroadFollower,
  ScopeRunStopsAtBoundary, FlagsExtrasInIterationStream,
  UnboundedRepeatDoesNotFlagAsExceeded,
  BroadMatcherYieldsBeforeMin, LateClaimFlagsRepeatMin,
  WrongLevelMatchCountsTowardRepeat, RejectsInvalidFmvarPath,
  OptionalMatcherSkipsTolerated, BroadRepeatYieldsAcronymScope,
  BroadRepeatYieldsToLaterScopeInPerScopeWalkers,
  RejectsMultipleNTokensProto, AcronymScopeOnRepeatedScope,
  ContentOnRepeatedScope, RulesOnRepeatedScope,
  AcronymScopeMatchesByHeadingText,
  OutOfOrderRunCountsAvailableMatches,
  NonContiguousClaimedScopeFlagged,
  LateClaimChildRecursionStopsAtParentLevel,
  OverlappingMatcherDoesNotInflateClaimCount.

https://claude.ai/code/session_012GGH62fZUzLuzP8T4ocGkJ

Co-authored-by: Claude <noreply@anthropic.com>

Author: jeduden

.github/copilot-instructions.md

@@ -94,7 +94,7 @@ row: "- [{summary}](../{filename})"
 - [Built-in Markdown conventions, the rule presets each one applies, and how user config layers on top via deep-merge.](../docs/reference/conventions.md)
 - [Glob pattern syntax across mdsmith config, directives, and CLI argument expansion, with the supported exclusion semantics for each surface.](../docs/reference/globs.md)
 - [Named field-type shortcuts for inline schema frontmatter values — the registered names, the canonical CUE each one resolves to, and example usage.](../docs/reference/schema-types.md)
-- [Section-schema reference: the entry-shape vocabulary used in inline `kinds.<name>.schema:` blocks and `proto.md` files. Covers the `heading:` discriminator, the `regex:` matcher (a CUE expression with `digits` and `fmvar` helpers), the `repeat: {min, max}` cardinality field, and the matching algorithm.](../docs/reference/section-schema.md)
+- [Section-schema reference for inline `kinds.<name>.schema:` blocks. Covers the `heading:` discriminator, the `regex:` matcher (a Go RE2 body with `\#(digits)` and `\#(fmvar(...))` helpers), the `repeat: {min, max}` cardinality field, and the matching algorithm. `proto.md` files are parsed into the same shape by the schema package, but MDS020's file-schema check still uses its legacy parser; see the proto.md section below for what is and is not migrated.](../docs/reference/section-schema.md)
 <?/catalog?>
 
 ### Development Workflow
@@ -224,6 +224,12 @@ layout](https://go.dev/doc/modules/layout):
   punctuation
 - Prefer returning errors over panicking
 
+#### Defensive Code
+
+Add a defensive branch only when you can drive it
+red/green. Write the failing test first. Then add
+the code that takes the branch.
+
 #### Test Fixtures
 
 Rule test fixtures live in

.github/workflows/ci.yml

@@ -182,7 +182,13 @@ jobs:
         with:
           persist-credentials: false
       - uses: ./.github/actions/setup-mdsmith-pinned-version
-      - run: mdsmith check .
+      # Plan 156 reshaped the inline schema vocabulary; the pinned
+      # baseline binary (v0.15.0) cannot parse the new form in
+      # .mdsmith.yml. .mdsmith.pinned.yml restates the inline
+      # schemas in the pre-156 shape so the pinned binary can lint
+      # the tree. Delete this -c flag (and .mdsmith.pinned.yml)
+      # once setup-mdsmith-pinned-version advances past v0.15.0.
+      - run: mdsmith check -c .mdsmith.pinned.yml .
 
   demo:
     uses: ./.github/workflows/record-demo.yml

.github/workflows/merge-queue.yml

@@ -36,6 +36,24 @@ jobs:
           persist-credentials: false
 
       - uses: ./.github/actions/setup-mdsmith-pinned-version
+      # The pinned merge driver / pre-merge-commit hook installer
+      # reads .mdsmith.yml to derive merge-driver attribute globs;
+      # the merge driver's `run` step (invoked by git during a
+      # merge) does the same. v0.15.0 cannot parse plan 156's
+      # inline schema vocabulary, so the workflow swaps in
+      # .mdsmith.pinned.yml — a config restated in the pre-156
+      # shape — for the entire job lifetime. `update-index
+      # --skip-worktree` keeps the swap invisible to git so the
+      # later checkout/merge operations performed by
+      # merge-queue-action don't trip "local changes would be
+      # overwritten" or try to restore the new-shape config
+      # mid-merge. Remove this block once
+      # setup-mdsmith-pinned-version advances past v0.15.0 (and
+      # delete .mdsmith.pinned.yml).
+      - name: Use pinned-binary config for merge driver
+        run: |
+          cp .mdsmith.pinned.yml .mdsmith.yml
+          git update-index --skip-worktree .mdsmith.yml
       - name: Install mdsmith merge driver and pre-merge-commit hook
         run: |
           mdsmith merge-driver install