fix(ready): --explain sorts a ready issue's blocking edges by status instead of calling a pinned dependency resolved (#7124)

* fix(ready): --explain sorts a ready issue's blocking edges by status instead of calling a pinned dependency resolved (wy-0h6t03)

The ready query skips a pinned target exactly as it skips a closed one, so a
blocks edge onto a pinned bead never fences its dependent. The explanation
never read the target's status: every blocking edge of a ready issue was
appended to ResolvedBlockers, so a bead wired behind a long-lived pinned
bring-up reported "1 blocker(s) resolved" while its precondition was unmet.
Two trials sat on a takeable front for days that way.

BuildReadyExplanation now sorts each blocks / conditional-blocks / waits-for
edge by the target's status in blockerMap: closed stays under
ResolvedBlockers, pinned goes to PinnedDependencies (never block), any other
status to OpenDependencies (not blocking; the #6066 shape, now visible). A
target without a status in the map keeps the old treatment. Reason keeps its
"N blocker(s) resolved" lead and appends the other two counts as clauses.

Both explain routes previously fetched only the blockers of blocked issues,
so no ready target ever had a status; explainBlockerIDs now adds the ready
issues' blocking-dependency targets to that one batch fetch, once each, and
printReadyItemDependencies prints the three lines for both routes.

Pinned-never-blocks itself is unchanged.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* build(bazel): list ready_explain_ids_test.go in the cmd/bd go_test srcs (wy-0h6t03)

The equivalence gate named TestExplainBlockerIDs and
TestExplainBlockerIDs_Empty as tests go test runs that Bazel did not: the
new test file was never added to BUILD.bazel.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Bee 2026-10-06 22:46:47 +00:00 • committed by GitHub
commit 2e7637757f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
7 changed files with 289 additions and 45 deletions

View file

@ -144,6 +144,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
is still ridden out within one command. A backend that drops a connection
after the greeting, a dial timeout, and every refusal from a managed (local
sidecar) backend keep the full transient retry.
- **`bd ready --explain` no longer reports a pinned dependency as a resolved
blocker.** The ready query skips a pinned target exactly as it skips a closed
one, so a `blocks` edge onto a pinned bead never fences its dependent — but
the explanation listed every blocking edge of a ready issue under
`Resolved blockers`, status unread, and a bead wired behind a long-lived
pinned bring-up reported itself satisfied while its precondition was unmet.
Each blocking edge is now sorted by the target's status: closed under
`Resolved blockers` (and `resolved_blockers`), pinned under
`Pinned dependencies (never block)` (`pinned_dependencies`), and any other
status under `Open dependencies (not blocking)` (`open_dependencies`) — the
shape #6066 reports for a foreign-prefix blocker, now visible instead of
passing as resolved. `Reason` keeps its `N blocker(s) resolved` lead and
appends the pinned and open counts as clauses. Both routes fetch the ready
issues' dependency targets alongside the blockers they already fetched.
Pinned-never-blocks itself is unchanged.
- **`bd list` no longer silently drops all but the last repeated filter flag.**
`--status`, `--state`, and `--id` were plain string flags, so
`bd list --status open --status closed --status pinned` kept only `pinned` —

View file

@ -1026,6 +1026,7 @@ go_test(
"readonly_policy_test.go",
"readonly_test.go",
"ready_embedded_test.go",
"ready_explain_ids_test.go",
"ready_input_test.go",
"ready_max_rows_proxied_test.go",
"ready_max_rows_test.go",

View file

@ -554,17 +554,11 @@ func runReadyExplain(_ *cobra.Command) error {
debug.Logf("warning: failed to detect cycles: %v", err)
}
// Collect all blocker IDs to batch-fetch blocker details
allBlockerIDs := make(map[string]bool)
for _, bi := range blockedIssues {
for _, blockerID := range bi.BlockedBy {
allBlockerIDs[blockerID] = true
}
}
blockerIDList := make([]string, 0, len(allBlockerIDs))
for id := range allBlockerIDs {
blockerIDList = append(blockerIDList, id)
}
// Collect all blocker IDs to batch-fetch blocker details: the blockers
// of blocked issues, plus the blocking-dependency targets of the ready
// issues, whose status decides whether --explain reports each as
// resolved, pinned or open.
blockerIDList := explainBlockerIDs(blockedIssues, readyIssues, allDeps)
// Build ready items with explanations
// TODO(batchgetter): unbounded id list; see issueops.BatchGetter's doc and
@ -596,9 +590,7 @@ func runReadyExplain(_ *cobra.Command) error {
ui.RenderPriority(item.Priority),
item.Title)
fmt.Printf(" Reason: %s\n", item.Reason)
if len(item.ResolvedBlockers) > 0 {
fmt.Printf(" Resolved blockers: %s\n", strings.Join(item.ResolvedBlockers, ", "))
}
printReadyItemDependencies(item)
if item.DependentCount > 0 {
fmt.Printf(" Unblocks: %d issue(s)\n", item.DependentCount)
}
@ -808,3 +800,48 @@ func init() {
blockedCmd.Flags().StringSlice("exclude-label", []string{}, "Exclude issues that have ANY of these labels")
rootCmd.AddCommand(blockedCmd)
}
// explainBlockerIDs collects, once each, the ids whose status --explain
// needs: every blocker of a blocked issue, and the target of every blocking
// dependency (blocks, conditional-blocks, waits-for) of a ready issue. The
// ready targets matter because the ready query admits an issue whose blocking
// targets are closed OR pinned, and only the target's status tells the
// explanation which of the two it saw.
func explainBlockerIDs(blockedIssues []*types.BlockedIssue, readyIssues []*types.Issue, allDeps map[string][]*types.Dependency) []string {
seen := make(map[string]bool)
var ids []string
add := func(id string) {
if id == "" || seen[id] {
return
}
seen[id] = true
ids = append(ids, id)
}
for _, bi := range blockedIssues {
for _, blockerID := range bi.BlockedBy {
add(blockerID)
}
}
for _, issue := range readyIssues {
for _, dep := range allDeps[issue.ID] {
if dep.Type == types.DepBlocks || dep.Type == types.DepConditionalBlocks || dep.Type == types.DepWaitsFor {
add(dep.DependsOnID)
}
}
}
return ids
}
// printReadyItemDependencies prints the three dependency lines of a ready
// item in --explain's text form, each only when non-empty.
func printReadyItemDependencies(item types.ReadyItem) {
if len(item.ResolvedBlockers) > 0 {
fmt.Printf(" Resolved blockers: %s\n", strings.Join(item.ResolvedBlockers, ", "))
}
if len(item.PinnedDependencies) > 0 {
fmt.Printf(" Pinned dependencies (never block): %s\n", strings.Join(item.PinnedDependencies, ", "))
}
if len(item.OpenDependencies) > 0 {
fmt.Printf(" Open dependencies (not blocking): %s\n", strings.Join(item.OpenDependencies, ", "))
}
}

View file

@ -0,0 +1,50 @@
package main
import (
"testing"
"github.com/steveyegge/beads/internal/types"
)
// explainBlockerIDs must hand the explanation every id whose status it
// reads: the blockers of blocked issues AND the blocking-dependency targets of
// ready issues (the ones whose closed-or-pinned status the ready query
// collapsed), once each, and no parent-child or related target.
func TestExplainBlockerIDs(t *testing.T) {
blocked := []*types.BlockedIssue{
{Issue: types.Issue{ID: "bd-b1"}, BlockedBy: []string{"bd-x", "bd-y"}},
{Issue: types.Issue{ID: "bd-b2"}, BlockedBy: []string{"bd-y", ""}},
}
ready := []*types.Issue{{ID: "bd-r1"}, {ID: "bd-r2"}}
allDeps := map[string][]*types.Dependency{
"bd-r1": {
{IssueID: "bd-r1", DependsOnID: "bd-pinned", Type: types.DepBlocks},
{IssueID: "bd-r1", DependsOnID: "bd-x", Type: types.DepConditionalBlocks},
{IssueID: "bd-r1", DependsOnID: "bd-epic", Type: types.DepParentChild},
},
"bd-r2": {
{IssueID: "bd-r2", DependsOnID: "bd-spawner", Type: types.DepWaitsFor},
{IssueID: "bd-r2", DependsOnID: "bd-rel", Type: types.DepRelated},
},
"bd-not-ready": {
{IssueID: "bd-not-ready", DependsOnID: "bd-elsewhere", Type: types.DepBlocks},
},
}
got := explainBlockerIDs(blocked, ready, allDeps)
want := []string{"bd-x", "bd-y", "bd-pinned", "bd-spawner"}
if len(got) != len(want) {
t.Fatalf("explainBlockerIDs = %v, want %v", got, want)
}
for i := range want {
if got[i] != want[i] {
t.Fatalf("explainBlockerIDs = %v, want %v", got, want)
}
}
}
func TestExplainBlockerIDs_Empty(t *testing.T) {
if got := explainBlockerIDs(nil, nil, nil); len(got) != 0 {
t.Fatalf("expected no ids, got %v", got)
}
}

View file

@ -320,16 +320,7 @@ func runReadyProxiedExplain(ctx context.Context, uw uow.UnitOfWork, _ readyInput
debug.Logf("warning: failed to detect cycles: %v", err)
}
allBlockerIDs := make(map[string]bool)
for _, bi := range blockedIssues {
for _, blockerID := range bi.BlockedBy {
allBlockerIDs[blockerID] = true
}
}
blockerIDList := make([]string, 0, len(allBlockerIDs))
for id := range allBlockerIDs {
blockerIDList = append(blockerIDList, id)
}
blockerIDList := explainBlockerIDs(blockedIssues, readyIssues, allDeps)
// TODO(batchgetter): unbounded id list; see issueops.BatchGetter's doc and
// the importIssueLookup TODO in import_shared.go for why this is not yet
// routed through GetMany.
@ -365,9 +356,7 @@ func runReadyProxiedExplain(ctx context.Context, uw uow.UnitOfWork, _ readyInput
ui.RenderPriority(item.Priority),
item.Title)
fmt.Printf(" Reason: %s\n", item.Reason)
if len(item.ResolvedBlockers) > 0 {
fmt.Printf(" Resolved blockers: %s\n", strings.Join(item.ResolvedBlockers, ", "))
}
printReadyItemDependencies(item)
if item.DependentCount > 0 {
fmt.Printf(" Unblocks: %d issue(s)\n", item.DependentCount)
}

View file

@ -62,6 +62,9 @@ func TestBuildReadyExplanation_ReadyWithResolvedBlockers(t *testing.T) {
},
}
// A nil blockerMap supplies no statuses: the ready set's verdict is the
// only word, so every blocking edge counts as resolved (the pre-#6066
// shape, kept for callers that fetch nothing).
result := BuildReadyExplanation(issues, nil, depCounts, allDeps, nil, nil)
if len(result.Ready) != 1 {
@ -75,6 +78,9 @@ func TestBuildReadyExplanation_ReadyWithResolvedBlockers(t *testing.T) {
if len(item.ResolvedBlockers) != 2 {
t.Errorf("expected 2 resolved blockers, got %d", len(item.ResolvedBlockers))
}
if len(item.PinnedDependencies) != 0 || len(item.OpenDependencies) != 0 {
t.Errorf("expected no pinned/open dependencies without statuses, got %v / %v", item.PinnedDependencies, item.OpenDependencies)
}
if item.DependencyCount != 2 {
t.Errorf("expected DependencyCount=2, got %d", item.DependencyCount)
}
@ -83,6 +89,103 @@ func TestBuildReadyExplanation_ReadyWithResolvedBlockers(t *testing.T) {
}
}
// A ready issue's blocking edges are sorted by the target's status: closed is
// a resolved blocker, pinned never blocked (the ready query skips pinned
// targets as it skips closed ones), anything else is an open dependency the
// ready set admitted anyway. Before this every edge printed as "resolved",
// so a dependency wired onto a pinned bead reported itself satisfied.
func TestBuildReadyExplanation_ReadyDependencyStatuses(t *testing.T) {
issues := []*Issue{
{ID: "bd-1", Title: "Ready", Priority: 1, Status: StatusOpen},
}
allDeps := map[string][]*Dependency{
"bd-1": {
{IssueID: "bd-1", DependsOnID: "bd-closed", Type: DepBlocks},
{IssueID: "bd-1", DependsOnID: "bd-pinned", Type: DepBlocks},
{IssueID: "bd-1", DependsOnID: "bd-open", Type: DepBlocks},
{IssueID: "bd-1", DependsOnID: "bd-spawner", Type: DepWaitsFor},
{IssueID: "bd-1", DependsOnID: "bd-unknown", Type: DepConditionalBlocks},
{IssueID: "bd-1", DependsOnID: "bd-epic", Type: DepParentChild},
{IssueID: "bd-1", DependsOnID: "bd-related", Type: DepRelated},
},
}
blockerMap := map[string]*Issue{
"bd-closed": {ID: "bd-closed", Status: StatusClosed},
"bd-pinned": {ID: "bd-pinned", Status: StatusPinned},
"bd-open": {ID: "bd-open", Status: StatusOpen},
"bd-spawner": {ID: "bd-spawner", Status: StatusInProgress},
"bd-epic": {ID: "bd-epic", Status: StatusOpen},
}
result := BuildReadyExplanation(issues, nil, nil, allDeps, blockerMap, nil)
if len(result.Ready) != 1 {
t.Fatalf("expected 1 ready item, got %d", len(result.Ready))
}
item := result.Ready[0]
// bd-unknown has no status in the map and so joins the resolved set.
assertIDs(t, "ResolvedBlockers", item.ResolvedBlockers, "bd-closed", "bd-unknown")
assertIDs(t, "PinnedDependencies", item.PinnedDependencies, "bd-pinned")
assertIDs(t, "OpenDependencies", item.OpenDependencies, "bd-open", "bd-spawner")
want := "2 blocker(s) resolved; 1 pinned dependency(ies), never blocking; 2 open dependency(ies), not blocking"
if item.Reason != want {
t.Errorf("reason:\n got %q\nwant %q", item.Reason, want)
}
if item.Parent == nil || *item.Parent != "bd-epic" {
t.Errorf("expected Parent=bd-epic, got %v", item.Parent)
}
}
// Only pinned edges: the reason must not claim anything was resolved.
func TestBuildReadyExplanation_ReadyWithOnlyPinnedDependency(t *testing.T) {
issues := []*Issue{{ID: "bd-1", Title: "Ready", Priority: 1, Status: StatusOpen}}
allDeps := map[string][]*Dependency{
"bd-1": {{IssueID: "bd-1", DependsOnID: "bd-pinned", Type: DepBlocks}},
}
blockerMap := map[string]*Issue{"bd-pinned": {ID: "bd-pinned", Status: StatusPinned}}
item := BuildReadyExplanation(issues, nil, nil, allDeps, blockerMap, nil).Ready[0]
if item.Reason != "1 pinned dependency(ies), never blocking" {
t.Errorf("unexpected reason %q", item.Reason)
}
if len(item.ResolvedBlockers) != 0 {
t.Errorf("expected no resolved blockers, got %v", item.ResolvedBlockers)
}
assertIDs(t, "PinnedDependencies", item.PinnedDependencies, "bd-pinned")
}
func TestReadyReason(t *testing.T) {
cases := []struct {
resolved, pinned, open int
want string
}{
{0, 0, 0, "no blocking dependencies"},
{2, 0, 0, "2 blocker(s) resolved"},
{0, 1, 0, "1 pinned dependency(ies), never blocking"},
{0, 0, 3, "3 open dependency(ies), not blocking"},
{1, 1, 1, "1 blocker(s) resolved; 1 pinned dependency(ies), never blocking; 1 open dependency(ies), not blocking"},
}
for _, c := range cases {
if got := readyReason(c.resolved, c.pinned, c.open); got != c.want {
t.Errorf("readyReason(%d,%d,%d) = %q, want %q", c.resolved, c.pinned, c.open, got, c.want)
}
}
}
func assertIDs(t *testing.T, field string, got []string, want ...string) {
t.Helper()
if len(got) != len(want) {
t.Errorf("%s = %v, want %v", field, got, want)
return
}
for i := range want {
if got[i] != want[i] {
t.Errorf("%s = %v, want %v", field, got, want)
return
}
}
}
func TestBuildReadyExplanation_ReadyWithParent(t *testing.T) {
issues := []*Issue{
{ID: "bd-child", Title: "Child task", Priority: 2, Status: StatusOpen},

View file

@ -1869,13 +1869,26 @@ type ReadyExplanation struct {
}
// ReadyItem explains why a specific issue is ready for work.
//
// The issue's blocking dependencies (blocks, conditional-blocks, waits-for)
// are sorted by the target's status as the caller supplied it in blockerMap:
// ResolvedBlockers holds closed targets, PinnedDependencies holds pinned ones
// (a pinned bead never blocks, so a dependency on one never fenced this
// issue — it is reported as what it is, not as a blocker that was resolved),
// and OpenDependencies holds targets in any other status — a blocks edge
// here means the ready set and the edge disagree (foreign-prefix ids, #6066);
// a waits-for edge here is the ordinary spawner-still-open case. A target the
// caller did not supply a status for is counted under ResolvedBlockers, the
// ready set's own verdict being the only word available.
type ReadyItem struct {
*Issue
Reason string `json:"reason"`
ResolvedBlockers []string `json:"resolved_blockers"`
DependencyCount int `json:"dependency_count"`
DependentCount int `json:"dependent_count"`
Parent *string `json:"parent,omitempty"`
Reason string `json:"reason"`
ResolvedBlockers []string `json:"resolved_blockers"`
PinnedDependencies []string `json:"pinned_dependencies,omitempty"`
OpenDependencies []string `json:"open_dependencies,omitempty"`
DependencyCount int `json:"dependency_count"`
DependentCount int `json:"dependent_count"`
Parent *string `json:"parent,omitempty"`
}
// BlockedItem explains why a specific issue is blocked.
@ -1918,18 +1931,29 @@ func BuildReadyExplanation(
counts = &DependencyCounts{}
}
// Find resolved blockers (closed issues that this depended on)
var resolvedBlockers []string
reason := "no blocking dependencies"
// Sort the blocking dependencies by the target's status. Before this
// every blocking edge of a ready issue was printed as a resolved
// blocker, which is wrong for a pinned target: the ready query skips
// pinned targets exactly as it skips closed ones, so a dependency on
// a pinned bead never blocked anything and nothing about it was
// resolved. --explain is the one place a reader can see that.
var resolvedBlockers, pinnedDeps, openDeps []string
deps := allDeps[issue.ID]
for _, dep := range deps {
if dep.Type == DepBlocks || dep.Type == DepConditionalBlocks || dep.Type == DepWaitsFor {
if dep.Type != DepBlocks && dep.Type != DepConditionalBlocks && dep.Type != DepWaitsFor {
continue
}
target, known := blockerMap[dep.DependsOnID]
switch {
case !known || target == nil || target.Status == StatusClosed:
resolvedBlockers = append(resolvedBlockers, dep.DependsOnID)
case target.Status == StatusPinned:
pinnedDeps = append(pinnedDeps, dep.DependsOnID)
default:
openDeps = append(openDeps, dep.DependsOnID)
}
}
if len(resolvedBlockers) > 0 {
reason = fmt.Sprintf("%d blocker(s) resolved", len(resolvedBlockers))
}
reason := readyReason(len(resolvedBlockers), len(pinnedDeps), len(openDeps))
// Compute parent
var parent *string
@ -1941,12 +1965,14 @@ func BuildReadyExplanation(
}
readyItems = append(readyItems, ReadyItem{
Issue: issue,
Reason: reason,
ResolvedBlockers: resolvedBlockers,
DependencyCount: counts.DependencyCount,
DependentCount: counts.DependentCount,
Parent: parent,
Issue: issue,
Reason: reason,
ResolvedBlockers: resolvedBlockers,
PinnedDependencies: pinnedDeps,
OpenDependencies: openDeps,
DependencyCount: counts.DependencyCount,
DependentCount: counts.DependentCount,
Parent: parent,
})
}
@ -1992,6 +2018,28 @@ func BuildReadyExplanation(
}
}
// readyReason words a ReadyItem's Reason from the three dependency counts.
// "no blocking dependencies" is kept verbatim for the no-edge case; a resolved
// count keeps the historical "N blocker(s) resolved" lead so scripts that
// match on it still do; pinned and open counts are appended as clauses rather
// than folded into the resolved count.
func readyReason(resolved, pinned, open int) string {
var parts []string
if resolved > 0 {
parts = append(parts, fmt.Sprintf("%d blocker(s) resolved", resolved))
}
if pinned > 0 {
parts = append(parts, fmt.Sprintf("%d pinned dependency(ies), never blocking", pinned))
}
if open > 0 {
parts = append(parts, fmt.Sprintf("%d open dependency(ies), not blocking", open))
}
if len(parts) == 0 {
return "no blocking dependencies"
}
return strings.Join(parts, "; ")
}
// TreeNode represents a node in a dependency tree
type TreeNode struct {
Issue