feat(epic): add --reason to bd epic close-eligible (GH#4817) (#4820)

* feat(epic): add --reason to bd epic close-eligible (GH#4817)

bd epic close-eligible hardcoded the close reason "All children completed",
so an agent that finishes an epic's children could not attach an
evidence-mapped reason to the epic close. Combined with GH#4816, a follow-up
`bd close <epic> --reason ...` silently lost that reason too (first close
wins), so close-eligible was effectively reason-lossy.

Add -r/--reason, one shared reason applied to every epic the command closes;
the default stays "All children completed" so existing behavior is unchanged.
The human dry-run preview and the final line now show the reason, and the
non-dry-run JSON payload gains a "reason" key ({"closed", "count", "reason"}).
The dry-run --json shape (array of epic statuses) is deliberately unchanged:
the reason there is an input the consumer already knows, and reshaping the
array into an object would break existing consumers.

CLI reference regenerated via scripts/generate-cli-docs.sh (epic pages only).

Tests (cmd/bd/epic_embedded_test.go): --reason persists to close_reason,
default reason unchanged, dry-run previews the reason without closing, JSON
includes the reason. All but the default-reason guard fail before this change
(unknown flag); the guard is green by design.

* fix(epic): address close-eligible --reason review feedback

1. Run validation.on-close check before closing — epic close-eligible
   now calls validateCloseReasons (same as bd close) so configured
   validators apply uniformly.

2. Fix JSON shape for nothing-eligible path — outputNoEligibleEpics now
   returns {"closed":[],"count":0,"reason":"..."} instead of [] so the
   JSON contract is total regardless of whether epics were found.

3. Move reason to final output line — human-mode output now lists IDs
   first, then prints the summary with reason on the last line. Added
   close_eligible_human_output_ends_with_reason test to pin this.

4. Add proxied-mode reason test — write_closes_with_reason in the
   proxied integration suite verifies --reason persists to CloseReason
   through the full UOW transaction path.
This commit is contained in:
Kevin Glynn 2026-07-26 15:29:15 -04:00 • committed by GitHub
commit e5ecb200db
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 174 additions and 17 deletions

View file

@ -2,13 +2,19 @@ package main
import (
"fmt"
"os"
"strings"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/metrics"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/internal/ui"
"os"
)
// defaultCloseEligibleReason is the close reason `bd epic close-eligible` has
// always used; --reason overrides it (GH#4817).
const defaultCloseEligibleReason = "All children completed"
var epicCmd = &cobra.Command{
Use: "epic",
GroupID: "deps",
@ -90,6 +96,14 @@ func filterEligibleEpics(epics []*types.EpicStatus) []*types.EpicStatus {
return filtered
}
func resolveCloseEligibleReason(cmd *cobra.Command) string {
reason, _ := cmd.Flags().GetString("reason")
if strings.TrimSpace(reason) == "" {
return defaultCloseEligibleReason
}
return reason
}
var closeEligibleEpicsCmd = &cobra.Command{
Use: "close-eligible",
Short: "Close epics where all children are complete",
@ -104,9 +118,14 @@ var closeEligibleEpicsCmd = &cobra.Command{
}()
dryRun, _ := cmd.Flags().GetBool("dry-run")
reason := resolveCloseEligibleReason(cmd)
if err := validateCloseReasons([]string{reason}); err != nil {
return HandleErrorRespectJSON("%v", err)
}
if usesProxiedServer() {
return runCloseEligibleEpicsProxiedServer(rootCtx, dryRun)
return runCloseEligibleEpicsProxiedServer(rootCtx, dryRun, reason)
}
if !dryRun {
@ -118,14 +137,14 @@ var closeEligibleEpicsCmd = &cobra.Command{
}
eligibleEpics := filterEligibleEpics(epics)
if len(eligibleEpics) == 0 {
return outputNoEligibleEpics()
return outputNoEligibleEpics(reason)
}
if dryRun {
return outputCloseEligibleDryRun(eligibleEpics)
return outputCloseEligibleDryRun(eligibleEpics, reason)
}
closedIDs := []string{}
for _, epicStatus := range eligibleEpics {
err := store.CloseIssue(rootCtx, epicStatus.Epic.ID, "All children completed", "system", "")
err := store.CloseIssue(rootCtx, epicStatus.Epic.ID, reason, "system", "")
if err != nil {
fmt.Fprintf(os.Stderr, "Error closing %s: %v\n", epicStatus.Epic.ID, err)
continue
@ -135,40 +154,45 @@ var closeEligibleEpicsCmd = &cobra.Command{
if len(closedIDs) > 0 {
commandDidWrite.Store(true)
}
return outputCloseEligibleResult(closedIDs)
return outputCloseEligibleResult(closedIDs, reason)
},
}
func outputNoEligibleEpics() error {
func outputNoEligibleEpics(reason string) error {
if jsonOutput {
return outputJSON([]*types.EpicStatus{})
return outputJSON(map[string]interface{}{
"closed": []string{},
"count": 0,
"reason": reason,
})
}
fmt.Println("No epics eligible for closure")
return nil
}
func outputCloseEligibleDryRun(eligibleEpics []*types.EpicStatus) error {
func outputCloseEligibleDryRun(eligibleEpics []*types.EpicStatus, reason string) error {
if jsonOutput {
return outputJSON(eligibleEpics)
}
fmt.Printf("Would close %d epic(s):\n", len(eligibleEpics))
fmt.Printf("Would close %d epic(s) with reason %q:\n", len(eligibleEpics), reason)
for _, epicStatus := range eligibleEpics {
fmt.Printf(" - %s: %s\n", epicStatus.Epic.ID, epicStatus.Epic.Title)
}
return nil
}
func outputCloseEligibleResult(closedIDs []string) error {
func outputCloseEligibleResult(closedIDs []string, reason string) error {
if jsonOutput {
return outputJSON(map[string]interface{}{
"closed": closedIDs,
"count": len(closedIDs),
"reason": reason,
})
}
fmt.Printf("✓ Closed %d epic(s)\n", len(closedIDs))
for _, id := range closedIDs {
fmt.Printf(" - %s\n", id)
}
fmt.Printf("✓ Closed %d epic(s) with reason %q\n", len(closedIDs), reason)
return nil
}
@ -177,5 +201,6 @@ func init() {
epicCmd.AddCommand(closeEligibleEpicsCmd)
epicStatusCmd.Flags().Bool("eligible-only", false, "Show only epics eligible for closure")
closeEligibleEpicsCmd.Flags().Bool("dry-run", false, "Preview what would be closed without making changes")
closeEligibleEpicsCmd.Flags().StringP("reason", "r", defaultCloseEligibleReason, "Close reason applied to every epic closed")
rootCmd.AddCommand(epicCmd)
}

View file

@ -178,6 +178,106 @@ func TestEmbeddedEpic(t *testing.T) {
t.Errorf("epic1 should not be closed: %s", out)
}
})
// ===== epic close-eligible --reason (GH#4817) =====
t.Run("close_eligible_reason_flag_persists", func(t *testing.T) {
dir5, _, _ := bdInit(t, bd, "--prefix", "ep5")
e := bdCreate(t, bd, dir5, "Reason epic", "--type", "epic")
ch := bdCreate(t, bd, dir5, "Reason child", "--type", "task")
bdDep(t, bd, dir5, "add", ch.ID, e.ID, "--type", "parent-child")
bdClose(t, bd, dir5, ch.ID)
bdEpic(t, bd, dir5, "close-eligible", "--reason", "Milestone shipped in v2.3")
got := bdShow(t, bd, dir5, e.ID)
if got.Status != types.StatusClosed {
t.Fatalf("expected epic closed, got %s", got.Status)
}
if got.CloseReason != "Milestone shipped in v2.3" {
t.Errorf("close_reason = %q, want %q", got.CloseReason, "Milestone shipped in v2.3")
}
})
t.Run("close_eligible_default_reason_unchanged", func(t *testing.T) {
dir6, _, _ := bdInit(t, bd, "--prefix", "ep6")
e := bdCreate(t, bd, dir6, "Default reason epic", "--type", "epic")
ch := bdCreate(t, bd, dir6, "Default reason child", "--type", "task")
bdDep(t, bd, dir6, "add", ch.ID, e.ID, "--type", "parent-child")
bdClose(t, bd, dir6, ch.ID)
bdEpic(t, bd, dir6, "close-eligible")
got := bdShow(t, bd, dir6, e.ID)
if got.CloseReason != "All children completed" {
t.Errorf("close_reason = %q, want default %q", got.CloseReason, "All children completed")
}
})
t.Run("close_eligible_dry_run_shows_reason", func(t *testing.T) {
dir7, _, _ := bdInit(t, bd, "--prefix", "ep7")
e := bdCreate(t, bd, dir7, "Dry-run reason epic", "--type", "epic")
ch := bdCreate(t, bd, dir7, "Dry-run reason child", "--type", "task")
bdDep(t, bd, dir7, "add", ch.ID, e.ID, "--type", "parent-child")
bdClose(t, bd, dir7, ch.ID)
out := bdEpic(t, bd, dir7, "close-eligible", "--dry-run", "--reason", "planned reason")
if !strings.Contains(out, "Would close") || !strings.Contains(out, "planned reason") {
t.Errorf("dry-run output should preview the reason, got: %s", out)
}
got := bdShow(t, bd, dir7, e.ID)
if got.Status != types.StatusOpen {
t.Errorf("dry-run must not close the epic, got %s", got.Status)
}
})
t.Run("close_eligible_json_includes_reason", func(t *testing.T) {
dir8, _, _ := bdInit(t, bd, "--prefix", "ep8")
e := bdCreate(t, bd, dir8, "JSON reason epic", "--type", "epic")
ch := bdCreate(t, bd, dir8, "JSON reason child", "--type", "task")
bdDep(t, bd, dir8, "add", ch.ID, e.ID, "--type", "parent-child")
bdClose(t, bd, dir8, ch.ID)
result := bdEpicJSON(t, bd, dir8, "close-eligible", "--reason", "JSON reason")
obj, ok := result.(map[string]interface{})
if !ok {
t.Fatalf("expected JSON object, got %T", result)
}
if reason, _ := obj["reason"].(string); reason != "JSON reason" {
t.Errorf("reason = %q, want %q", reason, "JSON reason")
}
closed, _ := obj["closed"].([]interface{})
found := false
for _, id := range closed {
if id == e.ID {
found = true
}
}
if !found {
t.Errorf("closed = %v, want it to contain %s", closed, e.ID)
}
})
t.Run("close_eligible_human_output_ends_with_reason", func(t *testing.T) {
dir9, _, _ := bdInit(t, bd, "--prefix", "ep9")
e := bdCreate(t, bd, dir9, "Output epic", "--type", "epic")
ch := bdCreate(t, bd, dir9, "Output child", "--type", "task")
bdDep(t, bd, dir9, "add", ch.ID, e.ID, "--type", "parent-child")
bdClose(t, bd, dir9, ch.ID)
out := bdEpic(t, bd, dir9, "close-eligible", "--reason", "ship it")
lines := strings.Split(strings.TrimSpace(out), "\n")
lastLine := lines[len(lines)-1]
if !strings.Contains(lastLine, "ship it") {
t.Errorf("final output line should contain the reason, got: %q", lastLine)
}
if !strings.Contains(lastLine, "Closed") {
t.Errorf("final output line should contain Closed summary, got: %q", lastLine)
}
if !strings.Contains(out, e.ID) {
t.Errorf("output should list closed epic ID %s, got: %s", e.ID, out)
}
})
}
// TestEmbeddedEpicConcurrent exercises epic operations concurrently.

View file

@ -178,4 +178,36 @@ func TestProxiedServerEpic(t *testing.T) {
t.Errorf("epic %s should be closed after close-eligible, got %s", epic.ID, show.Status)
}
})
t.Run("write_closes_with_reason", func(t *testing.T) {
p2 := newSharedProxiedProject(t, bd, "epr")
e2 := bdProxiedCreate(t, bd, p2.dir, "Reason epic", "--type", "epic")
c2a := bdProxiedCreate(t, bd, p2.dir, "Reason child", "--type", "task", "--parent", e2.ID)
if out, err := bdProxiedRun(t, bd, p2.dir, "close", c2a.ID); err != nil {
t.Fatalf("close child: %v\n%s", err, out)
}
out, err := bdProxiedRun(t, bd, p2.dir, "epic", "close-eligible", "--reason", "Sprint goal met", "--json")
if err != nil {
t.Fatalf("close-eligible --reason: %v\n%s", err, out)
}
var res struct {
Closed []string `json:"closed"`
Count int `json:"count"`
Reason string `json:"reason"`
}
if err := json.Unmarshal(out, &res); err != nil {
t.Fatalf("unmarshal: %v\n%s", err, out)
}
if res.Reason != "Sprint goal met" {
t.Errorf("reason = %q, want %q", res.Reason, "Sprint goal met")
}
show := bdProxiedShow(t, bd, p2.dir, e2.ID)
if show.Status != types.StatusClosed {
t.Errorf("epic should be closed, got %s", show.Status)
}
if show.CloseReason != "Sprint goal met" {
t.Errorf("persisted close_reason = %q, want %q", show.CloseReason, "Sprint goal met")
}
})
}

View file

@ -23,7 +23,7 @@ func runEpicStatusProxiedServer(ctx context.Context, eligibleOnly bool) error {
return renderEpicStatus(epics, eligibleOnly)
}
func runCloseEligibleEpicsProxiedServer(ctx context.Context, dryRun bool) error {
func runCloseEligibleEpicsProxiedServer(ctx context.Context, dryRun bool, reason string) error {
uw, err := openProxiedListUOW(ctx)
if err != nil {
return HandleError("%v", err)
@ -37,10 +37,10 @@ func runCloseEligibleEpicsProxiedServer(ctx context.Context, dryRun bool) error
uw.Close(ctx)
if len(eligibleEpics) == 0 {
return outputNoEligibleEpics()
return outputNoEligibleEpics(reason)
}
if dryRun {
return outputCloseEligibleDryRun(eligibleEpics)
return outputCloseEligibleDryRun(eligibleEpics, reason)
}
if uowProvider == nil {
@ -54,7 +54,7 @@ func runCloseEligibleEpicsProxiedServer(ctx context.Context, dryRun bool) error
}
var closed []string
for _, epicStatus := range filterEligibleEpics(epics) {
if _, err := uw.IssueUseCase().CloseIssue(ctx, epicStatus.Epic.ID, domain.CloseIssueParams{Reason: "All children completed"}, "system"); err != nil {
if _, err := uw.IssueUseCase().CloseIssue(ctx, epicStatus.Epic.ID, domain.CloseIssueParams{Reason: reason}, "system"); err != nil {
fmt.Fprintf(os.Stderr, "Error closing %s: %v\n", epicStatus.Epic.ID, err)
continue
}
@ -68,5 +68,5 @@ func runCloseEligibleEpicsProxiedServer(ctx context.Context, dryRun bool) error
if len(closedIDs) > 0 {
commandDidWrite.Store(true)
}
return outputCloseEligibleResult(closedIDs)
return outputCloseEligibleResult(closedIDs, reason)
}