get-tbd 0.1.30 → 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.
Files changed (91) hide show
  1. package/README.md +5 -1
  2. package/dist/bin.mjs +2823 -2226
  3. package/dist/bin.mjs.map +1 -1
  4. package/dist/cli.mjs +1063 -665
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/{config-DVap9omo.mjs → config-BJz1m9eN.mjs} +179 -39
  7. package/dist/config-BJz1m9eN.mjs.map +1 -0
  8. package/dist/{config-BPHcePSm.mjs → config-DlCUMyCG.mjs} +1 -1
  9. package/dist/docs/README.md +5 -1
  10. package/dist/docs/guidelines/backward-compatibility-rules.md +4 -0
  11. package/dist/docs/guidelines/bun-monorepo-patterns.md +20 -4
  12. package/dist/docs/guidelines/cli-agent-skill-patterns.md +38 -34
  13. package/dist/docs/guidelines/commit-conventions.md +4 -0
  14. package/dist/docs/guidelines/common-doc-guidelines.md +234 -0
  15. package/dist/docs/guidelines/convex-limits-best-practices.md +4 -0
  16. package/dist/docs/guidelines/convex-rules.md +4 -0
  17. package/dist/docs/guidelines/electron-app-development-patterns.md +4 -0
  18. package/dist/docs/guidelines/error-handling-rules.md +4 -0
  19. package/dist/docs/guidelines/general-coding-rules.md +4 -0
  20. package/dist/docs/guidelines/general-comment-rules.md +4 -0
  21. package/dist/docs/guidelines/general-eng-assistant-rules.md +4 -0
  22. package/dist/docs/guidelines/general-tdd-guidelines.md +4 -0
  23. package/dist/docs/guidelines/general-testing-rules.md +4 -0
  24. package/dist/docs/guidelines/golden-testing-guidelines.md +4 -0
  25. package/dist/docs/guidelines/pnpm-monorepo-patterns.md +27 -6
  26. package/dist/docs/guidelines/python-cli-patterns.md +4 -0
  27. package/dist/docs/guidelines/python-modern-guidelines.md +30 -0
  28. package/dist/docs/guidelines/python-rules.md +4 -0
  29. package/dist/docs/guidelines/release-notes-guidelines.md +4 -0
  30. package/dist/docs/guidelines/supply-chain-hardening.md +11 -7
  31. package/dist/docs/guidelines/tbd-sync-troubleshooting.md +10 -4
  32. package/dist/docs/guidelines/typescript-cli-tool-rules.md +27 -24
  33. package/dist/docs/guidelines/typescript-code-coverage.md +11 -7
  34. package/dist/docs/guidelines/typescript-rules.md +10 -6
  35. package/dist/docs/guidelines/typescript-sorting-patterns.md +4 -0
  36. package/dist/docs/guidelines/typescript-yaml-handling-rules.md +7 -3
  37. package/dist/docs/shortcuts/standard/agent-handoff.md +4 -0
  38. package/dist/docs/shortcuts/standard/checkout-third-party-repo.md +4 -0
  39. package/dist/docs/shortcuts/standard/code-cleanup-all.md +4 -0
  40. package/dist/docs/shortcuts/standard/code-cleanup-docstrings.md +4 -0
  41. package/dist/docs/shortcuts/standard/code-cleanup-tests.md +4 -0
  42. package/dist/docs/shortcuts/standard/code-review-and-commit.md +4 -0
  43. package/dist/docs/shortcuts/standard/coding-spike.md +4 -0
  44. package/dist/docs/shortcuts/standard/create-or-update-pr-simple.md +4 -0
  45. package/dist/docs/shortcuts/standard/create-or-update-pr-with-validation-plan.md +4 -0
  46. package/dist/docs/shortcuts/standard/implement-beads.md +4 -0
  47. package/dist/docs/shortcuts/standard/merge-upstream.md +4 -0
  48. package/dist/docs/shortcuts/standard/new-architecture-doc.md +4 -0
  49. package/dist/docs/shortcuts/standard/new-guideline.md +4 -0
  50. package/dist/docs/shortcuts/standard/new-plan-spec.md +4 -0
  51. package/dist/docs/shortcuts/standard/new-qa-playbook.md +4 -0
  52. package/dist/docs/shortcuts/standard/new-research-brief.md +4 -0
  53. package/dist/docs/shortcuts/standard/new-shortcut.md +4 -0
  54. package/dist/docs/shortcuts/standard/new-validation-plan.md +4 -0
  55. package/dist/docs/shortcuts/standard/plan-implementation-with-beads.md +4 -0
  56. package/dist/docs/shortcuts/standard/precommit-process.md +4 -0
  57. package/dist/docs/shortcuts/standard/review-code-python.md +4 -0
  58. package/dist/docs/shortcuts/standard/review-code-typescript.md +4 -0
  59. package/dist/docs/shortcuts/standard/review-code.md +4 -0
  60. package/dist/docs/shortcuts/standard/review-github-pr.md +4 -0
  61. package/dist/docs/shortcuts/standard/revise-all-architecture-docs.md +4 -0
  62. package/dist/docs/shortcuts/standard/revise-architecture-doc.md +4 -0
  63. package/dist/docs/shortcuts/standard/setup-github-cli.md +4 -0
  64. package/dist/docs/shortcuts/standard/sync-failure-recovery.md +4 -0
  65. package/dist/docs/shortcuts/standard/update-specs-status.md +4 -0
  66. package/dist/docs/shortcuts/standard/welcome-user.md +4 -0
  67. package/dist/docs/tbd-closing.md +4 -0
  68. package/dist/docs/tbd-design.md +109 -68
  69. package/dist/docs/tbd-docs.md +20 -13
  70. package/dist/docs/tbd-prime.md +4 -0
  71. package/dist/docs/templates/architecture-doc.md +4 -0
  72. package/dist/docs/templates/plan-spec.md +4 -0
  73. package/dist/docs/templates/qa-playbook.md +4 -0
  74. package/dist/docs/templates/research-brief.md +4 -0
  75. package/dist/{id-mapping-Ctfl_nc1.mjs → id-mapping-CFoPVinz.mjs} +1 -1
  76. package/dist/{id-mapping-CqrrLgeX.mjs → id-mapping-CtfTfGIh.mjs} +146 -122
  77. package/dist/id-mapping-CtfTfGIh.mjs.map +1 -0
  78. package/dist/index.d.mts +53 -1
  79. package/dist/index.mjs +3 -3
  80. package/dist/{schemas-C8mOQykE.mjs → schemas-f0EcuAVu.mjs} +40 -3
  81. package/dist/schemas-f0EcuAVu.mjs.map +1 -0
  82. package/dist/{src-BK_EF6mk.mjs → src-rIE4xSVs.mjs} +3 -3
  83. package/dist/src-rIE4xSVs.mjs.map +1 -0
  84. package/dist/tbd +2823 -2226
  85. package/package.json +1 -1
  86. package/dist/config-DVap9omo.mjs.map +0 -1
  87. package/dist/docs/guidelines/general-style-rules.md +0 -38
  88. package/dist/docs/guidelines/writing-style-guidelines.md +0 -42
  89. package/dist/id-mapping-CqrrLgeX.mjs.map +0 -1
  90. package/dist/schemas-C8mOQykE.mjs.map +0 -1
  91. package/dist/src-BK_EF6mk.mjs.map +0 -1
@@ -714,14 +714,17 @@ current node’s prefix.
714
714
 
715
715
  ### 2.2 Directory Structure
716
716
 
717
- tbd uses three directory locations:
717
+ tbd uses four directory locations:
718
718
 
719
719
  - **`.tbd/`** on main branch: Configuration (tracked) + installed docs (gitignored)
720
720
 
721
- - **`.tbd/data-sync-worktree/`** hidden worktree: Checkout of `tbd-sync` branch for
722
- search
721
+ - **`$GIT_COMMON_DIR/tbd/`** local repo-scoped machinery shared by the main checkout and
722
+ all linked worktrees
723
723
 
724
- - **`.tbd/data-sync/`** on `tbd-sync` branch: Synced entities and attic
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
- └── data-sync-worktree/ # Hidden worktree
754
- └── (checkout of tbd-sync branch)
755
- └── .tbd/
756
- └── data-sync/
757
- ├── issues/
758
- │ ├── is-a1b2c3.md
759
- │ └── is-f14c3d.md
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 a **hidden git worktree** at `.tbd/data-sync-worktree/` that checks out
800
- the `tbd-sync` branch.
801
- This provides:
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 .tbd/data-sync-worktree tbd-sync
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 .tbd/data-sync-worktree --orphan tbd-sync
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 `.tbd/` which is partially gitignored
849
+ - **Hidden location**: Inside Git’s common directory, not inside any single checkout
832
850
 
833
- - **Safe updates**: `tbd sync` does `git -C .tbd/data-sync-worktree pull` after push
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:** `backups/` on the main branch is for local backups only (corrupted
864
- > worktrees, data migrations).
865
- > This is different from `.tbd/data-sync/attic/` on the sync branch which stores merge
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 .tbd/data-sync-worktree/.tbd/data-sync/issues/is-a1b2c3.md
920
+ cat "$WORKTREE/.tbd/data-sync/issues/is-a1b2c3.md"
897
921
 
898
922
  # ripgrep search across all issues
899
- rg "authentication" .tbd/data-sync-worktree/.tbd/data-sync/issues/
923
+ rg "authentication" "$WORKTREE/.tbd/data-sync/issues/"
900
924
 
901
925
  # List all issues
902
- ls .tbd/data-sync-worktree/.tbd/data-sync/issues/
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` | `git -C data-sync-worktree pull origin tbd-sync` |
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 `.tbd/data-sync-worktree/` always reflects the
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 .tbd/data-sync-worktree/ exist and contain valid checkout?
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 .tbd/data-sync-worktree tbd-sync
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 .tbd/data-sync-worktree tbd-sync
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 .tbd/data-sync-worktree --orphan tbd-sync
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(.tbd/data-sync-worktree/)` | Create from local or remote branch |
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 or invalid gitdir pointer | **Backup to .tbd/backups/**, then recreate |
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
- mv .tbd/data-sync-worktree .tbd/backups/corrupted-worktree-backup-$(date +%Y%m%d-%H%M%S)
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 `.tbd/backups/` which is gitignored (see §3.6), preserving the
976
- data for manual recovery while not polluting the repository.
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 = join(baseDir, '.tbd/data-sync-worktree');
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** | `.tbd/data-sync-worktree/.tbd/data-sync/` | **Production path** — inside hidden worktree checkout |
1016
- | **Direct path** | `.tbd/data-sync/` | **Test-only path** — gitignored on main, should NEVER contain data in production |
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 = join(baseDir, '.tbd/data-sync-worktree/.tbd/data-sync');
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
- 'Worktree not found at .tbd/data-sync-worktree/. ' +
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/ # Local backups (corrupted worktrees, migrated data)
2015
- .tbd/data-sync-worktree/ # Hidden worktree for search access
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: Verify worktree health (see §2.3.4)
2107
- - If unhealthy and options.fix: repair worktree
2108
- - If unhealthy and not options.fix: throw WorktreeMissingError/WorktreeCorruptedError
2109
- 1. Resolve data path via resolveDataSyncDir() uses worktree path
2110
- 2. Fetch remote sync branch
2111
- 3. Update worktree to remote state (preserving local uncommitted changes)
2112
- 4. Commit worktree changes to sync branch
2113
- 5. Push to remote
2114
- 6. If push rejected (non-fast-forward): retry with merge (see 3.3.2)
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 `.tbd/data-sync-worktree/.tbd/data-sync/`.
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: .tbd/data-sync-worktree/ (healthy)
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": ".tbd/data-sync-worktree/",
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 `.tbd/backups/corrupted-worktree-backup-YYYYMMDD-HHMMSS/`** (prevents
3375
- data loss)
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: `git worktree add .tbd/data-sync-worktree tbd-sync`
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 `.tbd/backups/tbd-data-sync-backup-YYYYMMDD-HHMMSS/`
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:** Backups are stored in `.tbd/backups/` which is gitignored.
3390
- > Users can manually inspect backups to recover any data that wasn’t committed before
3391
- > the worktree became corrupted.
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 `.tbd/data-sync-worktree/`
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 `.tbd/`, doesn’t pollute working directory
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**: Gitignored, doesn’t appear in user’s `git 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 `.tbd/data-sync-worktree/`
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" .tbd/data-sync-worktree/.tbd/data-sync/issues/
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
+ -->
@@ -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
- ├── config.yml # Configuration (tracked on main)
18
- └── data-sync-worktree/ # Hidden worktree (gitignored)
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
- ├── state.yml # Local state
972
- └── data-sync-worktree/ # Hidden worktree
973
- └── .tbd/
974
- └── data-sync/
975
- │ ├── issues/ # Issue files (*.md)
976
- ├── mappings/ # ID mappings
977
- │ │ └── ids.yml # Short ID → ULID mapping
978
- ├── attic/ # Conflict archive
979
- │ └── meta.yml # Schema version
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 .tbd/data-sync-worktree/.tbd/data-sync/issues/is-01hx5*.md
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 .tbd/data-sync-worktree/.tbd/data-sync/issues/ | sort
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
+ -->
@@ -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
+ -->
@@ -120,3 +120,7 @@ How this component scales under load.
120
120
 
121
121
  - [Related doc](url)
122
122
  - [External reference](url)
123
+
124
+ <!-- This document follows common-doc-guidelines.md.
125
+ See github.com/jlevy/practical-prose and review guidelines before editing.
126
+ -->
@@ -71,3 +71,7 @@ How will this feature be deployed?
71
71
 
72
72
  - Link to related docs
73
73
  - Link to related issues
74
+
75
+ <!-- This document follows common-doc-guidelines.md.
76
+ See github.com/jlevy/practical-prose and review guidelines before editing.
77
+ -->
@@ -187,3 +187,7 @@ Before marking this test as **PASSED**, verify:
187
187
  - [ ] [Performance/quality threshold met]
188
188
 
189
189
  * * *
190
+
191
+ <!-- This document follows common-doc-guidelines.md.
192
+ See github.com/jlevy/practical-prose and review guidelines before editing.
193
+ -->
@@ -115,3 +115,7 @@ author: Joshua Levy (github.com/jlevy) with LLM assistance
115
115
 
116
116
  - [Link 1](url)
117
117
  - [Link 2](url)
118
+
119
+ <!-- This document follows common-doc-guidelines.md.
120
+ See github.com/jlevy/practical-prose and review guidelines before editing.
121
+ -->
@@ -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-CqrrLgeX.mjs";
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 };