schema: enforce repeat.max > 1 on out-of-order recovery

The earlier round restricted the "exceeds scope's allowed
occurrences" diagnostic to scopes with `max == 1` because the
boolean claim state can't distinguish "second of three allowed"
from a true excess. The reviewer flagged that this leaves
`max > 1` out-of-order extras unenforced: a schema [A, B max=2]
with doc [B, A, B, B] silently absorbs the third B in open
schemas.

Replace `claimedScopeMatches` with `claimedScopeExceeded`,
which counts same-level matches in the parent window up to and
including the current heading. The diagnostic fires only when
`count > max`, so two Bs are accepted, the third B is flagged.
The check still skips unbounded matchers and the in-order path
keeps using flagExtrasBeyondMax for its own enforcement.

Test: TestPlan156_BoundedMaxExceededOutOfOrder.

https://claude.ai/code/session_012GGH62fZUzLuzP8T4ocGkJ

Author: claude

internal/schema/plan156_acceptance_test.go

@@ -459,6 +459,41 @@ func TestPlan156_OutOfOrderSequentialDiagFires(t *testing.T) {
 			"the unenforced-sequential diagnostic")
 }
 
+// TestPlan156_BoundedMaxExceededOutOfOrder regresses a Copilot
+// finding: the recovery path used to skip already-claimed
+// scopes with `max > 1`, so a `repeat: { max: 2 }` scope
+// claimed out of order could silently absorb three or more
+// occurrences in open schemas. The trailing pass now counts
+// same-level matches in the parent window and flags the
+// excess (only) when count > max.
+func TestPlan156_BoundedMaxExceededOutOfOrder(t *testing.T) {
+	raw := map[string]any{
+		"sections": []any{
+			map[string]any{"heading": "A"},
+			map[string]any{"heading": map[string]any{
+				"regex":  "B",
+				"repeat": map[string]any{"max": 2},
+			}},
+		},
+	}
+	sch, err := ParseInline(raw, "kind x")
+	require.NoError(t, err)
+	// Doc: B (out of order), A, B, B. Three Bs total; max=2.
+	// The third B must be flagged.
+	doc := newDocFile(t, "doc.md",
+		"# T\n\n## B\n\nx\n\n## A\n\ny\n\n## B\n\nz\n\n## B\n\nw\n")
+	diags := Validate(doc, sch, nil, false, makeDiagForTest)
+	var exceededCount int
+	for _, d := range diags {
+		if strings.Contains(d.Message, "exceeds scope") {
+			exceededCount++
+		}
+	}
+	assert.Equal(t, 1, exceededCount,
+		"only the third B should be flagged as exceeding max=2 "+
+			"(the first two are within bounds)")
+}
+
 // TestPlan156_RejectsUserNamedCaptureN regresses a Copilot
 // finding: the matcher runtime reads the named capture `n` for
 // sequential ordering, but `regex:` is raw RE2 and a user

internal/schema/validate.go

@@ -220,12 +220,12 @@ func handleLeftoverHeadings(
 		// path absorbed. Surface it specifically as a max-exceeded
 		// diagnostic so the user sees which scope was over-filled
 		// rather than a generic "unexpected".
-		if idx := claimedScopeMatches(scopes, dh, claimed, docFM); idx >= 0 {
+		if idx := claimedScopeExceeded(
+			scopes, dh, claimed, docFM, docHeads, docIdx, expectedLevel); idx >= 0 {
 			sc := scopes[idx]
 			diags = append(diags, mkDiag(f.Path, dh.Line,
 				fmt.Sprintf(
-					"section %q exceeds scope %q's allowed occurrences "+
-						"(out-of-order recovery only counts one match)",
+					"section %q exceeds scope %q's allowed occurrences",
 					formatHeading(dh.Level, dh.Text),
 					formatHeading(expectedLevel, displayHeading(sc)))))
 			docIdx++
@@ -241,23 +241,21 @@ func handleLeftoverHeadings(
 	return docIdx, diags
 }
 
-// claimedScopeMatches returns the index of the first already-claimed
-// non-slot, non-preamble scope with `max == 1` that accepts dh, or
-// -1 when no such scope is a candidate. Used by
-// handleLeftoverHeadings to distinguish "max exceeded" from
-// generic "unexpected".
+// claimedScopeExceeded returns the index of the first already-
+// claimed non-slot, non-preamble scope whose matcher accepts dh
+// AND whose bounded `max` has been exceeded by the count of
+// same-level matching headings up to and including dhIdx — or
+// -1 when no such scope is over-filled.
 //
-// Only `max == 1` scopes are flagged because the recovery state
-// is a boolean claim and doesn't track how many occurrences were
-// already counted. For `max > 1` we can't tell whether the new
-// heading is the second of three allowed or a true excess
-// without re-running the run-matcher — false positives there
-// would be worse than the loss of specificity, so those cases
-// fall through to the generic unexpected handling. Unbounded
-// matchers (`max == 0`) are likewise excluded — they accept any
-// number of occurrences.
-func claimedScopeMatches(
-	scopes []Scope, dh DocHeading, claimed map[int]bool, docFM map[string]any,
+// Counting matches in the parent window (rather than tracking a
+// per-scope counter through the validator) lets the late/out-of-
+// order recovery path enforce `repeat.max > 1` without
+// false-positives at count <= max. Unbounded matchers
+// (`max == 0`) are excluded — they accept any number of
+// occurrences.
+func claimedScopeExceeded(
+	scopes []Scope, dh DocHeading, claimed map[int]bool,
+	docFM map[string]any, docHeads []DocHeading, dhIdx, expectedLevel int,
 ) int {
 	for i, sc := range scopes {
 		if !claimed[i] {
@@ -270,16 +268,40 @@ func claimedScopeMatches(
 			continue
 		}
 		_, max := sc.Matcher.Repeat.Bounds()
-		if max != 1 {
+		if max == 0 {
 			continue
 		}
-		if scopeMatchesHeading(sc, dh, docFM) {
+		if !scopeMatchesHeading(sc, dh, docFM) {
+			continue
+		}
+		count := countSameLevelMatches(sc, docHeads, expectedLevel, dhIdx, docFM)
+		if count > max {
 			return i
 		}
 	}
 	return -1
 }
 
+// countSameLevelMatches returns the number of headings in
+// docHeads[0..upToIdx] (inclusive) at expectedLevel that sc's
+// matcher accepts. Used to compute the occurrence count for the
+// max-exceeded check in the trailing-leftover pass.
+func countSameLevelMatches(
+	sc Scope, docHeads []DocHeading, expectedLevel, upToIdx int,
+	docFM map[string]any,
+) int {
+	count := 0
+	for j := 0; j <= upToIdx && j < len(docHeads); j++ {
+		if docHeads[j].Level != expectedLevel {
+			continue
+		}
+		if scopeMatchesHeading(sc, docHeads[j], docFM) {
+			count++
+		}
+	}
+	return count
+}
+
 // claimLateScope marks a late-arriving listed scope as claimed,
 // emits its out-of-order diagnostic, and recurses into the scope's
 // nested children so missing-required-section diagnostics still
@@ -567,12 +589,12 @@ func (s *matchRun) handleNonMatch(docHeads []DocHeading, docIdx int) (bool, int,
 	// 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 {
+	if idx := claimedScopeExceeded(
+		s.scopes, dh, s.claimed, s.docFM, docHeads, docIdx, s.expectedLevel); 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)",
+				"section %q exceeds scope %q's allowed occurrences",
 				formatHeading(dh.Level, dh.Text),
 				formatHeading(s.expectedLevel, displayHeading(sc)))))
 		return false, docIdx + 1, false