beads/website/versioned_docs/version-1.0.4/cli-reference/dep.md
Julian Knutsen e8ae7a291a
feat(count): add --include-infra for exact bd list cardinality parity (#4389)
* feat(count): add --include-infra for exact bd list cardinality parity

bd count hardcoded filter.SkipWisps=true (9a29a158f, Q2 SQL-COUNT rewrite),
so it only counted the durable issues table. bd list --include-infra merges
the wisps table — including no_history beads, which are durable work — so no
count invocation could match a list cardinality. On the production gascity
rig store that meant bd count --type task = 23,777 vs a list --include-infra
cardinality of 33,601: a 29% undercount that blocks Gas City from
implementing an exact Counter over the bd CLI (its bounded-read pagination
needs Total to be exact).

Changes:

- cmd/bd/count.go: new --include-infra flag mirroring bd list's flag.
  applyCountIncludeInfra reproduces the buildListFilter defaults that
  determine list's cardinality under --include-infra: wisps merge
  (SkipWisps=false), template exclusion (IsTemplate=false), default gate
  exclusion unless --type gate, and infra-type routing to the ephemeral
  tier using the store-configured infra set. Without the flag the filter
  construction is unchanged (SkipWisps=true), keeping the widely-scripted
  default byte-identical.
- internal/storage/{dolt,embeddeddolt}/counts.go: CountIssues now delegates
  to issueops.CountIssuesInTx (extended with the query param) instead of a
  hardcoded SELECT COUNT(*) FROM issues, so SkipWisps/Ephemeral routing
  matches SearchIssuesInTx. CountIssuesInTx previously had no production
  callers.
- internal/storage/issueops/count.go: CountIssuesByGroupInTx now honors
  SkipWisps/Ephemeral with the same merge semantics, so --by-* grouped
  counts under --include-infra report merged buckets instead of
  silently-wrong durable-only numbers.
- Tests (TDD): cmd/bd/count_filter_test.go pins the count filter against
  buildListFilter field-by-field; internal/storage/dolt/
  count_include_wisps_test.go asserts CountIssues == len(SearchIssues) for
  the trap filters (templates, no_history, ephemeral) and merged grouped
  counts; cmd/bd/count_embedded_test.go adds CLI-level count==list parity.
- Docs: regenerated CLI reference (also picks up pre-existing dep/import
  help-text drift so scripts/check-doc-flags.sh passes) and one pre-existing
  gofmt fix in issueops/search.go for ci-pr-lint.

Verification on the production gascity rig store (read-only):

  bd count --include-infra --type task  = 33,601
  bd list  --include-infra --type task --all --json --limit 0 | len = 33,601
  bd count --include-infra              = 42,631  (list equivalent: 42,631)
  bd count --include-infra --status open = 1,969  (list equivalent: 1,969)
  bd count --include-infra --by-type    : total 42,631, task bucket 33,601
  bd count --type task (no flag)        = 23,777  (stock bd 1.0.5: 23,777)

Gates: make ci-pr-core (go test -race -short), ci-pr-policy, ci-pr-lint,
go vet ./..., embedded count/list suites, full dolt + embeddeddolt
storage packages.

Fixes #4387

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

* fix(cli): write-intent routing for all mutating commands; count ephemeral parity; pin bulk dep cycle gate

Adopt-PR review fixes for PR #4389 on top of the pre-review CI repair.

Routed write surface (#4141, bd-6dnrw.32, GH#3231): bd-6dnrw.32 gave
read-only opens a real read-only path, which silently broke routed sibling
writes -- prefix-routed resolution opened the target read-only, so a mutating
command on a routes.jsonl-routed ID failed with "store is read-only". The
earlier CI repair restored update/comment/comments add/note/reopen; review
found the rest of the mutating surface still broken. Write intent now covers
every prefix-routed mutating command: assign, priority, tag, edit, delete
(single + batch), close (resolveCloseTargets), human respond/dismiss, link,
and dep add/--blocks/remove/bulk (via a new resolveIDWithRoutingForWrite).
The source issue's store opens writable so the write commits on the target
head; read paths, dependency-target ID resolution, dep tree, and contributor
auto-routing stay read-only, preserving the bd-6dnrw.32/GH#3231 guarantee
that routed reads never mutate a foreign project's history. Regression test
TestEmbeddedRoutedMutatingSiblingWritesCommitTargetHead pins assign/tag/
dep add/delete/close routed writes committing on the target head.

Count ephemeral parity (GH#4387): CountIssuesInTx returned the wisps count
unconditionally for an Ephemeral=true filter, while SearchIssuesInTx falls
through to the durable issues table when the wisps tier is empty. The scalar
fall-through landed first, but review (attempt 2) found the same fall-through
missing from the two sibling functions, so grouped counts and count-projection
searches still dropped a durable issues-table row flagged ephemeral=1:
CountIssuesByGroupInTx returned empty buckets while the scalar Total fell
through (sum(groups) != Total), and SearchIssuesWithCountsInTx returned nil
where SearchIssues returned the row. CountIssuesByGroupInTx and
SearchIssuesWithCountsInTx now mirror the scalar/list fall-through, so
bd count --include-infra --by-* and bd search --counts --include-infra match
bd list cardinality when only durable rows match. The scalar fall-through
comment is corrected to describe the durable ephemeral=1 defensive state
(a promoted bead carries ephemeral=0, so it never reaches this branch).
Regression tests TestCountIssuesEphemeralFallsThroughToDurable (scalar),
TestCountIssuesByGroupEphemeralFallsThroughToDurable (grouped), and
TestSearchIssuesWithCountsEphemeralFallsThroughToDurable (counts projection)
pin count==len(list) for that case; the merge path documents that list is the
disjoint-table corruption detector.

Bulk dep cycle gate (bd-6dnrw.8): unchanged from the pre-review repair --
TestEmbeddedDepBulkNoCycleCheckKeepsWholeGraphGate pins the whole-graph
cycle gate on bulk --no-cycle-check adds.

Validation (worktree, BEADS_TEST_EMBEDDED_DOLT=1, -tags gms_pure_go):
routed-write and count-parity regression tests pass; TestEmbeddedDep*,
cross-rig routing, dep/close/delete/link CLI suites, and the count
CLI/issueops suites pass; go build, go vet, gofmt, git diff --check clean.

Validation (attempt 2, grouped + counts-projection fall-through): go build
(issueops, dolt, cmd/bd) and go vet (issueops, dolt) clean; git diff --check
clean. The Dolt count/list parity suite passes against an isolated Dolt test
container (TestCountIssuesMergedMatchesSearch, the three ephemeral
fall-through regressions, TestCountIssuesByGroupIncludesWisps,
TestPR4107SearchIssuesWithCountsEphemeralFalseIncludesNoHistoryOnly); all
three fall-through regressions were verified failing on the pre-fix tree.
Embedded-engine fixtures that need the CGO/ICU build are exercised by the
GitHub PR workflow.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-06-13 04:14:28 -07:00

5.9 KiB

id title slug sidebar_position
dep bd dep /cli-reference/dep 100

Generated from bd help --doc dep

bd dep

Manage dependencies between issues.

When called with an issue ID and --blocks flag, creates a blocking dependency: bd dep <blocker-id> --blocks <blocked-id>

This is equivalent to: bd dep add <blocked-id> <blocker-id>

Examples: bd dep bd-xyz --blocks bd-abc # bd-xyz blocks bd-abc bd dep add bd-abc bd-xyz # Same as above (bd-abc depends on bd-xyz)

bd dep [issue-id] [flags]

Flags:

  -b, --blocks string    Issue ID that this issue blocks (shorthand for: bd dep add <blocked> <blocker>)
      --no-cycle-check   Skip per-edge cycle checks for speed (bulk wiring); bulk --file adds still run one final whole-graph check before commit

bd dep add

Add a dependency between two issues.

The depends-on-id can be provided as:

  • A positional argument: bd dep add issue-123 issue-456
  • A flag: bd dep add issue-123 --blocked-by issue-456
  • A flag: bd dep add issue-123 --depends-on issue-456

The --blocked-by and --depends-on flags are aliases and both mean "issue-123 depends on (is blocked by) the specified issue."

The depends-on-id can be:

  • A local issue ID (e.g., bd-xyz)
  • An external reference: external:<project>:<capability>

For bulk wiring, pass newline-delimited JSON with --file. Each line must be an object with "from" and "to" fields, and may include "type". The aliases "issue_id" and "depends_on_id" are also accepted. Use --file - to read stdin.

External references are stored as-is and resolved at query time using the external_projects config. They block the issue until the capability is "shipped" in the target project.

Examples: bd dep add bd-42 bd-41 # Positional args bd dep add bd-42 --blocked-by bd-41 # Flag syntax (same effect) bd dep add bd-42 --depends-on bd-41 # Alias (same effect) bd dep add gt-xyz external:beads:mol-run-assignee # Cross-project dependency bd dep add bd-42 bd-41 --no-cycle-check # Skip cycle check (bulk wiring) bd dep add --file deps.jsonl # Bulk JSONL: {"from":"bd-42","to":"bd-41"}

bd dep add [issue-id] [depends-on-id] [flags]

Flags:

      --blocked-by string   Issue ID that blocks the first issue (alternative to positional arg)
      --depends-on string   Issue ID that the first issue depends on (alias for --blocked-by)
      --file string         Read dependency edges from JSONL file, or '-' for stdin
      --no-cycle-check      Skip per-edge cycle checks for speed (bulk wiring); bulk --file adds still run one final whole-graph check before commit
  -t, --type string         Dependency type (blocks|tracks|related|parent-child|discovered-from|until|caused-by|validates|relates-to|supersedes) (default "blocks")

bd dep cycles

Detect dependency cycles

bd dep cycles

bd dep list

List dependencies or dependents of one or more issues with optional type filtering.

By default shows dependencies (what issues depend on). Use --direction to control:

  • down: Show dependencies (what this issue depends on) - default
  • up: Show dependents (what depends on this issue)

Multiple IDs can be provided for batch dep listing. With --json, the output is a flat array of dependency records across all requested issues.

Use --type to filter by dependency type (e.g., tracks, blocks, parent-child).

Examples: bd dep list gt-abc # Show what gt-abc depends on bd dep list gt-abc gt-def # Batch: deps for both issues bd dep list gt-abc --direction=up # Show what depends on gt-abc bd dep list gt-abc --direction=up -t tracks # Show what tracks gt-abc (convoy tracking)

bd dep list [issue-id...] [flags]

Flags:

      --direction string   Direction: 'down' (dependencies), 'up' (dependents) (default "down")
  -t, --type string        Filter by dependency type (e.g., tracks, blocks, parent-child)

bd dep relate

Create a loose 'see also' relationship between two issues.

The relates_to link is bidirectional - both issues will reference each other. This enables knowledge graph connections without blocking or hierarchy.

Examples: bd relate bd-abc bd-xyz # Link two related issues bd relate bd-123 bd-456 # Create see-also connection

bd dep relate <id1> <id2>

bd dep remove

Remove a dependency

bd dep remove [issue-id] [depends-on-id]

Aliases: rm

bd dep tree

Show dependency tree rooted at the given issue.

By default, shows dependencies (what blocks this issue). Use --direction to control:

  • down: Show dependencies (what blocks this issue) - default
  • up: Show dependents (what this issue blocks)
  • both: Show full graph in both directions

Examples: bd dep tree gt-0iqq # Show what blocks gt-0iqq bd dep tree gt-0iqq --direction=up # Show what gt-0iqq blocks bd dep tree gt-0iqq --status=open # Only show open issues bd dep tree gt-0iqq --depth=3 # Limit to 3 levels deep

bd dep tree [issue-id] [flags]

Flags:

      --direction string   Tree direction: 'down' (dependencies), 'up' (dependents), or 'both'
      --format string      Output format: 'mermaid' for Mermaid.js flowchart
  -d, --max-depth int      Maximum tree depth to display (safety limit) (default 50)
      --reverse            Show dependent tree (deprecated: use --direction=up)
      --show-all-paths     Show all paths to nodes (no deduplication for diamond dependencies)
      --status string      Filter to only show issues with this status (open, in_progress, blocked, deferred, closed)

bd dep unrelate

Remove a relates_to relationship between two issues.

Removes the link in both directions.

Example: bd unrelate bd-abc bd-xyz

bd dep unrelate <id1> <id2>