update --spec validates against the current checkout only, so specs on other branches cannot be referenced and read as missing
- Dominant language
- TypeScript
- Stars
- 79
- Forks
- 9
- Avg merge
- 1d 14h
- Merged PRs (30d)
- 42
Description
## Summary
`tbd update --spec ` validates the path against the working tree of the current checkout only, so a spec that exists on another branch or in another worktree cannot be referenced, and beads whose spec lives on an unmerged branch read as "missing" in every triage until the merge.
## What happened
```
$ tbd update p-aaaa --spec docs/project/specs/archive/plan-….md
Error: File not found: docs/project/specs/archive/plan-….md
```
The file existed on a branch checked out in a separate worktree. The workaround was to `cd` into that worktree and run the same command, which works only because bead storage is shared through the git common directory; nothing documents that this is the way to do it.
Separately, 12 of 137 open epics named specs that exist only on unmerged feature branches. Every spec-based selector and the update-specs-status triage treat those as missing files, which the shortcut says to check with `git log --diff-filter=D` by hand.
## Suggested change
- Validate against `git ls-tree` of any ref (`--spec-ref `), or allow `--no-verify` with a warning.
- Let a bead record where its spec currently lives (a ref alongside the path), and have `tbd list --specs` / doctor show "pending on branch X" rather than "missing".
Environment: tbd 0.8.1, Node v24.19.0, macOS 26 (Darwin 25.5), Linear integration enabled. Repository scale when observed: 7,156 beads, 137 open epics, 171 tracker links, about 110 plan specs in `active/`.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the `tbd update --spec` path, then trace the `tbd list --specs` and doctor checks that report specs as missing. Review how `git ls-tree` could inspect another ref and compare the behavior for specs on unmerged branches; done means those specs are resolved or clearly reported as pending rather than missing.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- git, typescript
- Domain
- cli, devtools
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100