schema: address tenth Copilot review round (plan 156)

- validate.go: claimedScopeExceeded now consumes a parallel
  claimCounts map seeded by the matcher itself, eliminating
  the heading-rescan that double-counted yielded broad-matcher
  acceptances.
- acronyms.go: walkRanges callback surfaces the matched doc
  heading text. acronymRanges adds the heading text to the
  scope-name allowlist check so disjunctive regexes like
  `Symptoms|Indicators` align with intuitive scope config such
  as `scope: ["Indicators"]`; plan 156 dropped the scope-level
  aliases field, so the heading match keeps existing users from
  having to mirror the regex body verbatim.
- plan156_acceptance_test.go: regression for the heading-text
  scope match (TestPlan156_AcronymScopeMatchesByHeadingText).

https://claude.ai/code/session_012GGH62fZUzLuzP8T4ocGkJ

Author: claude

internal/schema/acronyms.go

@@ -97,13 +97,21 @@ func acronymRanges(f *lint.File, sch *Schema, scope []string, docFM map[string]a
 
 	var out []lineRange
 	walkRanges(sch.Sections, body, rootLevel, 1, len(f.Lines)+1, docFM,
-		func(sc Scope, start, end int) {
+		func(sc Scope, headingText string, start, end int) {
 			// walkRanges already skips preamble and slot scopes, so
 			// any sc reaching here has a literal Matcher. Match the
-			// scope label or the matcher's regex against the
-			// configured scope-name allowlist; plan 156 removed the
-			// scope-level `aliases:` field, so disjunctive scope
-			// names live in the regex body (`A|B`).
+			// scope-name allowlist against (a) the actual heading
+			// text in the document, (b) the schema label, and (c)
+			// the raw regex body. The document-heading match keeps
+			// disjunctive regexes like `Symptoms|Indicators` aligned
+			// with intuitive `acronyms.scope: ["Indicators"]` config;
+			// plan 156 removed the scope-level `aliases:` field, so
+			// without (a) users would have to mirror the regex body
+			// verbatim.
+			if matchSet[headingText] {
+				out = append(out, lineRange{Start: start, End: end})
+				return
+			}
 			if matchSet[sc.Heading] {
 				out = append(out, lineRange{Start: start, End: end})
 				return
@@ -127,7 +135,7 @@ func walkRanges(
 	scopes []Scope, heads []DocHeading,
 	expectedLevel, parentStart, parentEnd int,
 	docFM map[string]any,
-	visit func(sc Scope, start, end int),
+	visit func(sc Scope, headingText string, start, end int),
 ) {
 	claimed := make(map[int]bool, len(heads))
 	for i, sc := range scopes {
@@ -142,7 +150,7 @@ func walkRanges(
 			claimed[idx] = true
 			start := heads[idx].Line
 			end := nextSectionLine(heads, idx, heads[idx].Level, parentEnd)
-			visit(sc, start, end)
+			visit(sc, heads[idx].Text, start, end)
 			if len(sc.Sections) > 0 {
 				walkRanges(sc.Sections, heads, expectedLevel+1, start, end, docFM, visit)
 			}

internal/schema/plan156_acceptance_test.go

@@ -459,6 +459,39 @@ func TestPlan156_OutOfOrderSequentialDiagFires(t *testing.T) {
 			"the unenforced-sequential diagnostic")
 }
 
+// TestPlan156_OverlappingMatcherDoesNotInflateClaimCount
+// regresses a Copilot finding: an earlier `regex: 'A|B'` scope
+// that yields a `B` heading to a later named `B` scope used to
+// have that yielded heading counted toward its own claim total
+// because the trailing pass re-scanned by regex. Now the count
+// tracks actual claims, so the early scope's `max` isn't
+// over-counted.
+func TestPlan156_OverlappingMatcherDoesNotInflateClaimCount(t *testing.T) {
+	raw := map[string]any{
+		"sections": []any{
+			map[string]any{
+				"heading": map[string]any{
+					"regex":  "A|B",
+					"repeat": map[string]any{"min": 1, "max": 2},
+				},
+			},
+			map[string]any{"heading": "B"},
+		},
+	}
+	sch, err := ParseInline(raw, "kind x")
+	require.NoError(t, err)
+	// Doc: A, B, A. The first scope claims A (counted = 1),
+	// yields B to the named B scope, then sees the second A.
+	// The trailing A should be its 2nd claim — within max=2.
+	doc := newDocFile(t, "doc.md",
+		"# T\n\n## A\n\nx\n\n## B\n\ny\n\n## A\n\nz\n")
+	diags := Validate(doc, sch, nil, false, makeDiagForTest)
+	for _, d := range diags {
+		assert.NotContains(t, d.Message, "exceeds scope",
+			"yielded headings must not inflate the first scope's claim count")
+	}
+}
+
 // TestPlan156_BoundedMaxExceededOutOfOrder regresses a Copilot
 // finding: the recovery path used to skip already-claimed
 // scopes with `max > 1`, so a `repeat: { max: 2 }` scope
@@ -1042,3 +1075,39 @@ func TestPlan156_RulesOnRepeatedScope(t *testing.T) {
 		"each repeated occurrence must contribute its own range "+
 			"so per-scope checks fire on every occurrence")
 }
+
+// TestPlan156_AcronymScopeMatchesByHeadingText regresses a
+// Copilot review finding: a disjunctive matcher like
+// `regex: 'Symptoms|Indicators'` paired with
+// `acronyms.scope: ["Indicators"]` must scan the matched
+// `## Indicators` body. Plan 156 dropped the scope-level
+// `aliases:` field, so the walker must compare the configured
+// scope name against the actual matched heading text (not just
+// the schema label or the raw regex body).
+func TestPlan156_AcronymScopeMatchesByHeadingText(t *testing.T) {
+	raw := map[string]any{
+		"sections": []any{
+			map[string]any{
+				"heading": map[string]any{"regex": "Symptoms|Indicators"},
+			},
+		},
+		"acronyms": map[string]any{
+			"scope":      []any{"Indicators"},
+			"known-safe": []any{},
+		},
+	}
+	sch, err := ParseInline(raw, "kind x")
+	require.NoError(t, err)
+	doc := newDocFile(t, "doc.md",
+		"# T\n\n## Indicators\n\nOIDC first.\n")
+	diags := ValidateAcronyms(doc, sch, nil, makeDiagForTest)
+	var seenOIDC bool
+	for _, d := range diags {
+		if strings.Contains(d.Message, "OIDC") {
+			seenOIDC = true
+		}
+	}
+	assert.True(t, seenOIDC,
+		"acronyms.scope must match the actual matched heading text, "+
+			"not just the schema label or the raw regex body")
+}

internal/schema/validate.go

@@ -146,6 +146,7 @@ func validateScopes(
 ) (int, []lint.Diagnostic) {
 	var diags []lint.Diagnostic
 	claimed := make(map[int]bool)
+	claimCounts := make(map[int]int)
 	allowExtra := false
 
 	for i, sc := range scopes {
@@ -166,7 +167,7 @@ func validateScopes(
 		}
 		newIdx, scDiags, claimedThis := matchScope(
 			f, scopes, i, expectedLevel, docHeads, docIdx,
-			claimed, allowExtra, closed, docFM, mkDiag)
+			claimed, claimCounts, allowExtra, closed, docFM, mkDiag)
 		diags = append(diags, scDiags...)
 		docIdx = newIdx
 		if claimedThis {
@@ -179,7 +180,7 @@ func validateScopes(
 	}
 
 	newIdx, leftoverDiags := handleLeftoverHeadings(
-		f, scopes, claimed, docHeads, docIdx, expectedLevel,
+		f, scopes, claimed, claimCounts, docHeads, docIdx, expectedLevel,
 		closed, allowExtra, docFM, mkDiag)
 	diags = append(diags, leftoverDiags...)
 	return newIdx, diags
@@ -194,7 +195,7 @@ func validateScopes(
 // closed: flagged as unexpected in closed scopes, silently
 // consumed in open ones.
 func handleLeftoverHeadings(
-	f *lint.File, scopes []Scope, claimed map[int]bool,
+	f *lint.File, scopes []Scope, claimed map[int]bool, claimCounts map[int]int,
 	docHeads []DocHeading, docIdx, expectedLevel int,
 	closed, allowExtra bool, docFM map[string]any, mkDiag MakeDiag,
 ) (int, []lint.Diagnostic) {
@@ -210,7 +211,8 @@ func handleLeftoverHeadings(
 		}
 		if idx := unclaimedListedScope(scopes, dh, claimed, docFM); idx >= 0 {
 			newIdx, claimDiags := claimLateScope(
-				f, scopes, idx, expectedLevel, docHeads, docIdx, claimed, docFM, mkDiag)
+				f, scopes, idx, expectedLevel, docHeads, docIdx,
+				claimed, claimCounts, docFM, mkDiag)
 			diags = append(diags, claimDiags...)
 			docIdx = newIdx
 			continue
@@ -221,7 +223,7 @@ func handleLeftoverHeadings(
 		// diagnostic so the user sees which scope was over-filled
 		// rather than a generic "unexpected".
 		if idx := claimedScopeExceeded(
-			scopes, dh, claimed, docFM, docHeads, docIdx, expectedLevel); idx >= 0 {
+			scopes, dh, claimed, claimCounts, docFM); idx >= 0 {
 			sc := scopes[idx]
 			diags = append(diags, mkDiag(f.Path, dh.Line,
 				fmt.Sprintf(
@@ -241,21 +243,23 @@ func handleLeftoverHeadings(
 	return docIdx, diags
 }
 
-// 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.
+// claimedScopeExceeded reports whether dh would push an
+// already-claimed non-slot, non-preamble scope past its `max`.
+// It also increments `claimCounts[i]` for the first claimed
+// scope whose matcher accepts dh — so consecutive same-scope
+// extras are counted accurately. Returns the matched scope's
+// index when the new count exceeds max, or -1 otherwise.
 //
-// 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.
+// Claim counts are tracked via the parallel `claimCounts` map,
+// so the check stays accurate even when overlapping matchers
+// yield specific headings to later named scopes: only headings
+// actually claimed by THIS scope count toward its 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,
+	claimCounts map[int]int, docFM map[string]any,
 ) int {
 	for i, sc := range scopes {
 		if !claimed[i] {
@@ -267,41 +271,24 @@ func claimedScopeExceeded(
 		if sc.Matcher == nil {
 			continue
 		}
-		_, max := sc.Matcher.Repeat.Bounds()
-		if max == 0 {
-			continue
-		}
 		if !scopeMatchesHeading(sc, dh, docFM) {
 			continue
 		}
-		count := countSameLevelMatches(sc, docHeads, expectedLevel, dhIdx, docFM)
-		if count > max {
+		_, max := sc.Matcher.Repeat.Bounds()
+		if max == 0 {
+			// Unbounded — count it but never flag.
+			claimCounts[i]++
+			return -1
+		}
+		claimCounts[i]++
+		if claimCounts[i] > max {
 			return i
 		}
+		return -1
 	}
 	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
@@ -320,7 +307,8 @@ func countSameLevelMatches(
 // surface.
 func claimLateScope(
 	f *lint.File, scopes []Scope, idx, expectedLevel int,
-	docHeads []DocHeading, docIdx int, claimed map[int]bool,
+	docHeads []DocHeading, docIdx int,
+	claimed map[int]bool, claimCounts map[int]int,
 	docFM map[string]any, mkDiag MakeDiag,
 ) (int, []lint.Diagnostic) {
 	sc := scopes[idx]
@@ -330,6 +318,7 @@ func claimLateScope(
 			"section %q out of order: expected before this position",
 			formatHeading(dh.Level, dh.Text)))}
 	claimed[idx] = true
+	claimCounts[idx]++
 	docIdx++
 	if len(sc.Sections) > 0 {
 		newIdx, childDiags := validateScopes(
@@ -368,12 +357,14 @@ func unclaimedListedScope(
 func matchScope(
 	f *lint.File, scopes []Scope, idx, expectedLevel int,
 	docHeads []DocHeading, docIdx int,
-	claimed map[int]bool, allowExtra, closed bool,
+	claimed map[int]bool, claimCounts map[int]int,
+	allowExtra, closed bool,
 	docFM map[string]any, mkDiag MakeDiag,
 ) (int, []lint.Diagnostic, bool) {
 	state := matchRun{
 		f: f, scopes: scopes, idx: idx, expectedLevel: expectedLevel,
-		claimed: claimed, allowExtra: allowExtra, closed: closed,
+		claimed: claimed, claimCounts: claimCounts,
+		allowExtra: allowExtra, closed: closed,
 		docFM: docFM, mkDiag: mkDiag,
 	}
 	state.min, state.max = scopes[idx].Matcher.Repeat.Bounds()
@@ -471,6 +462,7 @@ type matchRun struct {
 	idx           int
 	expectedLevel int
 	claimed       map[int]bool
+	claimCounts   map[int]int
 	allowExtra    bool
 	closed        bool
 	docFM         map[string]any
@@ -554,6 +546,7 @@ func (s *matchRun) claimMatch(docHeads []DocHeading, docIdx int, captured string
 	dh := docHeads[docIdx]
 	s.diags = append(s.diags, levelDiagIfNeeded(s.f, dh, s.expectedLevel, s.mkDiag)...)
 	s.claimed[s.idx] = true
+	s.claimCounts[s.idx]++
 	if len(sc.Sections) > 0 {
 		newIdx, childDiags := validateScopes(
 			s.f, sc.Sections, sc.Closed, docHeads, docIdx+1,
@@ -579,7 +572,7 @@ func (s *matchRun) handleNonMatch(docHeads []DocHeading, docIdx int) (bool, int,
 	if ooIdx := findOutOfOrderIdx(s.scopes, dh, s.claimed, s.idx+1, s.docFM); ooIdx >= 0 {
 		newIdx, ooDiags := claimOutOfOrder(
 			s.f, s.scopes, s.idx, ooIdx, s.expectedLevel, docHeads, docIdx,
-			s.claimed, s.docFM, s.mkDiag)
+			s.claimed, s.claimCounts, s.docFM, s.mkDiag)
 		s.diags = append(s.diags, ooDiags...)
 		return false, newIdx, false
 	}
@@ -590,7 +583,7 @@ func (s *matchRun) handleNonMatch(docHeads []DocHeading, docIdx int) (bool, int,
 	// doc [B, B, A] silently consumes the second B because
 	// findOutOfOrderIdx ignores claimed scopes.
 	if idx := claimedScopeExceeded(
-		s.scopes, dh, s.claimed, s.docFM, docHeads, docIdx, s.expectedLevel); idx >= 0 {
+		s.scopes, dh, s.claimed, s.claimCounts, s.docFM); idx >= 0 {
 		sc := s.scopes[idx]
 		s.diags = append(s.diags, s.mkDiag(s.f.Path, dh.Line,
 			fmt.Sprintf(
@@ -723,7 +716,8 @@ func levelDiagIfNeeded(
 // recurses into the matched scope's child sections.
 func claimOutOfOrder(
 	f *lint.File, scopes []Scope, idx, ooIdx, expectedLevel int,
-	docHeads []DocHeading, docIdx int, claimed map[int]bool,
+	docHeads []DocHeading, docIdx int,
+	claimed map[int]bool, claimCounts map[int]int,
 	docFM map[string]any, mkDiag MakeDiag,
 ) (int, []lint.Diagnostic) {
 	sc := scopes[idx]
@@ -763,6 +757,7 @@ func claimOutOfOrder(
 				formatHeading(expectedLevel, displayHeading(ooSc)))))
 	}
 	claimed[ooIdx] = true
+	claimCounts[ooIdx]++
 	docIdx++
 	if len(ooSc.Sections) > 0 {
 		newIdx, childDiags := validateScopes(