fix(skilldoc): don't misparse a description's bracketed prose as an enum

The Request-fields enum extractor matched the FIRST "[...]" bracket
anywhere in a flag's tail text and treated its contents as an enum
declaration. cligen's own trailing enum bracket is always the last
thing on the line (before an optional constraint suffix), but a
description can legitimately quote an unrelated bracket earlier in its
own prose -- e.g. a regex character class ("1-40 chars of
'[a-zA-Z0-9_]'"). The old code fabricated a one-value enum from that
character class AND deleted it from the sentence, leaving an empty
quoted pair where the class used to be.

Only recognize a bracket anchored to the end of the tail (once an
optional trailing "(constraint)" is set aside) as a genuine enum --
exactly where cligen's generator appends one. Anything earlier in the
text is left untouched, description and constraint both.

Regenerating all cards with this fix touches only field.md (the sole
card affected): the fabricated enum tag is gone and the character
class renders intact in the description.

Author: ysyneu

internal/skilldoc/generate.go

@@ -255,10 +255,46 @@ type requestFields struct {
 var (
 	flagLineRe  = regexp.MustCompile(`^\s{2}--([a-z0-9-]+)\s+\S+\s*(.*)$`)
 	bodyLineRe  = regexp.MustCompile(`^\s{2}([a-z0-9_]+)\s+\(([^,)]*)[^)]*\)\s*(.*)$`)
-	enumRe      = regexp.MustCompile(`\[([^\]]+)\]`)
 	requiredTag = "(required)"
 )
 
+// trailingConstraintRe matches a trailing "(...)" constraint parenthetical --
+// cligen appends this immediately after an enum bracket when a flag has both
+// (internal/cmd/cligen/main.go writes f.Enum then f.Constraint, in that
+// order). Setting it aside first lets enumTailRe check what's left for a
+// genuine trailing enum bracket without the constraint's own parens getting
+// in the way, and lets that constraint be reattached untouched afterward.
+var trailingConstraintRe = regexp.MustCompile(`\s*\([^()]*\)\s*$`)
+
+// enumTailRe matches a "[a, b, c]" bracket anchored to the END of its input --
+// exactly where cligen's own generator appends a real enum ("line += " [" +
+// strings.Join(f.Enum, ", ") + "]"", see cligen/main.go). Anchoring to the
+// end is what excludes an arbitrary "[...]" appearing earlier in a
+// description's free text -- e.g. a regex character class quoted inside a
+// constraint sentence ("1-40 chars of '[a-zA-Z0-9_]'", see
+// zz_generated_alert_enrichment.go's field-name flag) -- which an unanchored
+// match would misidentify as a one-value enum declaration AND delete from
+// the description, corrupting both the fabricated enum tag and the sentence.
+var enumTailRe = regexp.MustCompile(`\s*\[([^\]]+)\]\s*$`)
+
+// splitTrailingEnum peels cligen's own trailing enum bracket, if any, off
+// tail: enum is the bracket's inner text ("" when there is none), and rest is
+// tail with that bracket removed. A trailing "(constraint)" is set aside
+// before looking for the bracket and reattached untouched afterward, so it
+// never masks a genuine enum and is never itself mistaken for one. When the
+// tail-most token (once any constraint is set aside) isn't a bracket at all,
+// enum is "" and rest is tail unchanged -- any "[...]" earlier in the text is
+// incidental prose, not a declared enum, and must survive intact.
+func splitTrailingEnum(tail string) (enum, rest string) {
+	constraint := trailingConstraintRe.FindString(tail)
+	body := strings.TrimSuffix(tail, constraint)
+	loc := enumTailRe.FindStringSubmatchIndex(body)
+	if loc == nil {
+		return "", tail
+	}
+	return body[loc[2]:loc[3]], body[:loc[0]] + body[loc[1]:] + constraint
+}
+
 // parseRequestFields extracts the per-flag required/enum/usage and the
 // body-only (--data) field summaries from a command's Long "Request fields:"
 // block. Returns empty maps when the block is absent (read-only verbs).
@@ -303,13 +339,14 @@ func parseRequestFields(long string) requestFields {
 	return rf
 }
 
-// parseEnum pulls the enum members out of a trailing "[a, b, c]" marker.
+// parseEnum pulls the enum members out of tail's genuine trailing "[a, b, c]"
+// marker (see splitTrailingEnum), or returns nil when tail carries none.
 func parseEnum(tail string) []string {
-	m := enumRe.FindStringSubmatch(tail)
-	if m == nil {
+	enum, _ := splitTrailingEnum(tail)
+	if enum == "" {
 		return nil
 	}
-	parts := strings.Split(m[1], ",")
+	parts := strings.Split(enum, ",")
 	out := make([]string, 0, len(parts))
 	for _, p := range parts {
 		if v := strings.TrimSpace(p); v != "" {
@@ -319,11 +356,12 @@ func parseEnum(tail string) []string {
 	return out
 }
 
-// cleanUsage strips the leading em-dash, the (required) tag, and the trailing
-// enum bracket from a flag line's tail, leaving the human description.
+// cleanUsage strips the leading em-dash, the (required) tag, and tail's
+// genuine trailing enum bracket (see splitTrailingEnum) from a flag line's
+// tail, leaving the human description -- including any trailing constraint
+// and any incidental "[...]" that isn't cligen's own enum marker.
 func cleanUsage(tail string) string {
-	s := tail
-	s = enumRe.ReplaceAllString(s, "")
+	_, s := splitTrailingEnum(tail)
 	s = strings.ReplaceAll(s, requiredTag, "")
 	s = strings.TrimSpace(s)
 	s = strings.TrimPrefix(s, "—")

internal/skilldoc/generate_test.go

@@ -158,6 +158,115 @@ func TestGenerateFence_PositionalArg(t *testing.T) {
 	}
 }
 
+// TestSplitTrailingEnum_IgnoresBracketedProseInsideDescription reproduces the
+// real `field create --field-name` bug: its description quotes a regex
+// character class mid-sentence ("1-40 chars of '[a-zA-Z0-9_]'") followed by
+// more prose and a trailing constraint. An unanchored bracket match treats
+// that as a one-value enum declaration, fabricating an "enum: a-zA-Z0-9_" tag
+// AND deleting the bracket from the sentence (leaving an empty pair of
+// quotes where the character class used to be). Since
+// the bracket isn't at the tail's end (more text and the constraint follow
+// it), it must be left alone entirely: no enum, description word-for-word.
+func TestSplitTrailingEnum_IgnoresBracketedProseInsideDescription(t *testing.T) {
+	tail := `(required) — Machine name. Must start with a letter or underscore; 1–40 chars of '[a-zA-Z0-9_]'. Immutable after creation. (≤39 chars)`
+	if enum := parseEnum(tail); enum != nil {
+		t.Errorf("bracketed prose must not be parsed as an enum, got %v", enum)
+	}
+	got := cleanUsage(tail)
+	want := `Machine name. Must start with a letter or underscore; 1–40 chars of '[a-zA-Z0-9_]'. Immutable after creation. (≤39 chars)`
+	if got != want {
+		t.Errorf("cleanUsage must leave the character class and constraint untouched:\ngot:  %q\nwant: %q", got, want)
+	}
+}
+
+// TestSplitTrailingEnum_RecognizesGenuineTrailingEnum proves the fix doesn't
+// overcorrect: cligen's own trailing enum bracket ("line += " [" + ... +
+// "]"", cligen/main.go) -- anchored at the tail's end, nothing else
+// following it -- is still recognized and still stripped from the usage
+// text.
+func TestSplitTrailingEnum_RecognizesGenuineTrailingEnum(t *testing.T) {
+	tail := `(required) — Event type. [incident, maintenance]`
+	if enum := parseEnum(tail); !equalStrings(enum, []string{"incident", "maintenance"}) {
+		t.Errorf("genuine trailing enum not recognized, got %v", enum)
+	}
+	if got, want := cleanUsage(tail), "Event type."; got != want {
+		t.Errorf("cleanUsage should strip the genuine enum bracket:\ngot:  %q\nwant: %q", got, want)
+	}
+}
+
+// TestSplitTrailingEnum_GenuineEnumWithTrailingConstraint covers a flag that
+// has BOTH an enum and a constraint (cligen writes enum then constraint, in
+// that order, when both are present): the enum must still be recognized and
+// stripped, and the constraint must survive untouched and back in its
+// original trailing position -- not swallowed by the enum-bracket removal.
+func TestSplitTrailingEnum_GenuineEnumWithTrailingConstraint(t *testing.T) {
+	tail := `— Some usage. [a, b] (≤5 chars)`
+	if enum := parseEnum(tail); !equalStrings(enum, []string{"a", "b"}) {
+		t.Errorf("enum with a trailing constraint not recognized, got %v", enum)
+	}
+	if got, want := cleanUsage(tail), "Some usage. (≤5 chars)"; got != want {
+		t.Errorf("cleanUsage must strip only the enum bracket, keeping the constraint:\ngot:  %q\nwant: %q", got, want)
+	}
+}
+
+// TestSplitTrailingEnum_SingleValueEnumAtEnd covers a one-member enum (e.g.
+// the real `--environment-kind [byoc]`), proving the fix doesn't require a
+// comma to recognize a genuine trailing bracket as an enum.
+func TestSplitTrailingEnum_SingleValueEnumAtEnd(t *testing.T) {
+	tail := `— Pin to a specific runner. [byoc]`
+	if enum := parseEnum(tail); !equalStrings(enum, []string{"byoc"}) {
+		t.Errorf("single-value trailing enum not recognized, got %v", enum)
+	}
+}
+
+// TestGenerateFence_BracketedProseSurvivesAlongsideGenuineEnum is the
+// fence-level integration check: one command with a description-embedded
+// character class (must NOT become an enum) and, on a different flag in the
+// same command, a genuine trailing enum (must still render as one) —
+// proving the fix distinguishes them within the same Request-fields block,
+// not just in isolation.
+func TestGenerateFence_BracketedProseSurvivesAlongsideGenuineEnum(t *testing.T) {
+	d := Dump{Commands: []Command{{
+		Path:  "field create",
+		Group: "field",
+		Short: "Create field",
+		Use:   "create",
+		Long: `Create field.
+
+Request fields:
+  --field-name string (required) — Machine name. Must start with a letter or underscore; 1–40 chars of '[a-zA-Z0-9_]'. Immutable after creation. (≤39 chars)
+  --field-type string (required) — Field input type. [checkbox, text]
+`,
+		Flags: []Flag{{Name: "field-name", Type: "string"}, {Name: "field-type", Type: "string"}},
+	}}}
+	sec := sectionFor(GenerateFence(d, "field"), "create")
+	if !strings.Contains(sec, "1–40 chars of '[a-zA-Z0-9_]'") {
+		t.Errorf("character class embedded in prose must render intact:\n%s", sec)
+	}
+	if strings.Contains(sec, "chars of ''") {
+		t.Errorf("character class must not be deleted from the description:\n%s", sec)
+	}
+	if strings.Contains(sec, "enum: a-zA-Z0-9_") {
+		t.Errorf("character class must not be fabricated into an enum tag:\n%s", sec)
+	}
+	if !strings.Contains(sec, "enum: checkbox | text") {
+		t.Errorf("the genuine enum on the OTHER flag in the same command must still render:\n%s", sec)
+	}
+}
+
+// equalStrings compares two string slices for the enum-parsing tests above.
+func equalStrings(a, b []string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if a[i] != b[i] {
+			return false
+		}
+	}
+	return true
+}
+
 // sectionFor returns the slice of out from "### <verb>" to the next "### " or end.
 func sectionFor(out, verb string) string {
 	start := strings.Index(out, "### "+verb)

skills/flashduty/reference/field.md

@@ -45,7 +45,7 @@ fduty field update <field-id> \
 Create field
 - `--description` string — Optional free-text description. (≤499 chars)
 - `--display-name` string (required) — Human-readable name. Must be unique within the account. (≤39 chars)
-- `--field-name` string (required) — Machine name. Must start with a letter or underscore; 1–40 chars of ''. Immutable after creation. (≤39 chars) · enum: a-zA-Z0-9_
+- `--field-name` string (required) — Machine name. Must start with a letter or underscore; 1–40 chars of '[a-zA-Z0-9_]'. Immutable after creation. (≤39 chars)
 - `--field-type` string (required) — Field input type. Immutable after creation. · enum: checkbox | multi_select | single_select | text
 - `--options` stringSlice — Required and non-empty for 'single_select'/'multi_select' (unique strings, each 1–200 chars). Must be omitted or empty for 'checkbox'/'text'.
 - `--value-type` string (required) — Stored value type. 'checkbox' requires 'bool'; 'single_select'/'multi_select'/'text' require 'string'. Immutable after creation. · enum: string | bool | float