schema: flag in-stream extras + clarify proto.md migration state

Three review findings:

1. validate.go::handleNonMatch — when a doc heading doesn't
   match the current scope, `findOutOfOrderIdx` only looks at
   unclaimed later scopes. A schema [A, B] with doc [B, B, A]
   used to silently consume the second B (B already claimed
   out-of-order; A's matchScope walked past it). Consult
   `claimedScopeMatches` after the out-of-order check fails so
   the duplicate surfaces as "exceeds allowed occurrences".
   Test: TestPlan156_FlagsExtrasInIterationStream.

2. docs/reference/section-schema.md — the frontmatter summary
   and the proto.md section both implied `fmvar(...)` was a
   current proto.md feature. MDS020's file-schema check is
   still on the legacy parser, so `{field}` matches a
   wildcard run rather than resolving the document's
   frontmatter. Add a "Migration status" callout and reword
   the summary to scope the matcher promise to inline
   schemas.

3. docs/guides/schemas.md — the same caveat in the user-
   facing guide. Replace the "tokens desugar to the same
   matcher shape" wording with an explicit note that proto.md
   `{field}` is still a wildcard placeholder until the
   follow-up cutover lands.

https://claude.ai/code/session_012GGH62fZUzLuzP8T4ocGkJ

Author: claude

.github/copilot-instructions.md

@@ -78,7 +78,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 Go RE2 body 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

AGENTS.md

@@ -84,7 +84,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 Go RE2 body 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

CLAUDE.md

@@ -70,7 +70,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 Go RE2 body 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

docs/guides/schemas.md

@@ -401,11 +401,20 @@ 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. The
-heading-row tokens desugar to the same matcher
-shape the inline form uses; see the
+`<?require?>` declares the filename pattern.
+
+MDS020's file-schema check still routes through
+its legacy parser today: `{field}` in a proto.md
+heading row matches a non-empty run rather than
+resolving the document's frontmatter value via
+`fmvar(...)`. The schema package parses proto.md
+into the new Matcher shape (used by tests), and a
+follow-up plan will wire MDS020 through that
+parser. Until then, treat `{field}` in proto.md
+heading rows as a wildcard placeholder, not as a
+frontmatter substitution. The
 [section-schema reference](../reference/section-schema.md#protomd-file-syntax)
-for the row-by-row mapping.
+records the eventual mapping.
 
 ## Choosing a source
 

docs/reference/section-schema.md

@@ -1,13 +1,16 @@
 ---
 summary: >-
-  Section-schema reference: the entry-shape
-  vocabulary used in inline `kinds.<name>.schema:`
-  blocks and `proto.md` files. Covers the
+  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.
+  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.
 ---
 # Section schema
 
@@ -252,13 +255,24 @@ schema:
 
 ## `proto.md` file syntax
 
+> **Migration status.** MDS020's file-schema
+> check still uses the legacy `parseSchema`
+> pipeline today: `## ?` and `## ...` already
+> behave as wildcards, and `{field}` in a
+> heading row matches a non-empty run rather
+> than resolving the frontmatter value via
+> `fmvar(...)`. The mapping below is what the
+> schema package parses. Tests exercise it so a
+> follow-up cutover plan can wire MDS020
+> through without docs churn. Until then,
+> proto.md authors should treat `{field}` as a
+> wildcard, not a frontmatter substitution.
+
 Proto.md files use a literal-template surface
 distinct from the inline `regex:` form. Heading
 rows in the body act as the schema's
 `sections:` list. `{n}` and `{field}` survive
-here as template placeholders; they desugar to
-the same matcher the inline form produces with
-`digits` and `fmvar`.
+here as template placeholders.
 
 | Row syntax        | Equivalent inline entry                        |
 |-------------------|------------------------------------------------|

internal/schema/plan156_acceptance_test.go

@@ -459,6 +459,35 @@ func TestPlan156_OutOfOrderSequentialDiagFires(t *testing.T) {
 			"the unenforced-sequential diagnostic")
 }
 
+// TestPlan156_FlagsExtrasInIterationStream regresses a Copilot
+// finding: when a doc has [B, B, A] against schema [A, B], the
+// second B used to be silently consumed by handleNonMatch
+// (findOutOfOrderIdx skips claimed scopes, open schema → no
+// diag). The handler now consults claimedScopeMatches and
+// emits "exceeds allowed occurrences" for the duplicate.
+func TestPlan156_FlagsExtrasInIterationStream(t *testing.T) {
+	raw := map[string]any{
+		"sections": []any{
+			map[string]any{"heading": "A"},
+			map[string]any{"heading": "B"},
+		},
+	}
+	sch, err := ParseInline(raw, "kind x")
+	require.NoError(t, err)
+	doc := newDocFile(t, "doc.md",
+		"# T\n\n## B\n\nx\n\n## B\n\ny\n\n## A\n\nz\n")
+	diags := Validate(doc, sch, nil, false, makeDiagForTest)
+	var exceeded bool
+	for _, d := range diags {
+		if strings.Contains(d.Message, "exceeds scope") {
+			exceeded = true
+		}
+	}
+	assert.True(t, exceeded,
+		"the second B must be flagged as exceeding scope B's "+
+			"allowed occurrences, not silently consumed")
+}
+
 // TestPlan156_UnboundedRepeatDoesNotFlagAsExceeded regresses a
 // Copilot finding: claimedScopeMatches used to fire for any
 // claimed scope, including unbounded matchers (`max == 0`). A

internal/schema/validate.go

@@ -552,6 +552,22 @@ func (s *matchRun) handleNonMatch(docHeads []DocHeading, docIdx int) (bool, int,
 		s.diags = append(s.diags, ooDiags...)
 		return false, newIdx, false
 	}
+	// If dh matches a scope already claimed (in-order or
+	// out-of-order), it's an extra occurrence — surface it as
+	// "exceeds allowed occurrences" so the user sees which scope
+	// was over-filled. Without this, a sequence like [A, B] with
+	// doc [B, B, A] silently consumes the second B because
+	// findOutOfOrderIdx ignores claimed scopes.
+	if idx := claimedScopeMatches(s.scopes, dh, s.claimed, s.docFM); idx >= 0 {
+		sc := s.scopes[idx]
+		s.diags = append(s.diags, s.mkDiag(s.f.Path, dh.Line,
+			fmt.Sprintf(
+				"section %q exceeds scope %q's allowed occurrences "+
+					"(out-of-order recovery only counts one match)",
+				formatHeading(dh.Level, dh.Text),
+				formatHeading(s.expectedLevel, displayHeading(sc)))))
+		return false, docIdx + 1, false
+	}
 	if !s.allowExtra && s.closed {
 		sc := s.scopes[s.idx]
 		s.diags = append(s.diags, s.mkDiag(s.f.Path, dh.Line,