Address round-3 review: Splice negative-Start, IsGitHubAlert contract pin

Recall agent surfaced three findings after commit 17cca70; one was
the F5 silent-corruption path already closed in commit 131a9f1. The
remaining two land here.

#2: markdown.Splice's precondition check fired for negative-Start
edits via the generic "overlaps previous edit ending at 0" panic. A
producer that subtracts past 0 and emits Start=-1 sent the debugger
chasing a non-existent previous edit. Add a dedicated `Start < 0`
guard that names the actual fault, plus a pin in
TestSpliceInvariantViolation.

#3: fixGitHubAlerts removed the local (Paragraph, non-empty Lines)
re-check and trusts flavor.IsGitHubAlert's contract — but no
behavior test pinned that contract. The four existing fix tests
exercise inputs where IsGitHubAlert returns true via the real
parser; they would not catch a future relaxation of IsGitHubAlert
that returns true for a non-Paragraph first child. Add
TestIsGitHubAlertContractPostcondition: walk a corpus of alert /
non-alert / degenerate blockquotes, and on every IsGitHubAlert==true
case assert FirstChild is *ast.Paragraph with non-empty Lines.

Coverage in pkg/markdown and pkg/markdown/flavor stays at 100%;
mdsmith check and golangci-lint clean.

https://claude.ai/code/session_0144ZKUS2Zrg7xBft54qyoti

Author: claude

pkg/markdown/flavor/detect_edge_test.go

@@ -310,6 +310,61 @@ func TestFindHeadingIDNilHeadingReturnsFalse(t *testing.T) {
 	assert.Equal(t, HeadingIDExtra{}, hx)
 }
 
+// TestIsGitHubAlertContractPostcondition pins the documented
+// postcondition: IsGitHubAlert returns true ⇒ bq.FirstChild() is
+// *ast.Paragraph and Paragraph.Lines.Len() > 0. The rule's
+// fixGitHubAlerts trusts this postcondition (its bq.FirstChild()
+// type assertion + lines.At(0) are unguarded), so a future refactor
+// that relaxes IsGitHubAlert without updating the call site would
+// panic in production. Driving the contract from a corpus of
+// representative blockquotes — alert and non-alert, well-formed and
+// degenerate — catches the drift here instead.
+func TestIsGitHubAlertContractPostcondition(t *testing.T) {
+	corpus := []string{
+		"> [!NOTE]\n> body\n",
+		"> [!TIP]\n> body\n",
+		"> [!IMPORTANT]\n> body\n",
+		"> [!WARNING]\n> body\n",
+		"> [!CAUTION]\n> body\n",
+		"> [!NOTE]\n> first\n> second\n",
+		"> [!NOTE]\n", // marker only, no continuation
+		"> plain paragraph\n",
+		"> # heading not paragraph\n",
+		"plain paragraph\n",
+		"```\nfenced\n```\n",
+		"> [!note]\n> case-sensitive miss\n",
+	}
+	for _, src := range corpus {
+		t.Run(src, func(t *testing.T) {
+			doc := mkDoc(t, src)
+			_ = ast.Walk(doc.AST, func(n ast.Node, entering bool) (ast.WalkStatus, error) {
+				if !entering {
+					return ast.WalkContinue, nil
+				}
+				bq, ok := n.(*ast.Blockquote)
+				if !ok {
+					return ast.WalkContinue, nil
+				}
+				if !IsGitHubAlert(bq, []byte(src)) {
+					return ast.WalkContinue, nil
+				}
+				// Postcondition: the rule's fixGitHubAlerts trusts
+				// these two invariants — keep them locked.
+				para, ok := bq.FirstChild().(*ast.Paragraph)
+				require.True(t, ok,
+					"IsGitHubAlert returned true but bq.FirstChild() is %T",
+					bq.FirstChild())
+				lines := para.Lines()
+				require.NotNil(t, lines,
+					"IsGitHubAlert returned true but Paragraph.Lines() is nil")
+				require.Greater(t, lines.Len(), 0,
+					"IsGitHubAlert returned true but Paragraph has empty Lines")
+				return ast.WalkContinue, nil
+			})
+		})
+	}
+}
+
 // TestIsGitHubAlertHandlesEdgeCases pins the defensive branches of
 // IsGitHubAlert: nil blockquote, missing-paragraph first child, and
 // a paragraph with empty Lines all return false rather than panic.

pkg/markdown/parse_test.go

@@ -157,6 +157,18 @@ func TestSpliceInvariantViolation(t *testing.T) {
 			func() { Splice(body, []Edit{{Start: 5, End: 3}}) })
 	})
 
+	t.Run("negative Start panics with a dedicated message", func(t *testing.T) {
+		// Caller produces an edit with a negative offset (typically a
+		// buggy producer subtracting past 0). Without this check the
+		// generic overlap message ("overlaps previous edit ending at 0")
+		// would fire and mislead the debugger toward a non-existent
+		// previous edit; the dedicated message names the actual fault.
+		body := []byte("0123456789")
+		assert.PanicsWithValue(t,
+			"markdown.Splice: edit 0 has negative Start ({Start:-1, End:5})",
+			func() { Splice(body, []Edit{{Start: -1, End: 5}}) })
+	})
+
 	t.Run("edit exceeding body length panics", func(t *testing.T) {
 		body := []byte("short")
 		assert.PanicsWithValue(t,

pkg/markdown/produce.go

@@ -42,6 +42,11 @@ func Splice(body []byte, edits []Edit) []byte {
 	// an opaque slice-bounds panic during the build loop below.
 	prevEnd := 0
 	for i, e := range edits {
+		if e.Start < 0 {
+			panic(fmt.Sprintf(
+				"markdown.Splice: edit %d has negative Start "+
+					"({Start:%d, End:%d})", i, e.Start, e.End))
+		}
 		if e.Start < prevEnd {
 			panic(fmt.Sprintf(
 				"markdown.Splice: edits must be ascending and "+