jlevy / jlevy/tbd

doctor misses dangling spec_path, epics without a spec_path, and the same spec filename in two lifecycle folders

Open
#275 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 doctor` does not detect three kinds of spec drift, each of which corrupts the *next* reconciliation rather than the current one.

## What happened

- **Dangling `spec_path`:** at one earlier pass, 279 of 941 beads carrying a `spec_path` named a file that had moved out from under them. 213 were repairable mechanically because exactly one file of that name existed elsewhere under the specs tree. Doctor reported the repository healthy throughout.
- **Epics with no `spec_path`:** 30 of 137 open epics. Such an epic is invisible to `tbd list --spec` and to every spec-based selector, so it silently drops out of any spec-driven review.
- **Same spec filename in two lifecycle folders:** a plan sat in both `active/` and `done/` for weeks; beads pointed at both. Nothing flags this.

## Suggested change

Three doctor checks, and `--fix` for the first: repoint a bead when exactly one file with that basename exists elsewhere under the specs tree, and list the rest for judgement.

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 at the `tbd doctor` command and trace its existing repository checks, then inspect how beads and the specs tree are represented. Add checks for dangling `spec_path` values, open epics without `spec_path`, and duplicate spec basenames across lifecycle folders; `--fix` should only repoint an unambiguous dangling reference and report the rest for review.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
cli
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.