docs(skill),fix(skilldoc): review fixes — integration_id equivalence; guard splice index; single-file two-fence test

- filters.md: integration_id is not a legacy alias — the server accepts it
  and data_source_id interchangeably (the API's response docs in fact
  deprecate data_source_id), so present the pair as equivalent and keep the
  never-use list to the severity/status aliases, scoped to rule-evaluation
  time.
- runGen: check the start-marker index before slicing the body with it.
- New TestRunGen_TwoFencesInOneFile pins the sequential splice loop for a
  subset fence and catch-all living in one card.

Author: ysyneu

internal/cmd/skilldoc/main.go

@@ -130,8 +130,11 @@ func runGen(d skilldoc.Dump, base, group string) error {
 		for _, id := range perDoc[p] {
 			start, end := skilldoc.FenceStart(id), skilldoc.FenceEnd(id)
 			si := strings.Index(body, start)
+			if si < 0 {
+				return fmt.Errorf("%s: unterminated GENERATED:%s fence", p, id)
+			}
 			ei := strings.Index(body[si:], end)
-			if si < 0 || ei < 0 {
+			if ei < 0 {
 				return fmt.Errorf("%s: unterminated GENERATED:%s fence", p, id)
 			}
 			body = body[:si] + rendered[id] + body[si+ei+len(end):]

internal/cmd/skilldoc/main_test.go

@@ -399,3 +399,43 @@ func TestRunGen_TopologyViolationFails(t *testing.T) {
 		t.Fatalf("want topology error mentioning the missing catch-all, got %v", err)
 	}
 }
+
+// TestRunGen_TwoFencesInOneFile pins the sequential splice loop: a single card
+// carrying both a subset fence and the catch-all fence of the same group must
+// have both rewritten in one pass (offsets are re-resolved by marker text
+// after each splice, so the first replacement must not derail the second).
+func TestRunGen_TwoFencesInOneFile(t *testing.T) {
+	dir := t.TempDir()
+	mk := func(verb string) skilldoc.Command {
+		return skilldoc.Command{Path: "svc " + verb, Group: "svc", Short: "S " + verb, Use: verb}
+	}
+	d := skilldoc.Dump{Commands: []skilldoc.Command{mk("list"), mk("rule-create"), mk("rule-delete")}}
+
+	card := filepath.Join(dir, "reference", "svc.md")
+	writeFile(t, card, "# svc\n\nrules first\n\n"+
+		skilldoc.FenceStart("svc[rule-]")+"\n"+skilldoc.FenceEnd("svc[rule-]")+"\n\nthen the rest\n\n"+
+		skilldoc.FenceStart("svc")+"\n"+skilldoc.FenceEnd("svc")+"\n")
+
+	if err := runGen(d, dir, "svc"); err != nil {
+		t.Fatalf("runGen: %v", err)
+	}
+
+	body, err := os.ReadFile(card)
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := string(body)
+	ruleAt := strings.Index(got, "### rule-create")
+	listAt := strings.Index(got, "### list")
+	if ruleAt < 0 || listAt < 0 || ruleAt > listAt {
+		t.Fatalf("both fences must be filled, subset before catch-all:\n%s", got)
+	}
+	if !strings.Contains(got, "rules first") || !strings.Contains(got, "then the rest") {
+		t.Errorf("gen clobbered hand-written content between fences:\n%s", got)
+	}
+
+	var out bytes.Buffer
+	if n, _ := runCheck(d, dir, &out); n != 0 {
+		t.Errorf("after gen, check should be clean; got %d:\n%s", n, out.String())
+	}
+}

skills/flashduty/reference/filters.md

@@ -36,7 +36,9 @@ the rule fires when ANY group matches; each inner array holds
 ## Keys — use the canonical names only
 
 Common to every rule family: `severity`, `status`, `title`, `description`,
-`data_source_id`, and `labels.<name>` for any custom label. Per family:
+`data_source_id` / `integration_id` (interchangeable — the server accepts
+both and they always carry the same value), and `labels.<name>` for any
+custom label. Per family:
 
 | rule family | matched against | extra keys | keys that DO NOT exist here |
 |---|---|---|---|
@@ -47,13 +49,13 @@ A key outside the family's vocabulary (e.g. `dedup_key` in a silence rule)
 produces a rule that never matches while looking configured — check the table
 before creating, and prefer server-rejected over silently-dead if unsure.
 
-**Legacy aliases — never use them.** `event_severity`, `alert_severity`,
-`incident_severity`, `alert_status`, `incident_status`, and `integration_id`
-are stored aliases that always carry the SAME value as the canonical
-`severity` / `status` / `data_source_id` on their surface. Spelling them adds
-no precision and invites wrong reads — on escalation rules `alert_severity`
-is an alias of the *incident's* severity, not of any alert's. Always write
-the canonical key.
+**Legacy severity/status aliases — never use them.** `event_severity`,
+`alert_severity`, `incident_severity`, `alert_status`, and `incident_status`
+are stored aliases that, at rule-evaluation time, always carry the SAME
+value as the canonical `severity` / `status` on their surface. Spelling them
+adds no precision and invites wrong reads — on escalation rules
+`alert_severity` is an alias of the *incident's* severity, not of any
+alert's. Always write the canonical key.
 
 ## Building filters from incident labels (scoping a rule to one incident)