get-tbd 0.2.1 → 0.2.3

package/dist/docs/guidelines/tbd-sync-troubleshooting.md

@@ -31,6 +31,24 @@ tbd sync
 4. Import happens automatically when you later run `tbd sync` in an environment that can
    push
 
+### Push Fails Because Histories Are Unrelated
+
+**Symptoms:**
+- `tbd sync` aborts with “`origin/tbd-sync` has an unrelated history (no common
+  ancestor)”
+- `tbd doctor` reports the remote sync branch histories are unrelated
+- Push cannot fast-forward and a merge refuses
+
+**Causes:**
+- The local `tbd-sync` branch and `origin/tbd-sync` were created independently—for
+  example, two clones each initialized their own sync branch, or the remote branch was
+  replaced—so the two have no common ancestor
+
+**Solutions:**
+1. Run `tbd doctor --fix` to reconcile the unrelated histories.
+   This is non-destructive: a backup branch is created first.
+2. Run `tbd sync` again to confirm the push succeeds.
+
 ### “Already in sync” but data not on remote
 
 **Symptoms:**
@@ -60,7 +78,8 @@ auto-saving, since the issue is likely temporary.
 1. Check network connectivity
 2. Verify remote URL: `git remote -v`
 3. Retry: `tbd sync`
-4. If persistent, manually save: `tbd save --workspace=offline-backup`
+4. If persistent, save for later: `tbd save --outbox` (auto-imports on the next
+   successful sync)
 
 ### Bulk Trivial Changes in Outbox (Version/Timestamp Only)
 
@@ -79,7 +98,7 @@ auto-saving, since the issue is likely temporary.
 
 **What tbd now does:**
 - `mergeIssues()` detects no-op merges and skips the version/timestamp bump
-- `getUpdatedIssues()` ignores `version` and `updated_at` when filtering — only issues
+- `getUpdatedIssues()` ignores `version` and `updated_at` when filtering—only issues
   with actual content changes (title, status, labels, description, etc.)
   are saved
 - When fetch fails, the cached `origin/tbd-sync` ref is used for comparison instead of
@@ -87,7 +106,7 @@ auto-saving, since the issue is likely temporary.
 
 **If you encounter this with an older version:**
 1. Update tbd: `npm install -g get-tbd@latest`
-2. If you already have a large outbox, you can safely import it — the import will merge
+2. If you already have a large outbox, you can safely import it—the import will merge
    using field-level LWW and the trivial changes will be harmless
 3. Run `tbd sync` to clear the outbox
 
@@ -123,7 +142,7 @@ auto-saving, since the issue is likely temporary.
 ### Don’t gitignore .tbd/workspaces/
 
 When `tbd sync` fails and auto-saves to `.tbd/workspaces/outbox/`, a new untracked
-directory appears. Do not add it to `.gitignore` — the outbox must be committed to your
+directory appears. Do not add it to `.gitignore`—the outbox must be committed to your
 working branch so unsynced data survives across sessions.
 
 **What to do instead:**
@@ -193,7 +212,8 @@ The `.tbd/.gitignore` file contains a `!workspaces/` negation pattern to prevent
 - Commands fail with worktree errors
 
 **Solutions:**
-1. Run `tbd doctor --fix` to auto-repair
+1. Run `tbd doctor --fix` to auto-repair, or `tbd sync --fix` to repair the worktree as
+   part of a sync
 2. If that fails, manually repair:
    ```bash
    rm -rf "$(git rev-parse --path-format=absolute --git-common-dir)/tbd/data-sync-worktree"
@@ -258,6 +278,8 @@ tbd sync
 **CLI Options:**
 - `--no-auto-save`: Skip automatic save to outbox on failure
 - `--no-outbox`: Skip automatic import from outbox on success
+- `--fix`: Repair an unhealthy worktree before syncing
+- `--status`: Show sync status without syncing
 
 See `tbd shortcut sync-failure-recovery` for the full workflow.
 

package/dist/docs/guidelines/typescript-cli-tool-rules.md

@@ -13,9 +13,9 @@ Commander 14 moves to security-only maintenance until May 2027.
 
 **Related**:
 
-- [TypeScript Rules](./typescript-rules.md)
-- [Supply-Chain Mitigation](./pnpm-monorepo-patterns.md#supply-chain-mitigation) —
-  follow the 14-day package-age rule for every CLI dependency.
+- `typescript-rules`
+- `error-handling-rules`—failure paths and exit codes are part of every CLI command.
+- `supply-chain-hardening`—follow the 14-day package-age rule for every CLI dependency.
   Bundlers and CLI dependencies that execute at install time (`postinstall` scripts) are
   a primary attack surface.
 
@@ -368,10 +368,10 @@ context, output, and error handling.
 Strict separation of data and diagnostics enables pipeline composability.
 
 - **Data to stdout:** `data()`, `success()`, `notice()`, `dryRun()`, `table()`,
-  `list()`, `count()` — all go to `console.log` (stdout).
+  `list()`, `count()`—all go to `console.log` (stdout).
 
 - **Diagnostics to stderr:** `info()`, `warn()`, `error()`, `command()`, `debug()`,
-  `spinner` — all go to `console.error` (stderr) or `process.stderr.write`.
+  `spinner`—all go to `console.error` (stderr) or `process.stderr.write`.
 
 - **JSON mode wraps diagnostics:** `warn()` outputs `{"warning": "..."}` to stderr.
   `error()` outputs `{"error": "..."}` to stderr.
@@ -579,7 +579,7 @@ seamlessly in local dev and in remote environments.
   precedence logic, or runtime conditional loading from inside the CLI).
 
 - **Use `dotenv` only when needed:** Add `dotenv` only if your CLI must load env files
-  programmatically — e.g., it reads them after parsing command-line flags, performs
+  programmatically—e.g., it reads them after parsing command-line flags, performs
   variable expansion, or supports custom file paths the user cannot pre-bake into the
   `node` invocation.
 
@@ -615,11 +615,11 @@ seamlessly in local dev and in remote environments.
 
 - **Standard environment variables to respect:**
 
-  - `NO_COLOR` — disable colors (standard)
-  - `FORCE_COLOR` — force colors
-  - `CI` — detect CI environment, force non-interactive
-  - `DEBUG` — enable debug logging (or a namespaced equivalent like `<TOOL>_DEBUG`)
-  - `PAGER` — custom pager command for long output
+  - `NO_COLOR`—disable colors (standard)
+  - `FORCE_COLOR`—force colors
+  - `CI`—detect CI environment, force non-interactive
+  - `DEBUG`—enable debug logging (or a namespaced equivalent like `<TOOL>_DEBUG`)
+  - `PAGER`—custom pager command for long output
 
 ## Sub-Command Logging for Testability
 
@@ -705,27 +705,27 @@ runtimes, Cloudflare Workers, etc.).
 
 **Key patterns:**
 
-- **Base Command Pattern** — All handlers extend `BaseCommand`, which provides
+- **Base Command Pattern**—All handlers extend `BaseCommand`, which provides
   `CommandContext`, `OutputManager`, `execute()` error wrapping, and `checkDryRun()`
 
-- **Dual Output Mode** — `OutputManager.data(data, textFormatter)` switches between JSON
+- **Dual Output Mode**—`OutputManager.data(data, textFormatter)` switches between JSON
   and text formatting based on `--json` flag
 
-- **Handler + Command Structure** — Command definition (`.option()`, `.action()`) is
+- **Handler + Command Structure**—Command definition (`.option()`, `.action()`) is
   separate from handler class implementation.
   Action handlers do `new XxxHandler(command)` then `handler.run(options)`
 
-- **Version Handling** — Prefer deterministic runtime version resolution: build-time
+- **Version Handling**—Prefer deterministic runtime version resolution: build-time
   injection first, then environment override for dev/test, then `package.json` fallback
 
-- **Global Options** — Define `--dry-run`, `--verbose`, `--quiet`, `--json`, `--color`,
+- **Global Options**—Define `--dry-run`, `--verbose`, `--quiet`, `--json`, `--color`,
   and `--debug` at program level, plus tool-specific options as needed.
   Only add `--non-interactive` and `--yes` if the CLI has interactive prompts
 
-- **Stdout/Stderr Separation** — Data to stdout, diagnostics to stderr for pipeline
+- **Stdout/Stderr Separation**—Data to stdout, diagnostics to stderr for pipeline
   compatibility. See the Stdout/Stderr Separation section above for details
 
-- **Terminal Width Management** — Cap help text and formatted output at a maximum width
+- **Terminal Width Management**—Cap help text and formatted output at a maximum width
   (e.g., 88 chars) for readability, using narrower if the terminal is smaller
 
 ## Best Practices

package/dist/docs/guidelines/typescript-code-coverage.md

@@ -7,15 +7,17 @@ author: Joshua Levy (github.com/jlevy) with LLM assistance
 
 **Last Updated**: 2026-05-21
 
-**Tracks**: Vitest `^4.1.7`, `@vitest/coverage-v8` `^4.1.7`. Vitest 5.0 is in beta — do
+**Tracks**: Vitest `^4.1.7`, `@vitest/coverage-v8` `^4.1.7`. Vitest 5.0 is in beta—do
 not adopt yet.
 
 **Related**:
 
-- [Companion: pnpm Monorepo Patterns — Testing](./pnpm-monorepo-patterns.md#8-testing)
-- [Supply-Chain Mitigation](./pnpm-monorepo-patterns.md#supply-chain-mitigation) —
-  follow the 14-day package-age rule when installing or upgrading `vitest` and
-  `@vitest/coverage-v8`.
+- `typescript-rules`
+- `general-testing-rules` and `general-tdd-guidelines`—what to test and the red-green
+  workflow that coverage measures.
+- `pnpm-monorepo-patterns`—the Testing section covers the monorepo test setup.
+- `supply-chain-hardening`—follow the 14-day package-age rule when installing or
+  upgrading `vitest` and `@vitest/coverage-v8`.
 
 ## Coverage Metrics
 
@@ -95,7 +97,7 @@ upgrade: use `ncu --cooldown 14` or `pnpm install --frozen-lockfile`.
 - **`coverage.all` was removed** in Vitest 4. Use `coverage.include` and
   `coverage.exclude` to define exactly which files are reported.
 - Coverage reporters and v8 provider now ship as part of `@vitest/coverage-v8` aligned
-  with the Vitest major version — pin them together.
+  with the Vitest major version—pin them together.
 
 ### Example Configuration
 

package/dist/docs/guidelines/typescript-rules.md

@@ -11,19 +11,17 @@ alwaysApply: true
 
 **Tracks**: TypeScript `^6.0.3` (stable).
 TypeScript 7.0 Beta (`@typescript/native-preview`, binary `tsgo`) is available but **not
-yet production-ready** — do not adopt for shipped builds.
+yet production-ready**—do not adopt for shipped builds.
 
 **Related**:
 
-- [TypeScript CLI Tool Rules](./typescript-cli-tool-rules.md)
-- [TypeScript Sorting Patterns](./typescript-sorting-patterns.md)
-- [TypeScript YAML Handling Rules](./typescript-yaml-handling-rules.md)
-- [TypeScript Code Coverage](./typescript-code-coverage.md)
-- [pnpm Monorepo Patterns](./pnpm-monorepo-patterns.md) and
-  [Bun Monorepo Patterns](./bun-monorepo-patterns.md)
-- [Supply-Chain Mitigation](./pnpm-monorepo-patterns.md#supply-chain-mitigation) — the
-  14-day package-age rule applies to every TypeScript dependency (`zod`, `commander`,
-  `vitest`, `eslint`, type packages, etc.).
+- `typescript-cli-tool-rules`
+- `typescript-sorting-patterns`
+- `typescript-yaml-handling-rules`
+- `typescript-code-coverage`
+- `pnpm-monorepo-patterns` and `bun-monorepo-patterns`
+- `supply-chain-hardening`—the 14-day package-age rule applies to every TypeScript
+  dependency (`zod`, `commander`, `vitest`, `eslint`, type packages, etc.).
 
 ## Coding Style
 
@@ -352,7 +350,7 @@ yet production-ready** — do not adopt for shipped builds.
 
 - **Barrel files:** The rules differ for libraries vs applications.
 
-  **For libraries:** Use exactly ONE barrel file — the root `index.ts` that defines the
+  **For libraries:** Use exactly ONE barrel file—the root `index.ts` that defines the
   public API. This is essential for consumers who `import { X } from 'your-library'`. Do
   NOT create module-level barrels (like `utils/index.ts` or `harness/index.ts`).
   Internal code should import directly from source files.

package/dist/docs/guidelines/typescript-sorting-patterns.md

@@ -5,7 +5,7 @@ author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 # TypeScript Sorting Patterns
 
-**Related**: `tbd guidelines typescript-rules`, `tbd guidelines general-testing-rules`
+**Related**: `typescript-rules`, `general-testing-rules`
 
 ## 1. Always Make Sorting Deterministic
 

package/dist/docs/guidelines/typescript-yaml-handling-rules.md

@@ -9,14 +9,14 @@ globs: "*.ts"
 **Last Updated**: 2026-05-21
 
 **Tracks**: `yaml@^2.8.4` (latest stable; 2026-05-02). The `yaml@3.0.0-1` release is
-tagged `next` (pre-release) — do not adopt yet.
+tagged `next` (pre-release)—do not adopt yet.
 Zod 4.x is the recommended validation companion.
 
 **Related**:
 
-- [TypeScript Rules](./typescript-rules.md)
-- [Supply-Chain Mitigation](./pnpm-monorepo-patterns.md#supply-chain-mitigation) —
-  follow the 14-day package-age rule for `yaml`, `zod`, and `gray-matter`.
+- `typescript-rules`
+- `supply-chain-hardening`—follow the 14-day package-age rule for `yaml`, `zod`, and
+  `gray-matter`.
 
 These guidelines ensure consistent, safe, and readable YAML handling across TypeScript
 codebases. YAML is deceptively tricky—inconsistent quoting, serialization differences,
@@ -203,8 +203,8 @@ const output = `---\n${stringifyYaml(data)}---\n\n${content}`;
 
 ## Related Guidelines
 
-- For general TypeScript rules, see `tbd guidelines typescript-rules`
-- For error handling patterns, see `tbd guidelines error-handling-rules`
+- For general TypeScript rules, see `typescript-rules`
+- For error handling patterns, see `error-handling-rules`
 
 <!-- This document follows common-doc-guidelines.md.
 See github.com/jlevy/practical-prose and review guidelines before editing.

package/dist/docs/shortcuts/standard/new-shortcut.md

@@ -53,6 +53,20 @@ Examples: `code-review-and-commit`, `new-plan-spec`, `review-code-typescript`
 - **Reference, don’t duplicate**: Point to `tbd shortcut/guidelines/template` commands
 - **Trust the agent**: They’ll adapt to context
 
+## Referencing Other Shortcuts
+
+Refer to other shortcuts, guidelines, and templates by **name**, using the command that
+surfaces them — never by file path:
+
+- Another shortcut: `tbd shortcut <name>` (e.g. `tbd shortcut precommit-process`)
+- A guideline: `tbd guidelines <name>` (e.g. `tbd guidelines typescript-rules`)
+- A template: `tbd template <name>` (e.g. `tbd template plan-spec`)
+
+The name stays valid wherever the file ends up — read directly, served via
+`tbd shortcut`, or embedded in another tool.
+File paths and relative markdown links break when shortcuts are flattened into the
+`.tbd` cache or relocated, so don’t use them to point at other shortcuts.
+
 ## Testing
 
 ```bash

package/dist/docs/shortcuts/standard/setup-github-cli.md

@@ -64,7 +64,10 @@ If this fails for any reason, follow the steps below.
 
 Set `GH_TOKEN` environment variable with a GitHub personal access token **before**
 starting the session.
-See `docs/general/agent-setup/github-cli-setup.md` for token creation instructions.
+Create a [Personal Access Token](https://github.com/settings/tokens?type=beta)
+(fine-grained recommended) with **Contents** and **Pull requests** read/write
+permissions, then export it (e.g. add `export GH_TOKEN=...` to your shell profile or set
+it in your agent environment).
 
 ## Quick Reference
 

package/dist/docs/shortcuts/system/shortcut-explanation.md

@@ -24,6 +24,20 @@ These may include:
 - File operations and git workflows
 - Prompts for gathering information from the user
 
+## Referencing Other Shortcuts, Guidelines, and Templates
+
+Shortcuts refer to each other by **name**, using the command that surfaces them:
+
+- Another shortcut: `tbd shortcut <name>` (e.g. `tbd shortcut precommit-process`)
+- A guideline: `tbd guidelines <name>` (e.g. `tbd guidelines typescript-rules`)
+- A template: `tbd template <name>` (e.g. `tbd template plan-spec`)
+
+Always reference by name, never by file path.
+The name is stable wherever the shortcut lives, so the reference stays valid whether the
+file is read directly, served via `tbd shortcut`, or embedded in another tool.
+File paths (and relative markdown links) break when shortcuts are flattened into the
+`.tbd` cache or relocated, so avoid them inside shortcut bodies.
+
 ## Example Workflow
 
 User: “I want to create a new research brief”
@@ -37,7 +51,8 @@ Agent:
 
 Shortcuts are loaded from directories in the doc path (searched in order):
 
-- `.tbd/docs/shortcuts/system/` - Core system docs (skill.md, etc.)
+- `.tbd/docs/shortcuts/system/` - Core system docs (skill-baseline,
+  shortcut-explanation, etc.)
 - `.tbd/docs/shortcuts/standard/` - Standard workflow shortcuts
 
 Directories earlier in the doc path take precedence.

package/dist/docs/shortcuts/system/skill-baseline.md

@@ -9,7 +9,7 @@ description: Full tbd workflow guide for agents
    Drop-in replacement for `bd`.
 2. **Spec-Driven Workflows**: Plan features → break into beads → implement
    systematically.
-3. **Knowledge Injection**: 17+ engineering guidelines (TypeScript, Python, TDD,
+3. **Knowledge Injection**: 25+ engineering guidelines (TypeScript, Python, TDD,
    testing, Convex, monorepos) available on demand.
 4. **Shortcuts**: Reusable instruction templates for common workflows (code review,
    commits, PRs, cleanup, handoffs).
@@ -71,6 +71,7 @@ or want help → run `tbd shortcut welcome-user`
 | “Create a PR” / “File a PR” | `tbd shortcut create-or-update-pr-simple` |
 | “Merge main into my branch” | `tbd shortcut merge-upstream` |
 | **Guidelines & Knowledge** |  |
+| *(any engineering work)* | Load the **General engineering** group first (see below) |
 | “Use TypeScript best practices” | `tbd guidelines typescript-rules` |
 | “Use Python best practices” | `tbd guidelines python-rules` |
 | “Build a TypeScript CLI” | `tbd guidelines typescript-cli-tool-rules` |
@@ -89,6 +90,12 @@ or want help → run `tbd shortcut welcome-user`
 | “Check out this library’s source” | `tbd shortcut checkout-third-party-repo` |
 | *(your choice whenever appropriate)* | `tbd list`, `tbd dep add`, `tbd close`, `tbd sync`, etc. |
 
+**Loading guidelines for engineering work:** Before writing or reviewing code, load the
+**General engineering** group—the `general-*` rules plus `error-handling-rules`—since
+these apply to all code regardless of language.
+Then load the group for the language or framework in use (TypeScript, Python, Convex,
+etc.). Run `tbd guidelines --list` to see all available guidelines.
+
 **Note:** Never gitignore `.tbd/workspaces/` — the outbox must be committed to your
 working branch. See `tbd guidelines tbd-sync-troubleshooting` for details.
 

package/dist/docs/tbd-design.md

@@ -18,8 +18,7 @@ agents.
   - [1. Introduction](#1-introduction)
     - [1.1 What is tbd?](#11-what-is-tbd)
     - [1.2 When to Use tbd vs Beads](#12-when-to-use-tbd-vs-beads)
-    - [1.3 Why Replace Beads?
-      (Architecture Comparison)](#13-why-replace-beads-architecture-comparison)
+    - [1.3 Why Replace Beads? (Architecture Comparison)](#13-why-replace-beads-architecture-comparison)
     - [1.4 Design Goals](#14-design-goals)
     - [1.5 Design Principles](#15-design-principles)
     - [1.6 Non-Goals](#16-non-goals)
@@ -235,23 +234,23 @@ on demand.
 
 tbd provides **three integrated capabilities**:
 
-1. **Task tracking (beads)** — Git-native issues, bugs, epics, and dependencies that
+1. **Task tracking (beads)**—Git-native issues, bugs, epics, and dependencies that
    persist across sessions.
    This alone is a step change in what agents can do.
-2. **Spec-driven planning** — Workflows for writing specs, breaking them into issues,
-   and implementing systematically.
-3. **Instant knowledge injection** — 17+ detailed guideline docs covering TypeScript,
-   Python, Convex, monorepo architecture, TDD, and more — injected into the agent’s
+2. **Spec-driven planning**—Workflows for writing specs, breaking them into issues, and
+   implementing systematically.
+3. **Instant knowledge injection**—17+ detailed guideline docs covering TypeScript,
+   Python, Convex, monorepo architecture, TDD, and more—injected into the agent’s
    context on demand via shortcuts, guidelines, and templates.
 
 The **issue tracking layer** has four core principles:
 
-- **Durable storage in git** — Issues are version-controlled and distributed via
-  standard git
-- **Works in almost any environment** — No daemon, no SQLite, no file locking issues on
+- **Durable storage in git**—Issues are version-controlled and distributed via standard
+  git
+- **Works in almost any environment**—No daemon, no SQLite, no file locking issues on
   network drives
-- **Simple, self-documenting CLI** — Designed for both AI agents and humans
-- **Transparent internal format** — Markdown/YAML files that are debuggable and friendly
+- **Simple, self-documenting CLI**—Designed for both AI agents and humans
+- **Transparent internal format**—Markdown/YAML files that are debuggable and friendly
   to other tooling
 
 It does *not* aim to be a full solution for real-time agent coordination.
@@ -291,17 +290,17 @@ layered on top of tbd or handled by other tools.
 
 **Related Projects:**
 
-- [Beads](https://github.com/steveyegge/beads) — The original git-backed issue tracker
-  tbd is designed to replace
-- [Agent Mail](https://github.com/Dicklesworthstone/mcp_agent_mail) — Real-time agent
+- [Beads](https://github.com/steveyegge/beads)—The original git-backed issue tracker tbd
+  is designed to replace
+- [Agent Mail](https://github.com/Dicklesworthstone/mcp_agent_mail)—Real-time agent
   messaging via MCP (complementary to tbd for coordination)
-- [Gas Town](https://github.com/steveyegge/gastown) — Multi-agent orchestration platform
+- [Gas Town](https://github.com/steveyegge/gastown)—Multi-agent orchestration platform
   (complementary to tbd for real-time coordination)
-- [ticket](https://github.com/wedow/ticket) — Bash-based Markdown+YAML tracker (~1900
+- [ticket](https://github.com/wedow/ticket)—Bash-based Markdown+YAML tracker (~1900
   tickets in production)
-- [git-bug](https://github.com/git-bug/git-bug) — Issues stored as git objects
-- [git-issue](https://github.com/dspinellis/git-issue) — Shell-based with optional
-  GitHub sync
+- [git-bug](https://github.com/git-bug/git-bug)—Issues stored as git objects
+- [git-issue](https://github.com/dspinellis/git-issue)—Shell-based with optional GitHub
+  sync
 
 ### 1.2 When to Use tbd vs Beads
 
@@ -659,6 +658,7 @@ serialization:
 > directory.
 
 > **Why canonical format?** Deterministic serialization ensures:
+> 
 > 1. Git diffs show only actual content changes (no spurious whitespace/ordering noise)
 > 2. Testing is reliable (same input produces same output)
 > 3. Future caching/deduplication can use content hashes if needed
@@ -790,10 +790,10 @@ $GIT_COMMON_DIR/tbd/
     └── meta.yml               # Metadata (schema version)
 ```
 
-> **Future: Simple Mode** — For users who don’t need multi-machine sync, tbd could
-> support a “simple mode” where `data-sync/` is committed directly to main instead of
-> using a worktree. This would be enabled by removing `data-sync` from `.tbd/.gitignore`.
-> Not implemented in V1, but the naming structure supports this future option.
+> **Future: Simple Mode**—For users who don’t need multi-machine sync, tbd could support
+> a “simple mode” where `data-sync/` is committed directly to main instead of using a
+> worktree. This would be enabled by removing `data-sync` from `.tbd/.gitignore`. Not
+> implemented in V1, but the naming structure supports this future option.
 
 **Why this structure?**
 
@@ -887,7 +887,7 @@ backups/
 > Both differ from `.tbd/data-sync/attic/` on the sync branch which stores merge
 > conflict losers.
 > 
-> **Note:** `workspaces/` must not be gitignored — it stores outbox data that must be
+> **Note:** `workspaces/` must not be gitignored—it stores outbox data that must be
 > committed to the working branch.
 
 #### .tbd/.gitattributes Contents
@@ -904,7 +904,7 @@ that directory.
 ```
 
 > **Why this is needed:** When a feature branch with outbox changes is merged back to
-> main (which has no outbox), git’s 3-way merge can delete `ids.yml` entirely — treating
+> main (which has no outbox), git’s 3-way merge can delete `ids.yml` entirely—treating
 > “no file” on main as the correct state.
 > This causes all tbd commands to crash with “No short ID mapping found”.
 > The `merge=union` built-in merge driver keeps all lines from both sides, preventing
@@ -1037,8 +1037,8 @@ async function checkWorktreeHealth(baseDir: string): Promise<{
 
 | Term | Path | Purpose |
 | --- | --- | --- |
-| **Worktree path** | `$GIT_COMMON_DIR/tbd/data-sync-worktree/.tbd/data-sync/` | **Production path** — inside hidden worktree checkout |
-| **Direct path** | `.tbd/data-sync/` | **Legacy fallback path** — gitignored on main, should NEVER contain data in production |
+| **Worktree path** | `$GIT_COMMON_DIR/tbd/data-sync-worktree/.tbd/data-sync/` | **Production path**—inside hidden worktree checkout |
+| **Direct path** | `.tbd/data-sync/` | **Legacy fallback path**—gitignored on main, should NEVER contain data in production |
 
 **Invariant:** In production, the worktree path is the ONLY correct path for issue data.
 The direct path exists ONLY for test fixtures that don’t use git.
@@ -1082,7 +1082,7 @@ async function resolveDataSyncDir(
 
 1. Production code MUST call `resolveDataSyncDir()` without `allowFallback`
 2. Only test code may use `allowFallback: true`
-3. If `.tbd/data-sync/issues/` contains data on main branch, this indicates a bug — data
+3. If `.tbd/data-sync/issues/` contains data on main branch, this indicates a bug—data
    was written to wrong location due to missing worktree
 
 #### Worktree Error Classes
@@ -1114,7 +1114,7 @@ export class SyncBranchError extends TbdError {
 Workspaces are directories under `.tbd/workspaces/` that store issue data for sync
 failure recovery, backups, and bulk editing workflows.
 
-> **Note:** `.tbd/workspaces/` must not be gitignored — outbox data must be committed to
+> **Note:** `.tbd/workspaces/` must not be gitignored—outbox data must be committed to
 > the working branch.
 
 #### Workspace Structure
@@ -2147,7 +2147,7 @@ SYNC(options):
 ```
 
 **Critical Invariant:** All operations in steps 1-6 MUST use the resolved `dataSyncDir`
-path consistently. Never read from or write to `.tbd/data-sync/` directly — always go
+path consistently. Never read from or write to `.tbd/data-sync/` directly—always go
 through the shared worktree at `$GIT_COMMON_DIR/tbd/data-sync-worktree/.tbd/data-sync/`.
 
 **Why most syncs are trivial (no merge needed):**
@@ -2290,7 +2290,7 @@ const issueMergeRules: MergeRules<Issue> = {
   created_by: { strategy: 'preserve_oldest' },
   closed_at: { strategy: 'lww' }, // See status/closed_at rules below
   close_reason: { strategy: 'lww' },
-  child_order_hints: { strategy: 'lww' }, // Soft ordering, LWW on concurrent edits
+  child_order_hints: { strategy: 'union' }, // Append-only set of child IDs; union (dedupe)
 };
 ```
 
@@ -2374,8 +2374,8 @@ The CLI Layer provides a Beads-compatible command interface.
 
 All tbd commands require the repository to be initialized, except:
 
-- `tbd init` — Creates a new tbd repository
-- `tbd import --from-beads` — Can initialize and import in one step (auto-runs init if
+- `tbd init`—Creates a new tbd repository
+- `tbd import --from-beads`—Can initialize and import in one step (auto-runs init if
   needed)
 
 **Behavior when not initialized:**
@@ -2572,8 +2572,8 @@ Options:
 created/updated: newest first).
 The tiebreaker for issues with equal primary values is the internal ULID, which sorts
 lexicographically in chronological creation order.
-This ensures deterministic, stable ordering — issues created earlier always appear
-before issues created later within the same priority level.
+This ensures deterministic, stable ordering—issues created earlier always appear before
+issues created later within the same priority level.
 
 **Examples:**
 
@@ -3498,9 +3498,9 @@ This follows the same convention as `git`, `ls`, `grep`, and other Unix tools.
 The actor name (used for `created_by` and recorded in sync commits) is resolved in this
 order:
 
-1. `--actor <name>` CLI flag (highest priority) — *not yet implemented*
+1. `--actor <name>` CLI flag (highest priority)—*not yet implemented*
 
-2. `TBD_ACTOR` environment variable — *not yet implemented*
+2. `TBD_ACTOR` environment variable—*not yet implemented*
 
 3. Git user.email from git config
 
@@ -4571,8 +4571,8 @@ all environments including cloud sandboxes.
 
 Claude Code hooks are always installed to the **project-local** `.claude/` directory,
 adjacent to `.git/` and `.tbd/` at the git repository root.
-There is no global/user-level installation — this avoids confusion and ensures hooks
-work in any environment (local dev, Claude Code Cloud, etc.).
+There is no global/user-level installation—this avoids confusion and ensures hooks work
+in any environment (local dev, Claude Code Cloud, etc.).
 
 **A. JSON Settings Hooks** (installed to `.claude/settings.json` at project root)
 
@@ -4674,7 +4674,7 @@ Options:
 - `tbd list --status=in_progress` - Your active work
 - `tbd show <id>` - Detailed issue view with dependencies
 
-### Creating & Updating
+### Creating and Updating
 - `tbd create "title" --type=task|bug|feature --priority=P2` - New issue
   - Priority: P0-P4 (P0=critical, P2=medium, P4=backlog)
 - `tbd update <id> --status=in_progress` - Claim work
@@ -4682,12 +4682,12 @@ Options:
 - `tbd close <id>` - Mark complete
 - `tbd close <id> --reason "explanation"` - Close with reason
 
-### Dependencies & Blocking
+### Dependencies and Blocking
 - `tbd dep add <issue> <depends-on>` - Add dependency
 - `tbd blocked` - Show all blocked issues
 - `tbd show <id>` - See what's blocking/blocked by this issue
 
-### Sync & Collaboration
+### Sync and Collaboration
 - `tbd sync` - Sync with git remote (run at session end)
 - `tbd sync --status` - Check sync status without syncing
 

package/dist/docs/tbd-docs.md

@@ -30,7 +30,7 @@ Why a separate branch?
 - No conflicts across main or feature branches
 - Issues shared across all branches
 
-## File format
+## File Format
 
 You usually don’t need to worry about where issues are stored, but it may be comforting
 to know that internally it’s very simple and transparent.

package/dist/docs/tbd-prime.md

@@ -52,7 +52,7 @@ Every session must end with tbd in a clean state:
 - `tbd show <id>` - Detailed issue view with dependencies
   - Auto-displays parent context for child issues (use `--no-parent` to suppress)
 
-### Creating & Updating
+### Creating and Updating
 
 - `tbd create "title" --type task|bug|feature --priority 2` - New issue
   - Priority: 0-4 (0=critical, 2=medium, 4=backlog).
@@ -63,13 +63,13 @@ Every session must end with tbd in a clean state:
 - `tbd close <id> --reason "explanation"` - Close with reason
 - **Tip**: When creating multiple issues, use parallel subagents for efficiency
 
-### Dependencies & Blocking
+### Dependencies and Blocking
 
 - `tbd dep add <issue> <depends-on>` - Add dependency (issue depends on depends-on)
 - `tbd blocked` - Show all blocked issues
 - `tbd show <id>` - See what’s blocking/blocked by this issue
 
-### Sync & Collaboration
+### Sync and Collaboration
 
 - `tbd sync` - Sync with git remote (run at session end)
 - `tbd sync --status` - Check sync status without syncing

package/dist/index.mjs

@@ -1,4 +1,4 @@
 import { A as Priority, C as IssueSchema, D as LocalStateSchema, E as LOCAL_STATE_FIELD_ORDER, F as Version, M as SyncStorage, N as Timestamp, O as META_FIELD_ORDER, P as Ulid, S as IssueKind, T as IssueTitle, _ as ISSUE_BODY_MAX_LENGTH, a as CONFIG_FIELD_ORDER, b as IdMappingYamlSchema, c as DATA_SYNC_SCHEMA_VERSION, d as DocCacheConfigSchema, f as DocsCacheSchema, g as GitRemoteName, h as GitBranchName, i as COMMON_DIR_LAYOUT_FIELD_ORDER, j as ShortId, k as MetaSchema, l as Dependency, m as ExternalIssueIdInput, n as AtticEntrySchema, o as CommonDirLayoutSchema, p as EntityType, r as BaseEntity, s as ConfigSchema, t as ATTIC_ENTRY_FIELD_ORDER, u as DependencyRelationType, v as ISSUE_FIELD_ORDER, w as IssueStatus, x as IssueId, y as ISSUE_TITLE_MAX_LENGTH } from "./schemas-f0EcuAVu.mjs";
-import { c as noopLogger, i as serializeIssue, n as parseIssue, t as VERSION } from "./src-CtZIHxYM.mjs";
+import { c as noopLogger, i as serializeIssue, n as parseIssue, t as VERSION } from "./src-DTyyuaG_.mjs";
 
 export { ATTIC_ENTRY_FIELD_ORDER, AtticEntrySchema, BaseEntity, COMMON_DIR_LAYOUT_FIELD_ORDER, CONFIG_FIELD_ORDER, CommonDirLayoutSchema, ConfigSchema, DATA_SYNC_SCHEMA_VERSION, Dependency, DependencyRelationType, DocCacheConfigSchema, DocsCacheSchema, EntityType, ExternalIssueIdInput, GitBranchName, GitRemoteName, ISSUE_BODY_MAX_LENGTH, ISSUE_FIELD_ORDER, ISSUE_TITLE_MAX_LENGTH, IdMappingYamlSchema, IssueId, IssueKind, IssueSchema, IssueStatus, IssueTitle, LOCAL_STATE_FIELD_ORDER, LocalStateSchema, META_FIELD_ORDER, MetaSchema, Priority, ShortId, SyncStorage, Timestamp, Ulid, VERSION, Version, noopLogger, parseIssue, serializeIssue };