schema: address fifth Copilot review round (plan 156)

Four review findings:

1. validate.go::step (wrong-level branch) used to call a
   `claimRun` helper that bypassed the run accounting, so a
   repeated matcher could be silently satisfied by a single
   wrong-level occurrence. Route wrong-level matches through
   `claimMatch` so consumed / digitsSeen update normally and
   `repeat.min` + `sequential` still fire. Drop the obsolete
   `claimRun` helper. Test:
   TestPlan156_WrongLevelMatchCountsTowardRepeat.

2. validate.go::claimLateScope + claimOutOfOrder emit an
   explicit "matched 1 times, required at least N (out-of-order
   recovery only counts the first occurrence)" diagnostic when
   the late-claimed scope has `repeat.min > 1`. The in-order
   matchScope path remains the canonical cardinality surface;
   this keeps the contract enforced on the recovery path
   without re-implementing the full run-matcher there. Test:
   TestPlan156_LateClaimFlagsRepeatMin.

3. test_helpers_test.go: literalScope's doc-comment used to
   point at a nonexistent `matcherScope` helper. Rewrite to
   describe the intended call-site convention (tests with regex
   metacharacters construct the `Scope{Matcher: ...}` literal
   directly).

4. docs/guides/schemas.md: the schemas guide still described
   `regex:` as a CUE raw-interpolation string even though the
   reference page was corrected. Align the guide with the
   helper-only resolver.

https://claude.ai/code/session_012GGH62fZUzLuzP8T4ocGkJ

Author: claude

docs/guides/schemas.md

@@ -91,10 +91,13 @@ takes one of three shapes:
   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.
+  required; the body is a Go RE2 pattern that
+  accepts two interpolation references —
+  `\#(digits)` and `\#(fmvar(name))`. `repeat:`
+  bounds the run; `sequential:` (with `digits`)
+  asserts ordering. See the
+  [section-schema reference](../reference/section-schema.md)
+  for the full grammar.
 
 ### The matcher mapping
 

internal/schema/plan156_acceptance_test.go

@@ -389,6 +389,78 @@ func TestPlan156_OptionalSpecificClaimsOwnSlot(t *testing.T) {
 			"a broad `.+` matcher must not absorb it")
 }
 
+// TestPlan156_LateClaimFlagsRepeatMin regresses a Copilot
+// finding: when a repeated scope (`repeat.min > 1`) appears
+// out-of-order with only one occurrence, the late-claim
+// recovery path must still surface a "required at least N"
+// diagnostic so the cardinality contract is enforced.
+func TestPlan156_LateClaimFlagsRepeatMin(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{"min": 2},
+			}},
+		},
+	}
+	sch, err := ParseInline(raw, "kind x")
+	require.NoError(t, err)
+	// B appears once before A — out of order, and only one
+	// occurrence so the repeat.min is not satisfied.
+	doc := newDocFile(t, "doc.md",
+		"# T\n\n## B\n\nx\n\n## A\n\ny\n")
+	diags := Validate(doc, sch, nil, false, makeDiagForTest)
+	var card bool
+	for _, d := range diags {
+		if strings.Contains(d.Message, "required at least 2") {
+			card = true
+		}
+	}
+	assert.True(t, card,
+		"the late-claim path must flag the repeat.min shortfall")
+}
+
+// TestPlan156_WrongLevelMatchCountsTowardRepeat regresses a
+// Copilot finding: a wrong-level match used to go through a
+// claimRun helper that did not update consumed/digits, so a
+// repeated matcher could be silently satisfied by a single
+// wrong-level occurrence without `repeat.min` or `sequential`
+// enforcement. The path now routes through claimMatch so the
+// run accounting still fires.
+func TestPlan156_WrongLevelMatchCountsTowardRepeat(t *testing.T) {
+	raw := map[string]any{
+		"sections": []any{
+			map[string]any{"heading": "Outer", "sections": []any{
+				map[string]any{
+					"heading": map[string]any{
+						"regex":  "Inner",
+						"repeat": map[string]any{"min": 2},
+					},
+				},
+			}},
+		},
+	}
+	sch, err := ParseInline(raw, "kind x")
+	require.NoError(t, err)
+	// Outer at H2; only one Inner at H2 (wrong level — expected
+	// H3). The wrong-level match counts as one occurrence, so the
+	// run accounting must emit "matched 1 times, required at
+	// least 2".
+	doc := newDocFile(t, "doc.md",
+		"# T\n\n## Outer\n\n## Inner\n\nx\n")
+	diags := Validate(doc, sch, nil, false, makeDiagForTest)
+	var shortRun bool
+	for _, d := range diags {
+		if strings.Contains(d.Message, "required at least 2") {
+			shortRun = true
+		}
+	}
+	assert.True(t, shortRun,
+		"wrong-level match must contribute to the run's count "+
+			"so repeat.min still fires")
+}
+
 // TestPlan156_RejectsInvalidFmvarPath regresses a Copilot
 // finding: `fmvar(name)` accepted any argument string at parse
 // time, so a typo like `fmvar(my-key)` (unquoted hyphenated key)

internal/schema/plan156_coverage_test.go

@@ -58,15 +58,14 @@ func TestDisplayHeading_Branches(t *testing.T) {
 	assert.Equal(t, "", displayHeading(Scope{Preamble: true}))
 }
 
-// TestClaimRun_WrongLevelMatchWithChildren covers the branch of
-// claimRun that recurses into sc.Sections after a wrong-level
-// match: an outer scope whose nested children must still be
-// validated even when the outer heading appeared at a shallower
-// level than expected.
-func TestClaimRun_WrongLevelMatchWithChildren(t *testing.T) {
+// TestWrongLevelMatch_RecursesIntoChildren covers the branch of
+// claimMatch reached via the shallower-than-expected heading
+// path: a scope whose nested children must still be validated
+// even when the outer heading appeared at the wrong level.
+func TestWrongLevelMatch_RecursesIntoChildren(t *testing.T) {
 	// Schema: Outer at H3 (because of an outer wrapper), Inner at
 	// H4. Doc emits Outer at H2 (shallower than expected H3).
-	// claimRun recurses into Inner's checks; the missing-Inner
+	// claimMatch recurses into Inner's checks; the missing-Inner
 	// diagnostic surfaces from the nested validateScopes call.
 	raw := map[string]any{
 		"sections": []any{
@@ -98,14 +97,15 @@ func TestClaimRun_WrongLevelMatchWithChildren(t *testing.T) {
 		}
 	}
 	assert.True(t, missingInner,
-		"claimRun's children-recurse branch must validate nested sections")
+		"the children-recurse branch must validate nested sections")
 }
 
-// TestClaimRun_WrongLevelMatch covers claimRun, which fires when
-// matchScope sees a shallower-than-expected heading that still
-// matches the matcher: the level-mismatch diagnostic is appended
-// and the run is claimed.
-func TestClaimRun_WrongLevelMatch(t *testing.T) {
+// TestWrongLevelMatch_EmitsLevelDiag covers the wrong-level
+// match path: matchScope sees a shallower-than-expected heading
+// that still matches the matcher, claimMatch emits the
+// level-mismatch diagnostic, and the consumed/digits state is
+// updated so repeat.min / sequential still apply.
+func TestWrongLevelMatch_EmitsLevelDiag(t *testing.T) {
 	// Nested schema: outer expects H2, inner expects H3. The doc
 	// emits the inner heading at H2 (shallower than expected).
 	raw := map[string]any{
@@ -129,7 +129,8 @@ func TestClaimRun_WrongLevelMatch(t *testing.T) {
 			level = true
 		}
 	}
-	assert.True(t, level, "claimRun should emit the level-mismatch diagnostic")
+	assert.True(t, level,
+		"the wrong-level match path must emit the level-mismatch diagnostic")
 }
 
 // TestSequentialDiagMessage_NonInteger covers the parse-error path

internal/schema/test_helpers_test.go

@@ -4,10 +4,12 @@ package schema
 // going through the parser. Used by unit tests that exercise the
 // validator's branches directly.
 
-// literalScope returns a required-once scope matching the literal
-// text. The bare string is treated as plain text (no regex
-// metacharacters are honoured); use matcherScope for an explicit
-// regex.
+// literalScope returns a required-once scope whose Matcher.Regex
+// is the input text verbatim. Test inputs use plain alphanumeric
+// heading text where regex metacharacters and the source string
+// coincide; tests that need a real regex should construct the
+// `Scope{Matcher: &Matcher{...}}` literal directly so the intent
+// is obvious at the call site.
 func literalScope(text string) Scope {
 	return Scope{
 		Heading: text,

internal/schema/validate.go

@@ -241,16 +241,29 @@ func claimLateScope(
 	docHeads []DocHeading, docIdx int, claimed map[int]bool,
 	docFM map[string]any, mkDiag MakeDiag,
 ) (int, []lint.Diagnostic) {
+	sc := scopes[idx]
 	dh := docHeads[docIdx]
 	diags := []lint.Diagnostic{mkDiag(f.Path, dh.Line,
 		fmt.Sprintf(
 			"section %q out of order: expected before this position",
 			formatHeading(dh.Level, dh.Text)))}
+	// The late-claim path only consumes one heading. A repeated
+	// scope (`repeat.min > 1`) needs an explicit cardinality
+	// diagnostic so the contract is still enforced for the
+	// out-of-order recovery case.
+	if sc.Matcher != nil && sc.Matcher.Repeat.Min > 1 {
+		diags = append(diags, mkDiag(f.Path, dh.Line,
+			fmt.Sprintf(
+				"section %q matched 1 times, required at least %d "+
+					"(out-of-order recovery only counts the first occurrence)",
+				formatHeading(expectedLevel, displayHeading(sc)),
+				sc.Matcher.Repeat.Min)))
+	}
 	claimed[idx] = true
 	docIdx++
-	if len(scopes[idx].Sections) > 0 {
+	if len(sc.Sections) > 0 {
 		newIdx, childDiags := validateScopes(
-			f, scopes[idx].Sections, scopes[idx].Closed,
+			f, sc.Sections, sc.Closed,
 			docHeads, docIdx, expectedLevel+1, docFM, mkDiag)
 		diags = append(diags, childDiags...)
 		docIdx = newIdx
@@ -405,11 +418,12 @@ func (s *matchRun) step(docHeads []DocHeading, docIdx int) (bool, int, bool) {
 	dh := docHeads[docIdx]
 	if dh.Level < s.expectedLevel {
 		if matched, captured := matchHeading(sc.Matcher, dh, s.docFM); matched {
-			newIdx, runDiags := claimRun(
-				s.f, sc, s.idx, s.expectedLevel, docHeads, docIdx,
-				s.claimed, s.docFM, s.mkDiag, captured)
-			s.diags = append(s.diags, runDiags...)
-			return true, newIdx, true
+			// A shallower-than-expected heading that still matches
+			// the matcher counts toward the run's consumed/digits
+			// state — claimMatch emits the level-mismatch
+			// diagnostic on its own. Returning done=false lets the
+			// outer loop continue scanning for additional matches.
+			return false, s.claimMatch(docHeads, docIdx, captured), false
 		}
 		return true, docIdx, s.consumed > 0
 	}
@@ -494,28 +508,6 @@ func (s *matchRun) handleNonMatch(docHeads []DocHeading, docIdx int) (bool, int,
 	return false, docIdx + 1, false
 }
 
-// claimRun handles a wrong-level match for a matcher that consumes
-// exactly one heading: emit the level-mismatch diagnostic, mark
-// the scope as claimed, and recurse into the matched scope's
-// children.
-func claimRun(
-	f *lint.File, sc Scope, idx, expectedLevel int,
-	docHeads []DocHeading, docIdx int, claimed map[int]bool,
-	docFM map[string]any, mkDiag MakeDiag, _ string,
-) (int, []lint.Diagnostic) {
-	diags := levelDiagIfNeeded(f, docHeads[docIdx], expectedLevel, mkDiag)
-	claimed[idx] = true
-	docIdx++
-	if len(sc.Sections) > 0 {
-		newIdx, childDiags := validateScopes(
-			f, sc.Sections, sc.Closed, docHeads, docIdx,
-			expectedLevel+1, docFM, mkDiag)
-		diags = append(diags, childDiags...)
-		docIdx = newIdx
-	}
-	return docIdx, diags
-}
-
 // laterScopeMatches reports whether dh matches any later scope in
 // the same parent window that is more specific than a broad
 // matcher. Used by the per-scope walkers (rules, content,
@@ -617,6 +609,17 @@ func claimOutOfOrder(
 			formatHeading(dh.Level, dh.Text),
 			formatHeading(expectedLevel, displayHeading(sc))))}
 	diags = append(diags, levelDiagIfNeeded(f, dh, expectedLevel, mkDiag)...)
+	// The out-of-order claim only consumes one heading; a repeated
+	// late scope (`repeat.min > 1`) needs an explicit cardinality
+	// diagnostic so the contract is enforced even on recovery.
+	if ooSc.Matcher != nil && ooSc.Matcher.Repeat.Min > 1 {
+		diags = append(diags, mkDiag(f.Path, dh.Line,
+			fmt.Sprintf(
+				"section %q matched 1 times, required at least %d "+
+					"(out-of-order recovery only counts the first occurrence)",
+				formatHeading(expectedLevel, displayHeading(ooSc)),
+				ooSc.Matcher.Repeat.Min)))
+	}
 	claimed[ooIdx] = true
 	docIdx++
 	if len(ooSc.Sections) > 0 {