fix(skilldoc): exclude runnable command groups from card dump

newGroupCmd (#101) gives every command group a real RunE so a mistyped
subcommand fails loudly, which made Build's `c.Runnable() && !c.Hidden`
predicate start emitting a card entry for all 23 groups (incident,
oncall, change, ...). A group only dispatches to its subcommands; it has
no behavior of its own, so documenting it as an invocable command is
wrong content, not just churn.

Key the predicate off HasSubCommands() instead: every node in the tree
with children is a pure container (no command mixes its own business
logic with child commands), so this cleanly separates groups from
leaves regardless of Runnable(). Regenerating all fences with this fix
reproduces the base branch's cards byte-for-byte.

Author: ysyneu

internal/skilldoc/build.go

@@ -9,8 +9,10 @@ import (
 )
 
 // Build walks the cobra tree rooted at root and returns a structured dump of
-// every runnable, non-hidden leaf command. Group containers (non-runnable
-// parents like "status-page") are descended into but not emitted themselves.
+// every runnable, non-hidden leaf command. Group containers (parents with
+// their own subcommands, like "status-page") are descended into but not
+// emitted themselves — see the predicate comment in walk for why this is
+// keyed off subcommands rather than Runnable().
 //
 // Path is the space-joined chain of cobra command names below the root, using
 // c.Name() so a positional placeholder in Use (e.g. "change-create <page-id>")
@@ -33,7 +35,24 @@ func walk(c *cobra.Command, parents []string, d *Dump) {
 		path = append(append([]string{}, parents...), c.Name())
 	}
 
-	if c.Runnable() && !c.Hidden {
+	// A card entry is only correct for a leaf an agent can actually invoke to
+	// get work done. c.Runnable() alone is NOT that signal: every command
+	// group in this tree (alert, incident, oncall schedule, incident
+	// war-room, the generated genGroup groups, ...) is built through
+	// newGroupCmd (internal/cli/command.go), which gives it a real RunE
+	// (print help) and Args validator (groupUnknownSubcommand) so a typo'd
+	// subcommand fails loudly instead of cobra silently discarding it — see
+	// that constructor's doc comment. That makes every group Runnable too,
+	// even though its RunE does nothing but dispatch to children. The
+	// distinguishing fact is not "does it run" but "does it hold
+	// subcommands": every node in this tree with children is a pure
+	// container (verified when this predicate was fixed — no command mixes
+	// its own business logic with child commands), so HasSubCommands() is
+	// the correct group/leaf split. If that ever stops being true — a
+	// command gains both real behavior of its own AND subcommands — this
+	// predicate must change to emit a card for that command's own behavior
+	// while still not treating its children as absent.
+	if !c.HasSubCommands() && c.Runnable() && !c.Hidden {
 		d.Commands = append(d.Commands, command(c, path))
 	}
 

internal/skilldoc/build_test.go

@@ -49,3 +49,42 @@ func TestBuild_CapturesLeafWithFlagsAndRequired(t *testing.T) {
 		t.Errorf("--type should be present and required: %+v", got.Flags)
 	}
 }
+
+// runnableGroupTree mirrors internal/cli.newGroupCmd: a container command that
+// is Runnable (RunE just prints help, same as every group in the real tree —
+// alert, incident, oncall schedule, ...) purely so a mistyped subcommand fails
+// loudly instead of cobra discarding the leftover arg silently. Runnable()
+// alone therefore cannot distinguish a group from a leaf; a command with its
+// own subcommands must be excluded regardless of whether it happens to be
+// Runnable.
+func runnableGroupTree() *cobra.Command {
+	root := &cobra.Command{Use: "fduty"}
+	incident := &cobra.Command{
+		Use: "incident", Short: "Manage incidents",
+		RunE: func(cmd *cobra.Command, _ []string) error { return cmd.Help() },
+	}
+	list := &cobra.Command{Use: "list", Short: "List incidents", Run: func(*cobra.Command, []string) {}}
+	incident.AddCommand(list)
+	root.AddCommand(incident)
+	return root
+}
+
+func TestBuild_ExcludesRunnableGroupWithSubcommands(t *testing.T) {
+	d := Build(runnableGroupTree())
+
+	for _, c := range d.Commands {
+		if c.Path == "incident" {
+			t.Fatalf("group %q has subcommands and no behavior of its own beyond dispatching to them; it must not get a card entry (it would falsely document it as an invocable command): %+v", c.Path, c)
+		}
+	}
+
+	var gotLeaf bool
+	for _, c := range d.Commands {
+		if c.Path == "incident list" {
+			gotLeaf = true
+		}
+	}
+	if !gotLeaf {
+		t.Fatalf("leaf %q under a runnable group must still get a card entry; got %+v", "incident list", d.Commands)
+	}
+}