* test(delete): pin that a stale id never deletes the issue it prefixes (be-ksd) bd delete resolves each id through the abbreviation-tolerant resolver (resolveAndGetIssueForMutation -> utils.ResolvePartialID). When the exact id is absent, that resolver falls through to leading-prefix abbreviation, so an id that was already deleted resolves to a different issue whose id it happens to begin, and --force deletes that issue. The shape is ordinary: hash length is adaptive (3 to 8 characters) so a grown store holds short ids beside longer ones, --id makes any shape, and a hierarchical child's id always extends its parent's. On a fixture, after fx-t00003 was deleted, bd delete fx-t00003 resolved to fx-t000031; a re-run of a finished --from-file list with --force --quiet deleted two issues it never named, silently. The test drives deleteCmd in-process against a stub DoltStorage (no cgo, no Dolt server) and records every request handed to the Deleter role. It covers the single-id --force path, the preview, a deleted parent's id with an orphaned child, the --from-file batch path, and an abbreviation of one and of two live issues; each refusal must say delete needs the full id and name the ids the input matches. An over-refusal guard checks that exact ids (full, bare hash, child, batch) still delete exactly what they name. The six refusal cases fail at this commit; the guard passes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Agent-Signature: claude-code-claude-opus-5-5 on behalf of A3Ackerman * fix(delete): resolve ids exactly, never by prefix abbreviation (be-ksd) bd delete's direct route resolved each id with the abbreviation-tolerant resolver, so an id that no longer exists resolved to the surviving issue whose id it begins, and --force deleted that issue. Both of its resolution sites now use resolveAndGetIssueForMutationExact (#5393's exact sibling, until now used only by bd comment): the inline single-id path and deleteBatch, which --from-file, multiple ids and --cascade take. The resolver cannot tell a stale full id from an abbreviation. Hash length is adaptive with store size, so one store holds 3- to 8-character ids side by side and "fx-t00003" is both a valid full id and a valid abbreviation of "fx-t000031". The rule therefore has to be per command, the way #5393 made it for bd comment. Delete is exact on both preview and --force: the preview prints the next command to run ("To proceed, run: bd delete fx-t000031 --force"), so a tolerant preview hands the caller the wrong deletion to confirm. This matches the team-server route, which passes ids to issueops.Deleter unresolved, and DeleteRequest.IDs' own contract ("IDs ARE EXACT"). The partial-ID notice (#6302) did not protect this path: --quiet silences it, and a --force --quiet re-run of a finished --from-file list deleted two issues it never named. The refusal says what to do: "bd delete needs the full issue id: no issue has the id "t000", which is the start of fx-t000031". To name the matches, ResolvePartialIDExact now returns *utils.AbbreviatedIDError, which carries the input and the sorted matches, wraps ErrAbbreviatedIDNotAllowed and keeps the old error text, so bd comment's errors.Is checks and messages are unchanged. Cost: bd delete <abbreviation> is refused, naming the full ids, so the caller retypes one. Exact ids, bare full hashes, child, cross-prefix and routed ids resolve as before. The other deleteBatch callers (cleanup, wisp gc, mol burn) pass full ids read from the store, so nothing changes for them except under a race, where they now refuse instead of reaching a neighbor. Reads and other writes keep abbreviation. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Agent-Signature: claude-code-claude-opus-5-5 on behalf of A3Ackerman * docs(ids): say bd delete requires the full id, like bd comment (be-ksd) The Working with IDs section named bd comment as the one command that refuses abbreviations and said every other mutation keeps them. bd delete now requires the exact id too, so the section covers both, says why a delete reaches the wrong issue so easily (an already-deleted id is still the start of its child's id, or of a longer hash), and adds the bd delete lines to the example block. Best Practices #1 names both commands. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Agent-Signature: claude-code-claude-opus-5-5 on behalf of A3Ackerman * docs(changelog): link the bd delete exact-id entry to #7375 (be-ksd) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Agent-Signature: claude-code-claude-opus-5-5 on behalf of A3Ackerman * fix(delete): report a gone parent's id as a lost race under --if-revision (be-ksd) Review-loop iteration 1 for #7375: a maintainer fixup on top of the contributor's branch. Major (codex+claude): a guarded `bd delete --if-revision` whose target was deleted, and whose id is still the start of a surviving id (a gone parent with a live <parent>.1 child), exited 1 with the abbreviation refusal. Any other gone target gets the documented lost race (precondition_failed, exit 13), and gascity's conditional deletes switch on that code, so a benign race read as a hard failure. - reportIfRevisionTargetGone (the single-id path) also takes utils.ErrAbbreviatedIDNotAllowed as a gone target: under delete's exact resolution that id names no row either. - The refusal is a typed error, deleteAbbreviationError, that unwraps to storage.ErrNotFound beside the *utils.AbbreviatedIDError, so the --cascade caller of deleteBatch classifies it through reportIfRevisionFailure the same way. errors.New(msg) dropped every sentinel. Minor (claude), taken: the refusal leads with the not-found fact, `issue "t000" not found: bd delete needs the full issue id, and "t000" is only the start of fx-t000031`, so gascity's isBdNotFound reads an already-gone full id that begins a survivor's id as the idempotent not-found it reads for any other gone id. The CHANGELOG entry quotes the new text and the --if-revision outcome. Minor (gemini), declined: threading the source command into the refusal's wording. deleteBatch's other callers (bd cleanup, wisp gc, mol burn) pass store-minted full ids that no user retypes, and the text now leads with "issue X not found", which holds for every caller. Tests: - TestDeleteIfRevisionGoneIDThatPrefixesAnotherIssue: single id, --json, --cascade and --cascade --json each exit 13 with "precondition failed: issue no longer exists" and the precondition_failed body, never the refusal text, and the guarded write never runs. Two no-survivor rows are the plain gone id they must match. - TestReportIfRevisionTargetGone: abbreviation rows, guarded and not. - TestDeleteRefusesStaleIDThatPrefixesAnotherIssue also asserts the refusal says "not found". - TestEmbeddedIfRevisionDeletePreflightGoneParentIsPreconditionFailed, end to end on embedded Dolt: delete a parent, its child survives and `bd show <parent>` resolves to it; a guarded delete of the parent exits 13 on the single-id and --cascade paths and leaves the child. The TestEmbedded name is what puts it in a CI lane; its line in embedded-cmd-test-shards.txt is the generator's incremental --write. Mutation checks, each reverted afterwards: dropping the ErrAbbreviatedIDNotAllowed match fails the single-id cases and the abbreviation_guarded row; dropping ErrNotFound from Unwrap fails the --cascade cases; dropping "not found" from the text fails every refusal case; reverting both fixes fails both embedded legs (exit 1, the refusal text, no "precondition failed"). Validation: the focused delete and if-revision tests; the embedded pair under BEADS_TEST_EMBEDDED_DOLT=1; the scripts shard-manifest policy tests and the generator's --check; gofmt; git diff --check. The full ./cmd/bd and ./internal/utils packages (-short, BEADS_TEST_SKIP=dolt) pass but for TestRunApplyAllOK, which fails only because this worktree sets core.hooksPath=/dev/null ("mkdir /dev/null: not a directory") and passes with core.hooksPath overridden. Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: Eddie the Engineer <julianknutsen@users.noreply.github.com>
5 KiB
| title | description |
|---|---|
| Hash-based IDs | Why beads uses collision-resistant hash IDs like bd-a1b2 so agents and branches never clash |
Understanding beads' collision-resistant ID system.
The Problem
Traditional sequential IDs (#1, #2, #3) break when:
- Multiple agents create issues simultaneously
- Different branches have independent numbering
- Forks diverge and later merge
flowchart TD
subgraph seq["Sequential IDs — collision on merge"]
a1["agent A creates #7"] --> m1["merge: two different #7s ✗"]
b1["agent B creates #7"] --> m1
end
subgraph hash["Hash IDs — no coordination needed"]
a2["agent A creates bd-a1b2"] --> m2["merge: both IDs survive ✓"]
b2["agent B creates bd-f14c"] --> m2
end
The Solution
Beads uses hash-based IDs:
bd-a1b2c3 # Short hash
bd-f14c # Even shorter
bd-a3f8e9.1 # Hierarchical (child of bd-a3f8e9)
Properties:
- Globally unique (content-based hash)
- No coordination needed between creators
- Merge-friendly across branches
- Predictable length (configurable)
How Hashes Work
IDs are generated from:
- Issue title
- Creation timestamp
- Random salt
# Create issue - ID assigned automatically
bd create "Fix authentication bug"
# Returns: bd-7x2f
# The ID is deterministic for same content+timestamp
Hierarchical IDs
For epics and subtasks:
# Parent epic
bd create "Auth System" -t epic
# Returns: bd-a3f8e9
# Children auto-increment
bd create "Design UI" --parent bd-a3f8e9 # bd-a3f8e9.1
bd create "Backend" --parent bd-a3f8e9 # bd-a3f8e9.2
bd create "Tests" --parent bd-a3f8e9 # bd-a3f8e9.3
Benefits:
- Clear parent-child relationship
- No namespace collision (parent hash is unique)
- Up to 3 levels of nesting
ID Configuration
Configure ID prefix and length:
# Set prefix (default: bd)
bd config set id.prefix myproject
# Set hash length (default: 4)
bd config set id.hash_length 6
# New issues use new format
bd create "Test"
# Returns: myproject-a1b2c3
Collision Handling
While rare, collisions are handled automatically:
- On import, if hash collision detected
- Beads appends disambiguator
- Both issues preserved
# Check for collisions
bd info --schema --json | jq '.collision_count'
Working with IDs
# Partial ID matching
bd show a1b2 # Finds bd-a1b2...
bd show auth # Fuzzy match by title
# Full ID required for ambiguous cases
bd show bd-a1b2c3d4
# List with full IDs
bd list --full-ids
bd comment and bd delete require the full id
Every command above resolves an abbreviation the same way, with two deliberate
exceptions: bd comment <id> "text" (and its bd comments add twin) and
bd delete accept only a full, exact id, never an abbreviation. This is a
policy trade for an agent fleet, not an oversight: an abbreviation that happens
to be a leading-prefix match for the wrong issue would land the write there
instead of erroring. A comment write has no confirmation step to catch it, and
a deletion cannot be undone.
For bd delete the wrong match is easy to reach by accident. The id of an
issue that is already gone is still the start of other ids — its child's
(bd-a3f8e9.1 after bd-a3f8e9 is deleted), or a longer hash that happens to
begin with it — so retrying a delete or re-running a --from-file list would
otherwise reach an issue nobody named. The refusal says delete needs the full
id and names the ids the input matches.
Reads and every other mutation (show, close, update, …) keep accepting
abbreviations as documented above.
bd show a1b2 # OK — abbreviation resolves for reads
bd close a1b2 # OK — abbreviation resolves for other writes
bd comment a1b2 "text" # refused — comment writes require the full id
bd comment bd-a1b2c3d4 "text" # OK — use the full id from `bd show`
bd delete a1b2 # refused — deletes require the full id
bd delete bd-a1b2c3d4 # OK — previews the deletion; add --force to delete
A reserved word (list, add, rm, delete) as bd comment's id
positional is refused the same way, for a related reason: bd comment list "text" almost always means the caller confused the singular shorthand with the
plural bd comments list/bd comments add <id> "text", not that an issue is
literally named list.
Migration from Sequential IDs
If migrating from a system with sequential IDs:
# Bootstrap from a JSONL export (preserves original IDs in metadata)
bd init --from-jsonl old-issues.jsonl
# View original ID
bd show bd-new --json | jq '.original_id'
Best Practices
- Use short references -
bd-a1b2is usually unique enough, except onbd commentwrites andbd delete, which require the full id (see Working with IDs above) - Use
--jsonfor scripts - Parse full ID programmatically - Reference by hash in commits -
Fixed bd-a1b2in commit messages - Let hierarchies form naturally - Create epics, add children as needed