feat(skilldoc): subset fences — split one command group across cards

A fence id can now be group[verb-prefix,...]: a subset fence claiming every
verb starting with one of the prefixes, while the bare-group fence renders
the unclaimed remainder as the catch-all. gen/check discover fences by
scanning the cards for markers instead of deriving one filename per group,
so a large command group's reference card can be split along task lines.
Topology violations (a verb claimed twice, a prefix claiming nothing,
unclaimed verbs with no catch-all, a duplicated fence) fail gen and are
reported by check as fence-topology issues.

Author: ysyneu

internal/cmd/skilldoc/main.go

@@ -39,7 +39,7 @@ func main() {
 func genCmd() *cobra.Command {
 	return &cobra.Command{
 		Use:   "gen [group]",
-		Short: "Rewrite the generated fence in skills/flashduty/reference/<group>.md (every card if no group given)",
+		Short: "Rewrite every GENERATED:<group> fence across the skills/flashduty cards (every group if none given)",
 		Args:  cobra.MaximumNArgs(1),
 		RunE: func(_ *cobra.Command, args []string) error {
 			base, err := cardBase()
@@ -81,40 +81,90 @@ func checkCmd() *cobra.Command {
 // dump builds the command-tree dump from the live CLI root, in-process.
 func dump() skilldoc.Dump { return skilldoc.Build(cli.RootForDump()) }
 
-// runGen rewrites the GENERATED:<group> fence inside <base>/reference/<group>.md
-// with a fresh render, leaving all hand-written content outside the fence
-// untouched.
+// runGen regenerates every GENERATED fence of group across the cards under
+// <base>, leaving hand-written content outside the fences untouched. A group
+// may split its fences across cards (subset fences claiming verb prefixes,
+// plus the catch-all for the rest — see skilldoc.RenderGroupFences), so the
+// fresh render is computed for the group as a whole, then spliced per card.
 func runGen(d skilldoc.Dump, base, group string) error {
-	card := filepath.Join(base, "reference", group+".md")
-	raw, err := os.ReadFile(card)
+	docs, err := loadDocs(base)
 	if err != nil {
-		return fmt.Errorf("read card: %w", err)
+		return err
+	}
+
+	var ids []string
+	perDoc := map[string][]string{}
+	var docOrder []string
+	for _, doc := range docs {
+		for _, fl := range skilldoc.FenceLocs(doc.Body) {
+			spec, err := skilldoc.ParseFenceID(fl.ID)
+			if err != nil {
+				return fmt.Errorf("%s: %w", doc.Path, err)
+			}
+			if spec.Group != group {
+				continue
+			}
+			if len(perDoc[doc.Path]) == 0 {
+				docOrder = append(docOrder, doc.Path)
+			}
+			perDoc[doc.Path] = append(perDoc[doc.Path], fl.ID)
+			ids = append(ids, fl.ID)
+		}
+	}
+	if len(ids) == 0 {
+		return fmt.Errorf("no GENERATED:%s fence found under %s (add the start/end markers first)", group, base)
 	}
-	body := normalizeEOL(string(raw))
 
-	start, end := skilldoc.FenceStart(group), skilldoc.FenceEnd(group)
-	si := strings.Index(body, start)
-	ei := strings.Index(body, end)
-	if si < 0 || ei < 0 || ei < si {
-		return fmt.Errorf("%s: no GENERATED:%s fence to fill (add the start/end markers first)", card, group)
+	rendered, violations := skilldoc.RenderGroupFences(d, group, ids)
+	if len(violations) > 0 {
+		return fmt.Errorf("group %s fence topology: %s", group, strings.Join(violations, "; "))
 	}
 
-	fresh := skilldoc.GenerateFence(d, group)
-	updated := body[:si] + fresh + body[ei+len(end):]
-	if updated == body {
-		return nil // already fresh
+	byPath := map[string]skilldoc.Doc{}
+	for _, doc := range docs {
+		byPath[doc.Path] = doc
 	}
-	if err := os.WriteFile(card, []byte(updated), 0o644); err != nil {
-		return fmt.Errorf("write card: %w", err)
+	for _, p := range docOrder {
+		doc := byPath[p]
+		body := doc.Body
+		for _, id := range perDoc[p] {
+			start, end := skilldoc.FenceStart(id), skilldoc.FenceEnd(id)
+			si := strings.Index(body, start)
+			ei := strings.Index(body[si:], end)
+			if si < 0 || ei < 0 {
+				return fmt.Errorf("%s: unterminated GENERATED:%s fence", p, id)
+			}
+			body = body[:si] + rendered[id] + body[si+ei+len(end):]
+		}
+		if body == doc.Body {
+			continue // already fresh
+		}
+		if err := os.WriteFile(filepath.Join(base, p), []byte(body), 0o644); err != nil {
+			return fmt.Errorf("write card: %w", err)
+		}
 	}
 	return nil
 }
 
-// runGenAll regenerates the fence of every dump group that has a card file under
-// <base>/reference. The group set is derived from the dump (intersected with the
-// cards that actually exist), so it stays correct as domains are added or
-// renamed — no hardcoded list. Groups without a card (e.g. webhook) are skipped.
+// runGenAll regenerates the fences of every dump group that has at least one
+// GENERATED marker in a card under <base>. The group set is derived from the
+// dump (intersected with the fences that actually exist), so it stays correct
+// as domains are added or renamed — no hardcoded list. Groups without any
+// fence (e.g. webhook) are skipped.
 func runGenAll(d skilldoc.Dump, base string) error {
+	docs, err := loadDocs(base)
+	if err != nil {
+		return err
+	}
+	withFence := map[string]bool{}
+	for _, doc := range docs {
+		for _, fl := range skilldoc.FenceLocs(doc.Body) {
+			if spec, err := skilldoc.ParseFenceID(fl.ID); err == nil {
+				withFence[spec.Group] = true
+			}
+		}
+	}
+
 	seen := map[string]bool{}
 	var groups []string
 	for _, c := range d.Commands {
@@ -125,8 +175,8 @@ func runGenAll(d skilldoc.Dump, base string) error {
 	}
 	sort.Strings(groups)
 	for _, g := range groups {
-		if _, err := os.Stat(filepath.Join(base, "reference", g+".md")); err != nil {
-			continue // no card for this group
+		if !withFence[g] {
+			continue
 		}
 		if err := runGen(d, base, g); err != nil {
 			return fmt.Errorf("gen %s: %w", g, err)

internal/cmd/skilldoc/main_test.go

@@ -337,3 +337,65 @@ func TestRunGen_FillsFence(t *testing.T) {
 		t.Errorf("gen clobbered hand-written content:\n%s", updated)
 	}
 }
+
+// TestRunGen_SplitAcrossCards is the split-card path: one group whose subset
+// fence and catch-all fence live in different files. gen must fill both from
+// one group-wide render, and check must then be clean.
+func TestRunGen_SplitAcrossCards(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")}}
+
+	rules := filepath.Join(dir, "reference", "rules.md")
+	svc := filepath.Join(dir, "reference", "svc.md")
+	writeFile(t, rules, "# rules\n\n"+skilldoc.FenceStart("svc[rule-]")+"\n"+skilldoc.FenceEnd("svc[rule-]")+"\n")
+	writeFile(t, svc, "# svc\n\nintro\n\n"+skilldoc.FenceStart("svc")+"\n"+skilldoc.FenceEnd("svc")+"\n")
+
+	if err := runGen(d, dir, "svc"); err != nil {
+		t.Fatalf("runGen: %v", err)
+	}
+
+	rulesBody, err := os.ReadFile(rules)
+	if err != nil {
+		t.Fatal(err)
+	}
+	svcBody, err := os.ReadFile(svc)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(rulesBody), "### rule-create") || strings.Contains(string(rulesBody), "### list") {
+		t.Errorf("rules card should carry exactly the claimed verbs:\n%s", rulesBody)
+	}
+	if !strings.Contains(string(svcBody), "### list") || strings.Contains(string(svcBody), "### rule-create") {
+		t.Errorf("svc card should carry exactly the unclaimed remainder:\n%s", svcBody)
+	}
+	if !strings.Contains(string(svcBody), "intro") {
+		t.Errorf("gen clobbered hand-written content:\n%s", svcBody)
+	}
+
+	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())
+	}
+}
+
+// TestRunGen_TopologyViolationFails asserts gen refuses to write anything when
+// the group's fences do not partition its verbs.
+func TestRunGen_TopologyViolationFails(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")}}
+
+	// Subset fence only — "list" has no home.
+	writeFile(t, filepath.Join(dir, "reference", "rules.md"),
+		"# rules\n\n"+skilldoc.FenceStart("svc[rule-]")+"\n"+skilldoc.FenceEnd("svc[rule-]")+"\n")
+
+	err := runGen(d, dir, "svc")
+	if err == nil || !strings.Contains(err.Error(), "no catch-all") {
+		t.Fatalf("want topology error mentioning the missing catch-all, got %v", err)
+	}
+}

internal/skilldoc/fence.go

@@ -0,0 +1,159 @@
+package skilldoc
+
+// Fence topology: which GENERATED fence carries which commands of a group.
+//
+// A fence id is either the bare group name ("channel") — the group's
+// catch-all fence — or the group plus a bracketed verb-prefix claim list
+// ("channel[silence-rule,inhibit-rule]") — a subset fence that claims every
+// verb starting with one of the prefixes. A group's fences may live in
+// different cards; together they must cover the group exactly: every verb
+// lands in exactly one fence, each prefix claims at least one verb, and any
+// unclaimed remainder requires the catch-all fence to exist.
+
+import (
+	"fmt"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// FenceSpec is one parsed fence id.
+type FenceSpec struct {
+	Group    string
+	Prefixes []string // empty → the group's catch-all fence
+}
+
+// ID renders the spec back to its marker id ("group" or "group[p1,p2]").
+func (s FenceSpec) ID() string {
+	if len(s.Prefixes) == 0 {
+		return s.Group
+	}
+	return s.Group + "[" + strings.Join(s.Prefixes, ",") + "]"
+}
+
+// fenceIDRe accepts "group" or "group[prefix,prefix,...]". Group and prefix
+// share the verb charset; no spaces, so a malformed claim list fails loudly
+// instead of silently truncating at the first space.
+var fenceIDRe = regexp.MustCompile(`^([a-z0-9-]+)(?:\[([a-z0-9-]+(?:,[a-z0-9-]+)*)\])?$`)
+
+// ParseFenceID parses a fence id as found in a GENERATED marker.
+func ParseFenceID(id string) (FenceSpec, error) {
+	m := fenceIDRe.FindStringSubmatch(id)
+	if m == nil {
+		return FenceSpec{}, fmt.Errorf("malformed fence id %q (want group or group[verb-prefix,…])", id)
+	}
+	spec := FenceSpec{Group: m[1]}
+	if m[2] != "" {
+		spec.Prefixes = strings.Split(m[2], ",")
+	}
+	return spec, nil
+}
+
+// FenceLoc is one GENERATED start marker found in a doc body.
+type FenceLoc struct {
+	ID     string
+	Offset int // byte offset of the start marker
+}
+
+// fenceStartRe matches a start marker and captures its fence id; the literal
+// " START " cannot appear in an end marker, so ends never match.
+var fenceStartRe = regexp.MustCompile(`<!-- GENERATED:([^ ]+) START `)
+
+// FenceLocs returns every GENERATED start marker in body, in document order.
+func FenceLocs(body string) []FenceLoc {
+	var locs []FenceLoc
+	for _, m := range fenceStartRe.FindAllStringSubmatchIndex(body, -1) {
+		locs = append(locs, FenceLoc{ID: body[m[2]:m[3]], Offset: m[0]})
+	}
+	return locs
+}
+
+// RenderGroupFences renders the fenced block for every fence of one command
+// group. ids must be the complete set of fence ids that exist for the group
+// across all cards — the catch-all fence renders whatever its sibling subset
+// fences leave unclaimed, so a fence cannot be rendered in isolation.
+// Topology problems (a verb claimed twice, a prefix claiming nothing, verbs
+// left over with no catch-all, a duplicated id) come back as violations;
+// rendered blocks are still returned for the fences that parsed.
+func RenderGroupFences(d Dump, group string, ids []string) (map[string]string, []string) {
+	var violations []string
+	var specs []FenceSpec
+	seen := map[string]bool{}
+	for _, id := range ids {
+		spec, err := ParseFenceID(id)
+		if err != nil {
+			violations = append(violations, err.Error())
+			continue
+		}
+		if spec.Group != group {
+			violations = append(violations, fmt.Sprintf("fence %q does not belong to group %q", id, group))
+			continue
+		}
+		if seen[spec.ID()] {
+			violations = append(violations, fmt.Sprintf("fence %q appears more than once", id))
+			continue
+		}
+		seen[spec.ID()] = true
+		specs = append(specs, spec)
+	}
+
+	byID := make(map[string][]Command, len(specs))
+	catchAll := ""
+	hasCatchAll := false
+	for _, s := range specs {
+		byID[s.ID()] = nil
+		if len(s.Prefixes) == 0 {
+			catchAll = s.ID()
+			hasCatchAll = true
+		}
+	}
+
+	// Partition the group's verbs among the specs. A verb matching several
+	// prefixes of ONE spec is fine (all count as live); matching prefixes of
+	// two specs is a double claim.
+	prefixHit := map[string]bool{} // spec id + "\x00" + prefix → claimed something
+	var unclaimed []string
+	for _, c := range groupCommands(d, group) {
+		verb := verbOf(c.Path)
+		var owners []string
+		for _, s := range specs {
+			matched := false
+			for _, p := range s.Prefixes {
+				if strings.HasPrefix(verb, p) {
+					prefixHit[s.ID()+"\x00"+p] = true
+					matched = true
+				}
+			}
+			if matched {
+				owners = append(owners, s.ID())
+			}
+		}
+		switch {
+		case len(owners) > 1:
+			violations = append(violations, fmt.Sprintf("verb %q claimed by %s", verb, strings.Join(owners, " and ")))
+		case len(owners) == 1:
+			byID[owners[0]] = append(byID[owners[0]], c)
+		case hasCatchAll:
+			byID[catchAll] = append(byID[catchAll], c)
+		default:
+			unclaimed = append(unclaimed, verb)
+		}
+	}
+	if len(unclaimed) > 0 {
+		violations = append(violations, fmt.Sprintf("group %q has no catch-all fence for unclaimed verbs: %s", group, strings.Join(unclaimed, ", ")))
+	}
+	for _, s := range specs {
+		for _, p := range s.Prefixes {
+			if !prefixHit[s.ID()+"\x00"+p] {
+				violations = append(violations, fmt.Sprintf("fence %q: prefix %q claims no verb", s.ID(), p))
+			}
+		}
+	}
+
+	out := make(map[string]string, len(specs))
+	for _, s := range specs {
+		out[s.ID()] = renderFence(s.ID(), byID[s.ID()])
+	}
+	sort.Strings(violations)
+	return out, violations
+}