jlevy / jlevy/tbd

update --spec validates against the current checkout only, so specs on other branches cannot be referenced and read as missing

Open
#273 0 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.