get-tbd 0.1.29 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -1
- package/dist/bin.mjs +3241 -2326
- package/dist/bin.mjs.map +1 -1
- package/dist/cli.mjs +1503 -791
- package/dist/cli.mjs.map +1 -1
- package/dist/{config-B38rbI9u.mjs → config-BJz1m9eN.mjs} +183 -39
- package/dist/config-BJz1m9eN.mjs.map +1 -0
- package/dist/{config-C0ITTrtc.mjs → config-DlCUMyCG.mjs} +1 -1
- package/dist/docs/README.md +5 -1
- package/dist/docs/SKILL.md +0 -1
- package/dist/docs/guidelines/backward-compatibility-rules.md +4 -0
- package/dist/docs/guidelines/bun-monorepo-patterns.md +20 -4
- package/dist/docs/guidelines/cli-agent-skill-patterns.md +354 -37
- package/dist/docs/guidelines/commit-conventions.md +4 -0
- package/dist/docs/guidelines/common-doc-guidelines.md +234 -0
- package/dist/docs/guidelines/convex-limits-best-practices.md +4 -0
- package/dist/docs/guidelines/convex-rules.md +4 -0
- package/dist/docs/guidelines/electron-app-development-patterns.md +4 -0
- package/dist/docs/guidelines/error-handling-rules.md +4 -0
- package/dist/docs/guidelines/general-coding-rules.md +4 -0
- package/dist/docs/guidelines/general-comment-rules.md +4 -0
- package/dist/docs/guidelines/general-eng-assistant-rules.md +4 -0
- package/dist/docs/guidelines/general-tdd-guidelines.md +4 -0
- package/dist/docs/guidelines/general-testing-rules.md +4 -0
- package/dist/docs/guidelines/golden-testing-guidelines.md +4 -0
- package/dist/docs/guidelines/pnpm-monorepo-patterns.md +27 -6
- package/dist/docs/guidelines/python-cli-patterns.md +4 -0
- package/dist/docs/guidelines/python-modern-guidelines.md +30 -0
- package/dist/docs/guidelines/python-rules.md +4 -0
- package/dist/docs/guidelines/release-notes-guidelines.md +4 -0
- package/dist/docs/guidelines/supply-chain-hardening.md +11 -7
- package/dist/docs/guidelines/tbd-sync-troubleshooting.md +10 -4
- package/dist/docs/guidelines/typescript-cli-tool-rules.md +27 -24
- package/dist/docs/guidelines/typescript-code-coverage.md +11 -7
- package/dist/docs/guidelines/typescript-rules.md +10 -6
- package/dist/docs/guidelines/typescript-sorting-patterns.md +4 -0
- package/dist/docs/guidelines/typescript-yaml-handling-rules.md +7 -3
- package/dist/docs/install/ensure-gh-cli.sh +59 -24
- package/dist/docs/shortcuts/standard/agent-handoff.md +4 -0
- package/dist/docs/shortcuts/standard/checkout-third-party-repo.md +4 -0
- package/dist/docs/shortcuts/standard/code-cleanup-all.md +4 -0
- package/dist/docs/shortcuts/standard/code-cleanup-docstrings.md +4 -0
- package/dist/docs/shortcuts/standard/code-cleanup-tests.md +4 -0
- package/dist/docs/shortcuts/standard/code-review-and-commit.md +4 -0
- package/dist/docs/shortcuts/standard/coding-spike.md +4 -0
- package/dist/docs/shortcuts/standard/create-or-update-pr-simple.md +4 -0
- package/dist/docs/shortcuts/standard/create-or-update-pr-with-validation-plan.md +4 -0
- package/dist/docs/shortcuts/standard/implement-beads.md +4 -0
- package/dist/docs/shortcuts/standard/merge-upstream.md +4 -0
- package/dist/docs/shortcuts/standard/new-architecture-doc.md +4 -0
- package/dist/docs/shortcuts/standard/new-guideline.md +4 -0
- package/dist/docs/shortcuts/standard/new-plan-spec.md +4 -0
- package/dist/docs/shortcuts/standard/new-qa-playbook.md +4 -0
- package/dist/docs/shortcuts/standard/new-research-brief.md +4 -0
- package/dist/docs/shortcuts/standard/new-shortcut.md +4 -0
- package/dist/docs/shortcuts/standard/new-validation-plan.md +4 -0
- package/dist/docs/shortcuts/standard/plan-implementation-with-beads.md +4 -0
- package/dist/docs/shortcuts/standard/precommit-process.md +4 -0
- package/dist/docs/shortcuts/standard/review-code-python.md +4 -0
- package/dist/docs/shortcuts/standard/review-code-typescript.md +4 -0
- package/dist/docs/shortcuts/standard/review-code.md +4 -0
- package/dist/docs/shortcuts/standard/review-github-pr.md +4 -0
- package/dist/docs/shortcuts/standard/revise-all-architecture-docs.md +4 -0
- package/dist/docs/shortcuts/standard/revise-architecture-doc.md +4 -0
- package/dist/docs/shortcuts/standard/setup-github-cli.md +4 -0
- package/dist/docs/shortcuts/standard/sync-failure-recovery.md +4 -0
- package/dist/docs/shortcuts/standard/update-specs-status.md +4 -0
- package/dist/docs/shortcuts/standard/welcome-user.md +4 -0
- package/dist/docs/tbd-closing.md +4 -0
- package/dist/docs/tbd-design.md +109 -68
- package/dist/docs/tbd-docs.md +20 -13
- package/dist/docs/tbd-prime.md +4 -0
- package/dist/docs/templates/architecture-doc.md +4 -0
- package/dist/docs/templates/plan-spec.md +4 -0
- package/dist/docs/templates/qa-playbook.md +4 -0
- package/dist/docs/templates/research-brief.md +4 -0
- package/dist/{id-mapping-Ctfl_nc1.mjs → id-mapping-CFoPVinz.mjs} +1 -1
- package/dist/{id-mapping-CqrrLgeX.mjs → id-mapping-CtfTfGIh.mjs} +146 -122
- package/dist/id-mapping-CtfTfGIh.mjs.map +1 -0
- package/dist/index.d.mts +53 -1
- package/dist/index.mjs +3 -3
- package/dist/{schemas-C8mOQykE.mjs → schemas-f0EcuAVu.mjs} +40 -3
- package/dist/schemas-f0EcuAVu.mjs.map +1 -0
- package/dist/{src-CJyVkC3V.mjs → src-rIE4xSVs.mjs} +3 -3
- package/dist/src-rIE4xSVs.mjs.map +1 -0
- package/dist/tbd +3241 -2326
- package/package.json +1 -1
- package/dist/config-B38rbI9u.mjs.map +0 -1
- package/dist/docs/guidelines/general-style-rules.md +0 -38
- package/dist/docs/guidelines/writing-style-guidelines.md +0 -42
- package/dist/id-mapping-CqrrLgeX.mjs.map +0 -1
- package/dist/schemas-C8mOQykE.mjs.map +0 -1
- package/dist/src-CJyVkC3V.mjs.map +0 -1
package/dist/docs/tbd-design.md
CHANGED
|
@@ -714,14 +714,17 @@ current node’s prefix.
|
|
|
714
714
|
|
|
715
715
|
### 2.2 Directory Structure
|
|
716
716
|
|
|
717
|
-
tbd uses
|
|
717
|
+
tbd uses four directory locations:
|
|
718
718
|
|
|
719
719
|
- **`.tbd/`** on main branch: Configuration (tracked) + installed docs (gitignored)
|
|
720
720
|
|
|
721
|
-
-
|
|
722
|
-
|
|
721
|
+
- **`$GIT_COMMON_DIR/tbd/`** local repo-scoped machinery shared by the main checkout and
|
|
722
|
+
all linked worktrees
|
|
723
723
|
|
|
724
|
-
-
|
|
724
|
+
- **`$GIT_COMMON_DIR/tbd/data-sync-worktree/`** hidden worktree: Checkout of `tbd-sync`
|
|
725
|
+
branch for search and writes
|
|
726
|
+
|
|
727
|
+
- **`.tbd/data-sync/`** on `tbd-sync` branch: Synced entities and attic payload
|
|
725
728
|
|
|
726
729
|
#### On Main Branch (all working branches)
|
|
727
730
|
|
|
@@ -750,14 +753,24 @@ tbd uses three directory locations:
|
|
|
750
753
|
│ │ └── standard/ # Workflow shortcuts (new-plan-spec.md, etc.)
|
|
751
754
|
│ ├── guidelines/ # Coding rules and best practices
|
|
752
755
|
│ └── templates/ # Document templates
|
|
753
|
-
└──
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
756
|
+
└── backups/ # Legacy local backups
|
|
757
|
+
```
|
|
758
|
+
|
|
759
|
+
#### In `$GIT_COMMON_DIR/tbd/` (local, shared by linked worktrees)
|
|
760
|
+
|
|
761
|
+
```
|
|
762
|
+
$GIT_COMMON_DIR/tbd/
|
|
763
|
+
├── layout.yml # Local layout metadata; uses the same f04 format ID
|
|
764
|
+
├── locks/
|
|
765
|
+
│ └── data-sync.lock/ # mkdir-based repo-scoped lock
|
|
766
|
+
├── backups/ # Repair and migration backups
|
|
767
|
+
└── data-sync-worktree/ # Checkout of tbd-sync branch
|
|
768
|
+
└── .tbd/
|
|
769
|
+
└── data-sync/
|
|
770
|
+
├── issues/
|
|
771
|
+
│ ├── is-a1b2c3.md
|
|
772
|
+
│ └── is-f14c3d.md
|
|
773
|
+
└── ...
|
|
761
774
|
```
|
|
762
775
|
|
|
763
776
|
#### On `tbd-sync` Branch
|
|
@@ -796,9 +809,11 @@ tbd uses three directory locations:
|
|
|
796
809
|
|
|
797
810
|
### 2.3 Hidden Worktree Model
|
|
798
811
|
|
|
799
|
-
tbd maintains
|
|
800
|
-
the `tbd-sync` branch.
|
|
801
|
-
|
|
812
|
+
tbd maintains one **hidden git worktree** at `$GIT_COMMON_DIR/tbd/data-sync-worktree/`
|
|
813
|
+
that checks out the `tbd-sync` branch.
|
|
814
|
+
The Git common-dir location is shared by the main checkout and linked worktrees, so
|
|
815
|
+
Codex or other agents can run from any checkout without creating competing `tbd-sync`
|
|
816
|
+
worktrees. This provides:
|
|
802
817
|
|
|
803
818
|
1. **Fast search**: ripgrep can search all issues without git plumbing commands
|
|
804
819
|
|
|
@@ -808,16 +823,19 @@ This provides:
|
|
|
808
823
|
|
|
809
824
|
4. **Automatic updates**: Updated on `tbd sync` operations
|
|
810
825
|
|
|
826
|
+
5. **Linked-worktree safety**: One shared sync worktree owns `tbd-sync`, and a
|
|
827
|
+
repo-scoped mkdir lock serializes mutations
|
|
828
|
+
|
|
811
829
|
#### Worktree Setup
|
|
812
830
|
|
|
813
831
|
Created automatically by `tbd init` or first `tbd sync`:
|
|
814
832
|
|
|
815
833
|
```bash
|
|
816
834
|
# Create hidden worktree (done by tbd internally)
|
|
817
|
-
git worktree add
|
|
835
|
+
git worktree add "$(git rev-parse --path-format=absolute --git-common-dir)/tbd/data-sync-worktree" tbd-sync
|
|
818
836
|
|
|
819
837
|
# Or if tbd-sync doesn't exist yet
|
|
820
|
-
git worktree add
|
|
838
|
+
git worktree add --orphan -b tbd-sync "$(git rev-parse --path-format=absolute --git-common-dir)/tbd/data-sync-worktree"
|
|
821
839
|
```
|
|
822
840
|
|
|
823
841
|
**Key properties:**
|
|
@@ -828,9 +846,10 @@ git worktree add .tbd/data-sync-worktree --orphan tbd-sync
|
|
|
828
846
|
If the worktree becomes detached (from old tbd versions), it’s automatically repaired
|
|
829
847
|
before commits.
|
|
830
848
|
|
|
831
|
-
- **Hidden location**: Inside
|
|
849
|
+
- **Hidden location**: Inside Git’s common directory, not inside any single checkout
|
|
832
850
|
|
|
833
|
-
- **Safe updates**: `tbd sync`
|
|
851
|
+
- **Safe updates**: `tbd sync` acquires `$GIT_COMMON_DIR/tbd/locks/data-sync.lock/`
|
|
852
|
+
before mutating the worktree, committing, fetching, merging, or pushing
|
|
834
853
|
|
|
835
854
|
#### Worktree Gitignore
|
|
836
855
|
|
|
@@ -860,9 +879,12 @@ backups/
|
|
|
860
879
|
> issues could be stored directly on main without a worktree.
|
|
861
880
|
> In normal operation, `data-sync/` only exists inside the worktree checkout.
|
|
862
881
|
>
|
|
863
|
-
> **Note:**
|
|
864
|
-
>
|
|
865
|
-
>
|
|
882
|
+
> **Note:** Production repair and migration backups under the shared common-dir layout
|
|
883
|
+
> live at `$GIT_COMMON_DIR/tbd/backups/`, alongside `layout.yml` and the shared
|
|
884
|
+
> `data-sync-worktree/`. The legacy `.tbd/backups/` directory on the main branch is
|
|
885
|
+
> gitignored and reserved for historical local backups; current `tbd doctor --fix` and
|
|
886
|
+
> migration paths write to the common-dir location.
|
|
887
|
+
> Both differ from `.tbd/data-sync/attic/` on the sync branch which stores merge
|
|
866
888
|
> conflict losers.
|
|
867
889
|
>
|
|
868
890
|
> **Note:** `workspaces/` must not be gitignored — it stores outbox data that must be
|
|
@@ -892,14 +914,16 @@ that directory.
|
|
|
892
914
|
#### Accessing Issues via Worktree
|
|
893
915
|
|
|
894
916
|
```bash
|
|
917
|
+
WORKTREE="$(git rev-parse --path-format=absolute --git-common-dir)/tbd/data-sync-worktree"
|
|
918
|
+
|
|
895
919
|
# Files are directly accessible
|
|
896
|
-
cat
|
|
920
|
+
cat "$WORKTREE/.tbd/data-sync/issues/is-a1b2c3.md"
|
|
897
921
|
|
|
898
922
|
# ripgrep search across all issues
|
|
899
|
-
rg "authentication"
|
|
923
|
+
rg "authentication" "$WORKTREE/.tbd/data-sync/issues/"
|
|
900
924
|
|
|
901
925
|
# List all issues
|
|
902
|
-
ls
|
|
926
|
+
ls "$WORKTREE/.tbd/data-sync/issues/"
|
|
903
927
|
```
|
|
904
928
|
|
|
905
929
|
#### Worktree Lifecycle
|
|
@@ -907,13 +931,13 @@ ls .tbd/data-sync-worktree/.tbd/data-sync/issues/
|
|
|
907
931
|
| Operation | Worktree Action |
|
|
908
932
|
| --- | --- |
|
|
909
933
|
| `tbd init` | Create worktree if tbd-sync exists |
|
|
910
|
-
| `tbd sync --pull` |
|
|
934
|
+
| `tbd sync --pull` | Fetch and merge through the shared worktree |
|
|
911
935
|
| `tbd sync --push` | Update worktree after successful push |
|
|
912
936
|
| `tbd doctor` | Verify worktree health, repair if needed |
|
|
913
937
|
| Repo clone | Worktree created on first tbd command |
|
|
914
938
|
|
|
915
|
-
**Invariant:** The hidden worktree at
|
|
916
|
-
current state of the `tbd-sync` branch after sync operations.
|
|
939
|
+
**Invariant:** The hidden worktree at `$GIT_COMMON_DIR/tbd/data-sync-worktree/` always
|
|
940
|
+
reflects the current state of the `tbd-sync` branch after sync operations.
|
|
917
941
|
|
|
918
942
|
#### Worktree Initialization Decision Tree
|
|
919
943
|
|
|
@@ -927,16 +951,16 @@ START: Any tbd command
|
|
|
927
951
|
│ ├─ NO → Run `tbd init` first (error: "Not a tbd repository")
|
|
928
952
|
│ └─ YES ↓
|
|
929
953
|
│
|
|
930
|
-
├─ Does
|
|
954
|
+
├─ Does $GIT_COMMON_DIR/tbd/data-sync-worktree/ exist and contain valid checkout?
|
|
931
955
|
│ ├─ YES → Worktree ready, proceed with command
|
|
932
956
|
│ └─ NO ↓
|
|
933
957
|
│
|
|
934
958
|
├─ Does tbd-sync branch exist (local or remote)?
|
|
935
|
-
│ ├─ YES (local) → git worktree add
|
|
959
|
+
│ ├─ YES (local) → git worktree add $GIT_COMMON_DIR/tbd/data-sync-worktree tbd-sync
|
|
936
960
|
│ ├─ YES (remote only) → git fetch origin tbd-sync
|
|
937
|
-
│ │ git worktree add
|
|
961
|
+
│ │ git worktree add $GIT_COMMON_DIR/tbd/data-sync-worktree tbd-sync
|
|
938
962
|
│ └─ NO → This is a fresh tbd init, create orphan worktree:
|
|
939
|
-
│ git worktree add
|
|
963
|
+
│ git worktree add --orphan -b tbd-sync $GIT_COMMON_DIR/tbd/data-sync-worktree
|
|
940
964
|
│ (Initialize .tbd/data-sync/ structure in worktree)
|
|
941
965
|
│
|
|
942
966
|
└─ Worktree ready, proceed with command
|
|
@@ -958,9 +982,9 @@ The worktree can be in one of four states, detected by `checkWorktreeHealth()`:
|
|
|
958
982
|
| State | Description | Detection | Recovery |
|
|
959
983
|
| --- | --- | --- | --- |
|
|
960
984
|
| `valid` | Healthy, ready to use | Directory exists, `.git` file valid, not prunable | None needed |
|
|
961
|
-
| `missing` | Directory doesn’t exist | `!exists(
|
|
985
|
+
| `missing` | Directory doesn’t exist | `!exists($GIT_COMMON_DIR/tbd/data-sync-worktree/)` | Create from local or remote branch |
|
|
962
986
|
| `prunable` | Directory deleted but git still tracks it | `git worktree list --porcelain` shows prunable | `git worktree prune`, then recreate |
|
|
963
|
-
| `corrupted` | Directory exists but invalid | Missing `.git` file
|
|
987
|
+
| `corrupted` | Directory exists but invalid | Missing `.git` file, invalid gitdir pointer, or wrong branch | **Backup to $GIT_COMMON_DIR/tbd/backups/**, then recreate |
|
|
964
988
|
|
|
965
989
|
**Safety: Backup before removal**
|
|
966
990
|
|
|
@@ -969,11 +993,12 @@ Before removing, ALWAYS back it up to prevent data loss:
|
|
|
969
993
|
|
|
970
994
|
```bash
|
|
971
995
|
# Backup corrupted worktree before removal
|
|
972
|
-
|
|
996
|
+
COMMON="$(git rev-parse --path-format=absolute --git-common-dir)"
|
|
997
|
+
mv "$COMMON/tbd/data-sync-worktree" "$COMMON/tbd/backups/corrupted-worktree-backup-$(date +%Y%m%d-%H%M%S)"
|
|
973
998
|
```
|
|
974
999
|
|
|
975
|
-
The backup is placed in
|
|
976
|
-
|
|
1000
|
+
The backup is placed in `$GIT_COMMON_DIR/tbd/backups/`, preserving the data for manual
|
|
1001
|
+
recovery while not polluting the repository.
|
|
977
1002
|
|
|
978
1003
|
**Detection algorithm:**
|
|
979
1004
|
|
|
@@ -983,7 +1008,7 @@ async function checkWorktreeHealth(baseDir: string): Promise<{
|
|
|
983
1008
|
status: 'valid' | 'missing' | 'prunable' | 'corrupted';
|
|
984
1009
|
details?: string;
|
|
985
1010
|
}> {
|
|
986
|
-
const worktreePath =
|
|
1011
|
+
const { sharedWorktreePath: worktreePath } = await resolveSharedTbdPaths(baseDir);
|
|
987
1012
|
|
|
988
1013
|
// Check directory exists
|
|
989
1014
|
if (!await pathExists(worktreePath)) {
|
|
@@ -1012,8 +1037,8 @@ async function checkWorktreeHealth(baseDir: string): Promise<{
|
|
|
1012
1037
|
|
|
1013
1038
|
| Term | Path | Purpose |
|
|
1014
1039
|
| --- | --- | --- |
|
|
1015
|
-
| **Worktree path** |
|
|
1016
|
-
| **Direct path** | `.tbd/data-sync/` | **
|
|
1040
|
+
| **Worktree path** | `$GIT_COMMON_DIR/tbd/data-sync-worktree/.tbd/data-sync/` | **Production path** — inside hidden worktree checkout |
|
|
1041
|
+
| **Direct path** | `.tbd/data-sync/` | **Legacy fallback path** — gitignored on main, should NEVER contain data in production |
|
|
1017
1042
|
|
|
1018
1043
|
**Invariant:** In production, the worktree path is the ONLY correct path for issue data.
|
|
1019
1044
|
The direct path exists ONLY for test fixtures that don’t use git.
|
|
@@ -1025,7 +1050,7 @@ async function resolveDataSyncDir(
|
|
|
1025
1050
|
baseDir: string,
|
|
1026
1051
|
options?: { allowFallback?: boolean; repair?: boolean }
|
|
1027
1052
|
): Promise<string> {
|
|
1028
|
-
const worktreePath =
|
|
1053
|
+
const worktreePath = (await resolveSharedTbdPaths(baseDir)).sharedDataSyncDir;
|
|
1029
1054
|
|
|
1030
1055
|
// Check if worktree exists
|
|
1031
1056
|
if (await pathExists(worktreePath)) {
|
|
@@ -1047,7 +1072,7 @@ async function resolveDataSyncDir(
|
|
|
1047
1072
|
|
|
1048
1073
|
// Fail with clear error — NEVER silently fall back in production
|
|
1049
1074
|
throw new WorktreeMissingError(
|
|
1050
|
-
'
|
|
1075
|
+
'Shared worktree not found under $GIT_COMMON_DIR/tbd/data-sync-worktree/. ' +
|
|
1051
1076
|
'Run `tbd doctor --fix` to repair.'
|
|
1052
1077
|
);
|
|
1053
1078
|
}
|
|
@@ -1632,6 +1657,11 @@ const ConfigSchema = z.object({
|
|
|
1632
1657
|
> This ensures older versions fail fast rather than silently corrupting config.
|
|
1633
1658
|
> See `tbd-format.ts` for format version history and `config.ts` for the compatibility
|
|
1634
1659
|
> check via `isCompatibleFormat()`.
|
|
1660
|
+
>
|
|
1661
|
+
> For the rules that govern adding a new format (idempotent migration, write order,
|
|
1662
|
+
> signing-agnostic commits, doctor recovery contract), see the project-local
|
|
1663
|
+
> [docs/tbd-format-versioning.md](../../../docs/tbd-format-versioning.md) contributor
|
|
1664
|
+
> guide.
|
|
1635
1665
|
|
|
1636
1666
|
#### 2.7.5 MetaSchema
|
|
1637
1667
|
|
|
@@ -2011,9 +2041,10 @@ main branch: tbd-sync branch:
|
|
|
2011
2041
|
```
|
|
2012
2042
|
.tbd/state.yml # Per-node sync state
|
|
2013
2043
|
.tbd/docs/ # Installed documentation (regenerated on setup)
|
|
2014
|
-
.tbd/backups/ #
|
|
2015
|
-
.tbd/data-sync-worktree/ #
|
|
2044
|
+
.tbd/backups/ # Legacy local backups
|
|
2045
|
+
.tbd/data-sync-worktree/ # Legacy per-checkout worktree path
|
|
2016
2046
|
.tbd/data-sync/ # Reserved for potential future "simple mode"
|
|
2047
|
+
$GIT_COMMON_DIR/tbd/ # Shared local sync worktree, locks, backups
|
|
2017
2048
|
```
|
|
2018
2049
|
|
|
2019
2050
|
#### Files Tracked on tbd-sync Branch
|
|
@@ -2103,20 +2134,21 @@ High-level sync flow:
|
|
|
2103
2134
|
|
|
2104
2135
|
```
|
|
2105
2136
|
SYNC(options):
|
|
2106
|
-
0. PREREQUISITE:
|
|
2107
|
-
|
|
2108
|
-
- If
|
|
2109
|
-
|
|
2110
|
-
2.
|
|
2111
|
-
3.
|
|
2112
|
-
4.
|
|
2113
|
-
5.
|
|
2114
|
-
6.
|
|
2137
|
+
0. PREREQUISITE: Acquire $GIT_COMMON_DIR/tbd/locks/data-sync.lock
|
|
2138
|
+
1. Verify shared worktree health (see §2.3.4)
|
|
2139
|
+
- If missing/prunable: repair shared worktree
|
|
2140
|
+
- If corrupted: throw WorktreeCorruptedError and route to doctor --fix
|
|
2141
|
+
2. Resolve data path via resolveDataSyncDir() — uses worktree path
|
|
2142
|
+
3. Fetch remote sync branch
|
|
2143
|
+
4. Update worktree to remote state (preserving local uncommitted changes)
|
|
2144
|
+
5. Commit worktree changes to sync branch
|
|
2145
|
+
6. Push to remote
|
|
2146
|
+
7. If push rejected (non-fast-forward): retry with merge (see 3.3.2)
|
|
2115
2147
|
```
|
|
2116
2148
|
|
|
2117
2149
|
**Critical Invariant:** All operations in steps 1-6 MUST use the resolved `dataSyncDir`
|
|
2118
2150
|
path consistently. Never read from or write to `.tbd/data-sync/` directly — always go
|
|
2119
|
-
through the worktree at
|
|
2151
|
+
through the shared worktree at `$GIT_COMMON_DIR/tbd/data-sync-worktree/.tbd/data-sync/`.
|
|
2120
2152
|
|
|
2121
2153
|
**Why most syncs are trivial (no merge needed):**
|
|
2122
2154
|
|
|
@@ -3213,7 +3245,7 @@ Integrations:
|
|
|
3213
3245
|
✓ Claude Code hooks installed (./.claude/settings.json)
|
|
3214
3246
|
✗ Codex AGENTS.md not installed
|
|
3215
3247
|
|
|
3216
|
-
Worktree:
|
|
3248
|
+
Worktree: /path/to/repo/.git/tbd/data-sync-worktree (healthy)
|
|
3217
3249
|
```
|
|
3218
3250
|
|
|
3219
3251
|
**Output (--json) when initialized:**
|
|
@@ -3225,7 +3257,7 @@ Worktree: .tbd/data-sync-worktree/ (healthy)
|
|
|
3225
3257
|
"sync_branch": "tbd-sync",
|
|
3226
3258
|
"remote": "origin",
|
|
3227
3259
|
"display_prefix": "bd",
|
|
3228
|
-
"worktree_path": "
|
|
3260
|
+
"worktree_path": "/path/to/repo/.git/tbd/data-sync-worktree",
|
|
3229
3261
|
"worktree_healthy": true,
|
|
3230
3262
|
"last_sync": "2025-01-10T10:00:00Z",
|
|
3231
3263
|
"last_synced_commit": "abc123def456",
|
|
@@ -3371,24 +3403,29 @@ Run `tbd doctor --fix` to auto-fix 2 issue(s)
|
|
|
3371
3403
|
The `--fix` flag performs repairs in this order:
|
|
3372
3404
|
|
|
3373
3405
|
1. If worktree corrupted:
|
|
3374
|
-
- **Backup to
|
|
3375
|
-
|
|
3406
|
+
- **Backup to
|
|
3407
|
+
`$GIT_COMMON_DIR/tbd/backups/corrupted-worktree-backup-YYYYMMDD-HHMMSS/`**
|
|
3408
|
+
(prevents data loss)
|
|
3376
3409
|
- Remove the corrupted worktree directory
|
|
3377
3410
|
2. If worktree prunable: `git worktree prune`
|
|
3378
3411
|
3. If worktree missing (or was just removed):
|
|
3379
|
-
- If local tbd-sync exists:
|
|
3412
|
+
- If local tbd-sync exists:
|
|
3413
|
+
`git worktree add $GIT_COMMON_DIR/tbd/data-sync-worktree tbd-sync`
|
|
3380
3414
|
- Else if remote exists: `git fetch && git worktree add ... tbd-sync`
|
|
3381
3415
|
- Else: `git worktree add --orphan tbd-sync ...`
|
|
3382
3416
|
4. If data in wrong location (`.tbd/data-sync/`):
|
|
3383
|
-
- Backup to
|
|
3417
|
+
- Backup to `$GIT_COMMON_DIR/tbd/backups/tbd-data-sync-backup-YYYYMMDD-HHMMSS/`
|
|
3384
3418
|
- Copy to worktree
|
|
3385
3419
|
- Commit in worktree
|
|
3386
3420
|
5. Rebuild ID mappings if corrupted
|
|
3387
3421
|
6. Remove orphaned dependency references
|
|
3388
3422
|
|
|
3389
|
-
> **Note:**
|
|
3390
|
-
>
|
|
3391
|
-
>
|
|
3423
|
+
> **Note:** Migration and repair backups are stored under `$GIT_COMMON_DIR/tbd/backups/`
|
|
3424
|
+
> (alongside the shared sync worktree, outside the working tree and never committed).
|
|
3425
|
+
> Older clients may still have data in `.tbd/backups/`, which is kept gitignored for
|
|
3426
|
+
> legacy compatibility but is no longer the active write location.
|
|
3427
|
+
> Users can manually inspect backups in either location to recover any data that wasn’t
|
|
3428
|
+
> committed before the worktree became corrupted.
|
|
3392
3429
|
|
|
3393
3430
|
#### Compact (Future)
|
|
3394
3431
|
|
|
@@ -4938,7 +4975,7 @@ checkout.
|
|
|
4938
4975
|
|
|
4939
4976
|
- Con: Pollutes user’s working directory, shows in `git status`
|
|
4940
4977
|
|
|
4941
|
-
3. **Hidden worktree**: Separate checkout at
|
|
4978
|
+
3. **Hidden worktree**: Separate checkout at `$GIT_COMMON_DIR/tbd/data-sync-worktree/`
|
|
4942
4979
|
|
|
4943
4980
|
- Pro: Files accessible for search, isolated from user’s work
|
|
4944
4981
|
|
|
@@ -4948,15 +4985,15 @@ checkout.
|
|
|
4948
4985
|
|
|
4949
4986
|
- **Search integration**: ripgrep/grep work directly on issue files
|
|
4950
4987
|
|
|
4951
|
-
- **User isolation**: Hidden in
|
|
4988
|
+
- **User isolation**: Hidden in Git’s common directory, doesn’t pollute any checkout
|
|
4952
4989
|
|
|
4953
4990
|
- **Git-native**: Uses standard `git worktree` mechanics
|
|
4954
4991
|
|
|
4955
|
-
- **Clean status**:
|
|
4992
|
+
- **Clean status**: Lives under `.git`, doesn’t appear in user’s `git status`
|
|
4956
4993
|
|
|
4957
4994
|
**Implementation Notes**:
|
|
4958
4995
|
|
|
4959
|
-
- Worktree created at
|
|
4996
|
+
- Worktree created at `$GIT_COMMON_DIR/tbd/data-sync-worktree/`
|
|
4960
4997
|
|
|
4961
4998
|
- Worktree directory added to `.tbd/.gitignore`
|
|
4962
4999
|
|
|
@@ -5034,7 +5071,7 @@ matching. For large repositories (10K+ issues), this could be optimized:
|
|
|
5034
5071
|
**Implementation:**
|
|
5035
5072
|
|
|
5036
5073
|
```bash
|
|
5037
|
-
rg -i -C 2 --type md "pattern"
|
|
5074
|
+
rg -i -C 2 --type md "pattern" "$(git rev-parse --path-format=absolute --git-common-dir)/tbd/data-sync-worktree/.tbd/data-sync/issues/"
|
|
5038
5075
|
```
|
|
5039
5076
|
|
|
5040
5077
|
Post-process results to:
|
|
@@ -5905,3 +5942,7 @@ implement GitHub bridge later with plugin architecture for other providers.
|
|
|
5905
5942
|
* * *
|
|
5906
5943
|
|
|
5907
5944
|
**End of tbd Design Specification**
|
|
5945
|
+
|
|
5946
|
+
<!-- This document follows common-doc-guidelines.md.
|
|
5947
|
+
See github.com/jlevy/practical-prose and review guidelines before editing.
|
|
5948
|
+
-->
|
package/dist/docs/tbd-docs.md
CHANGED
|
@@ -14,8 +14,10 @@ tbd stores issues on a dedicated `tbd-sync` branch, separate from your code:
|
|
|
14
14
|
|
|
15
15
|
```
|
|
16
16
|
.tbd/
|
|
17
|
-
|
|
18
|
-
|
|
17
|
+
└── config.yml # Configuration (tracked on main)
|
|
18
|
+
|
|
19
|
+
$GIT_COMMON_DIR/tbd/
|
|
20
|
+
└── data-sync-worktree/ # Hidden worktree shared by linked checkouts
|
|
19
21
|
└── .tbd/data-sync/
|
|
20
22
|
├── issues/ # One .md file per issue
|
|
21
23
|
├── mappings/ids.yml # Short ID → ULID mapping
|
|
@@ -968,15 +970,16 @@ my-project/
|
|
|
968
970
|
│ ├── workspaces/ # Persistent state (outbox, named workspaces)
|
|
969
971
|
│ │
|
|
970
972
|
│ │ Gitignored (local only):
|
|
971
|
-
│
|
|
972
|
-
│
|
|
973
|
-
|
|
974
|
-
|
|
975
|
-
|
|
976
|
-
|
|
977
|
-
|
|
978
|
-
│
|
|
979
|
-
|
|
973
|
+
│ └── state.yml # Local state
|
|
974
|
+
│
|
|
975
|
+
└── $GIT_COMMON_DIR/tbd/
|
|
976
|
+
└── data-sync-worktree/ # Hidden worktree shared by linked checkouts
|
|
977
|
+
└── .tbd/data-sync/
|
|
978
|
+
├── issues/ # Issue files (*.md)
|
|
979
|
+
├── mappings/ # ID mappings
|
|
980
|
+
│ └── ids.yml # Short ID → ULID mapping
|
|
981
|
+
├── attic/ # Conflict archive
|
|
982
|
+
└── meta.yml # Schema version
|
|
980
983
|
```
|
|
981
984
|
|
|
982
985
|
### Issue File Format
|
|
@@ -1109,10 +1112,10 @@ tbd uses short display IDs (`proj-a7k2`) that map to internal ULIDs
|
|
|
1109
1112
|
|
|
1110
1113
|
```bash
|
|
1111
1114
|
# Find the actual issue file
|
|
1112
|
-
ls
|
|
1115
|
+
ls "$(git rev-parse --path-format=absolute --git-common-dir)/tbd/data-sync-worktree/.tbd/data-sync/issues"/is-01hx5*.md
|
|
1113
1116
|
|
|
1114
1117
|
# Internal IDs sort chronologically (creation order)
|
|
1115
|
-
ls
|
|
1118
|
+
ls "$(git rev-parse --path-format=absolute --git-common-dir)/tbd/data-sync-worktree/.tbd/data-sync/issues/" | sort
|
|
1116
1119
|
```
|
|
1117
1120
|
|
|
1118
1121
|
### Performance
|
|
@@ -1153,3 +1156,7 @@ tbd help <command> # Alternative help syntax
|
|
|
1153
1156
|
```
|
|
1154
1157
|
|
|
1155
1158
|
**Project Repo**: https://github.com/jlevy/tbd
|
|
1159
|
+
|
|
1160
|
+
<!-- This document follows common-doc-guidelines.md.
|
|
1161
|
+
See github.com/jlevy/practical-prose and review guidelines before editing.
|
|
1162
|
+
-->
|
package/dist/docs/tbd-prime.md
CHANGED
|
@@ -118,3 +118,7 @@ tbd dep add <tests-id> <feature-id> # Tests depend on feature
|
|
|
118
118
|
- **Issue types**: task, bug, feature, epic
|
|
119
119
|
- **Status values**: open, in_progress, closed
|
|
120
120
|
- **JSON output**: Add `--json` to any command for machine-readable output
|
|
121
|
+
|
|
122
|
+
<!-- This document follows common-doc-guidelines.md.
|
|
123
|
+
See github.com/jlevy/practical-prose and review guidelines before editing.
|
|
124
|
+
-->
|
|
@@ -1,3 +1,3 @@
|
|
|
1
|
-
import { a as hasShortId, c as parseIdMappingFromYaml, d as resolveToInternalId, f as saveIdMapping, i as generateUniqueShortId, l as reconcileMappings, n as calculateOptimalLength, o as loadIdMapping, r as createShortIdMapping, s as mergeIdMappings, t as addIdMapping, u as resolveIdMappingConflicts } from "./id-mapping-
|
|
1
|
+
import { a as hasShortId, c as parseIdMappingFromYaml, d as resolveToInternalId, f as saveIdMapping, i as generateUniqueShortId, l as reconcileMappings, n as calculateOptimalLength, o as loadIdMapping, r as createShortIdMapping, s as mergeIdMappings, t as addIdMapping, u as resolveIdMappingConflicts } from "./id-mapping-CtfTfGIh.mjs";
|
|
2
2
|
|
|
3
3
|
export { loadIdMapping, mergeIdMappings, parseIdMappingFromYaml, reconcileMappings, resolveIdMappingConflicts, saveIdMapping };
|