get-tbd 0.1.21 → 0.1.23

package/dist/docs/tbd-design.md

@@ -77,6 +77,7 @@ agents.
     - [3.2 Sync Branch Architecture](#32-sync-branch-architecture)
       - [Files Tracked on Main Branch](#files-tracked-on-main-branch)
       - [.tbd/.gitignore Contents](#tbdgitignore-contents)
+      - [.tbd/.gitattributes Contents](#tbdgitattributes-contents)
       - [Files Tracked on tbd-sync Branch](#files-tracked-on-tbd-sync-branch)
     - [3.3 Sync Operations](#33-sync-operations)
       - [3.3.1 Reading from Sync Branch](#331-reading-from-sync-branch)
@@ -325,7 +326,7 @@ tbd and Beads serve different use cases:
 | Complex workflow orchestration | Molecules, wisps, formulas, bonding |
 | Need ephemeral work tracking | Wisps (never synced, squash to digest) |
 | High-performance queries on 10K+ issues | SQLite with indexes is faster than file scan |
-| Need automatic "memory decay" | AI-powered compaction of old issues |
+| Need automatic “memory decay” | AI-powered compaction of old issues |
 | Need interactive edit mode | `bd edit` opens in $EDITOR |
 
 **Key Differences Summary:**
@@ -424,7 +425,7 @@ tbd addresses specific requirements:
 | Git commit log noise | Issues stored on separate `tbd-sync` branch |
 | Synchronized state across Git branches | Always sync from the `tbd-sync` branch |
 | Git merging conflicts | One file per issue eliminates most merge conflicts |
-| Agent-friendly | Self-documenting, skill-compatible, non-interactive, simple commands |
+| Agent-friendly | Self-documenting, skill-compatible, simple commands |
 | Transparent formats | Issues internally are Markdown files with YAML frontmatter |
 | Reliable | Clear specs, golden testing of end-to-end use scenarios |
 
@@ -639,6 +640,24 @@ serialization:
 .tbd/data-sync/** text eol=lf
 ```
 
+**Required `.tbd/.gitattributes`** (created by `tbd setup`):
+
+```gitattributes
+# Protect ID mappings from merge deletion (always keep all rows)
+# See: https://github.com/jlevy/tbd/issues/99
+**/mappings/ids.yml merge=union
+```
+
+> **Why `merge=union`?** Git 3-way merge can delete `ids.yml` when merging a feature
+> branch back to main, because main has no outbox directory and the merge treats “no
+> file” as the correct state.
+> The `merge=union` strategy keeps all lines from both sides, which is safe for
+> `ids.yml` since it’s an append-only mapping.
+> Duplicate keys (if any) are tolerated by the YAML parser and auto-fixed on next save.
+> This file is placed inside `.tbd/` so all tbd settings are self-contained in one
+> directory. Git supports `.gitattributes` in subdirectories with paths relative to that
+> 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)
@@ -712,6 +731,7 @@ tbd uses three directory locations:
 │ Committed to the repo:
 ├── config.yml              # Project configuration
 ├── .gitignore              # Controls what's gitignored below
+├── .gitattributes          # Merge strategies (merge=union for ids.yml)
 ├── workspaces/             # Persistent state (outbox, named workspaces)
 │   ├── outbox/             # Sync failure recovery workspace
 │   │   ├── issues/
@@ -848,6 +868,27 @@ backups/
 > **Note:** `workspaces/` must not be gitignored — it stores outbox data that must be
 > committed to the working branch.
 
+#### .tbd/.gitattributes Contents
+
+The `.tbd/.gitattributes` file configures merge strategies for tbd files.
+It is placed inside `.tbd/` (not at the repo root) so all tbd settings are
+self-contained. Git supports `.gitattributes` in subdirectories with paths relative to
+that directory.
+
+```gitattributes
+# Protect ID mappings from merge deletion (always keep all rows)
+# See: https://github.com/jlevy/tbd/issues/99
+**/mappings/ids.yml merge=union
+```
+
+> **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
+> “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
+> row deletion. Duplicate YAML keys (if any) are tolerated by the parser and auto-fixed
+> on next save. See [#99](https://github.com/jlevy/tbd/issues/99) for details.
+
 #### Accessing Issues via Worktree
 
 ```bash
@@ -917,7 +958,7 @@ The worktree can be in one of four states, detected by `checkWorktreeHealth()`:
 | State | Description | Detection | Recovery |
 | --- | --- | --- | --- |
 | `valid` | Healthy, ready to use | Directory exists, `.git` file valid, not prunable | None needed |
-| `missing` | Directory doesn't exist | `!exists(.tbd/data-sync-worktree/)` | Create from local or remote branch |
+| `missing` | Directory doesn’t exist | `!exists(.tbd/data-sync-worktree/)` | Create from local or remote branch |
 | `prunable` | Directory deleted but git still tracks it | `git worktree list --porcelain` shows prunable | `git worktree prune`, then recreate |
 | `corrupted` | Directory exists but invalid | Missing `.git` file or invalid gitdir pointer | **Backup to .tbd/backups/**, then recreate |
 
@@ -1760,9 +1801,9 @@ dependencies:
 
 | Type | Affects Ready? | Use Case |
 | --- | --- | --- |
-| `blocks` | **Yes** | "This issue must close before target can proceed" |
-| `related` | No | Soft link: "See also" references (future) |
-| `discovered-from` | No | Provenance: "Found while working on X" (future) |
+| `blocks` | **Yes** | “This issue must close before target can proceed” |
+| `related` | No | Soft link: “See also” references (future) |
+| `discovered-from` | No | Provenance: “Found while working on X” (future) |
 
 **Commands:**
 
@@ -1797,7 +1838,7 @@ tbd and Beads have different models for parent-child relationships:
 | Aspect | tbd | Beads |
 | --- | --- | --- |
 | Parent-child storage | `parent_id` field | `dependencies[].type: parent-child` |
-| Parent-child blocking | **No** (organizational only) | **Transitive** (inherits parent's blocked state) |
+| Parent-child blocking | **No** (organizational only) | **Transitive** (inherits parent’s blocked state) |
 | Dependency types | `blocks` only (more planned) | `blocks`, `parent-child`, `related`, `discovered-from`, + more |
 
 **Understanding Beads’ parent-child behavior:**
@@ -1935,9 +1976,10 @@ main branch:                    tbd-sync branch:
 ├── tests/                          └── data-sync/
 ├── README.md                           ├── issues/
 ├── .tbd/                               ├── attic/
-│   ├── config.yml  (committed)         └── meta.yml
-│   ├── .gitignore  (committed)
-│   ├── workspaces/ (committed)
+│   ├── config.yml      (committed)     └── meta.yml
+│   ├── .gitignore      (committed)
+│   ├── .gitattributes  (committed)
+│   ├── workspaces/     (committed)
 │   ├── state.yml   (gitignored)
 │   ├── docs/       (gitignored)
 │   └── data-sync-worktree/ (gitignored)
@@ -1960,6 +2002,7 @@ main branch:                    tbd-sync branch:
 ```
 .tbd/config.yml       # Project configuration (YAML)
 .tbd/.gitignore       # Controls what's gitignored below
+.tbd/.gitattributes   # Merge strategies (merge=union for ids.yml)
 .tbd/workspaces/      # Persistent state (outbox, named workspaces)
 ```
 
@@ -2324,14 +2367,14 @@ If `.tbd/config.yml` does not exist or is invalid, commands exit with an error:
 | `init` | No | Creates `.tbd/` directory and sync branch |
 | `status` | No | Shows detection results and guidance (see §4.9) |
 | `import --from-beads` | No | Auto-initializes, then imports |
-| `import <file>` | Yes | Error: "Not a tbd repository" |
-| `list`, `show`, `stats` | Yes | Error: "Not a tbd repository" |
-| `create`, `update`, `close`, `reopen` | Yes | Error: "Not a tbd repository" |
-| `ready`, `blocked`, `stale` | Yes | Error: "Not a tbd repository" |
-| `label`, `dep` | Yes | Error: "Not a tbd repository" |
-| `sync`, `search`, `doctor`, `config` | Yes | Error: "Not a tbd repository" |
-| `attic list/show/restore` | Yes | Error: "Not a tbd repository" |
-| All other commands | Yes | Error: "Not a tbd repository" |
+| `import <file>` | Yes | Error: “Not a tbd repository” |
+| `list`, `show`, `stats` | Yes | Error: “Not a tbd repository” |
+| `create`, `update`, `close`, `reopen` | Yes | Error: “Not a tbd repository” |
+| `ready`, `blocked`, `stale` | Yes | Error: “Not a tbd repository” |
+| `label`, `dep` | Yes | Error: “Not a tbd repository” |
+| `sync`, `search`, `doctor`, `config` | Yes | Error: “Not a tbd repository” |
+| `attic list/show/restore` | Yes | Error: “Not a tbd repository” |
+| All other commands | Yes | Error: “Not a tbd repository” |
 
 **`import --from-beads` auto-initialization:**
 
@@ -2382,8 +2425,8 @@ repository (which automatically detects and uses the beads prefix).
 
 **What it does:**
 
-1. Creates `.tbd/` directory with `config.yml` (including display.id_prefix) and
-   `.gitignore`
+1. Creates `.tbd/` directory with `config.yml` (including display.id_prefix),
+   `.gitignore`, and `.gitattributes` (merge=union for ids.yml)
 
 2. Creates `.tbd/docs/` directories for shortcuts, guidelines, templates (gitignored)
 
@@ -2403,7 +2446,7 @@ Created sync branch: tbd-sync
 Pushed sync branch to origin
 
 To complete setup, commit the config files:
-  git add .tbd/config.yml .tbd/.gitignore
+  git add .tbd/config.yml .tbd/.gitignore .tbd/.gitattributes
   git commit -m "Initialize tbd"
 ```
 
@@ -3251,7 +3294,7 @@ The doctor command performs comprehensive health checks organized into categorie
 
 | Check | Severity | Auto-fixable | Detection |
 | --- | --- | --- | --- |
-| Worktree missing | error | yes | Directory doesn't exist |
+| Worktree missing | error | yes | Directory doesn’t exist |
 | Worktree prunable | error | yes | `git worktree list` shows prunable |
 | Worktree corrupted | error | yes | Missing `.git` file or invalid gitdir |
 
@@ -3259,8 +3302,8 @@ The doctor command performs comprehensive health checks organized into categorie
 
 | Check | Severity | Auto-fixable | Detection |
 | --- | --- | --- | --- |
-| Local branch missing | error | yes | `refs/heads/tbd-sync` doesn't exist |
-| Remote branch missing | warning | no | `refs/remotes/origin/tbd-sync` doesn't exist |
+| Local branch missing | error | yes | `refs/heads/tbd-sync` doesn’t exist |
+| Remote branch missing | warning | no | `refs/remotes/origin/tbd-sync` doesn’t exist |
 | Local/remote diverged | warning | no | `git merge-base` != either HEAD |
 
 **3. Sync State Consistency Check**
@@ -3285,7 +3328,7 @@ Only runs if worktree is healthy:
 | Check | Severity | Auto-fixable | Detection |
 | --- | --- | --- | --- |
 | Schema version incompatible | error | no | `meta.yml` version > supported |
-| Orphaned dependencies | warning | yes | Dependency target doesn't exist |
+| Orphaned dependencies | warning | yes | Dependency target doesn’t exist |
 | Duplicate IDs | error | yes | Multiple files with same short ID |
 | Invalid references | warning | yes | `parent_id` points to missing issue |
 
@@ -3379,8 +3422,6 @@ Available on all commands:
 --verbose                   Enable verbose output
 --quiet                     Suppress non-essential output
 --debug                     Show internal IDs alongside public IDs for debugging
---non-interactive           Disable all prompts, fail if input required
---yes                       Assume yes to confirmation prompts
 ```
 
 **Color Output:**
@@ -3420,16 +3461,7 @@ Example: `TBD_ACTOR=claude-agent-1 tbd create "Fix bug"`
 
 **Agent/Automation Flags:**
 
-These options enable non-interactive use in CI/CD pipelines and by AI agents:
-
-- `--non-interactive`: Disables all interactive prompts.
-  Commands that require user input will fail with an error instead of blocking.
-  Automatically enabled when `CI` environment variable is set or when stdin is not a
-  TTY.
-
-- `--yes`: Automatically answers “yes” to confirmation prompts.
-  Useful for batch operations or scripts.
-  Does not bypass `--non-interactive`—combine both for fully automated execution.
+These options enable automation in CI/CD pipelines and by AI agents:
 
 - `--dry-run`: Shows what changes would be made without actually making them.
   Essential for verifying agent-planned operations before execution.
@@ -3444,14 +3476,14 @@ These options enable non-interactive use in CI/CD pipelines and by AI agents:
 Example agent workflow:
 
 ```bash
-# CI pipeline: create issue non-interactively
+# CI pipeline: create issue with JSON output
 CI=1 tbd create "Deploy failed" --kind bug --priority=P2 --json
 
 # Agent: preview changes before committing
 tbd update td-abc1 --status done --dry-run --json
 
 # Batch script: close multiple issues
-tbd close td-abc1 td-abc2 td-abc3 --yes --quiet
+tbd close td-abc1 td-abc2 td-abc3 --quiet
 ```
 
 ### 4.11 Attic Commands
@@ -3972,7 +4004,7 @@ On import:
 
 | Beads Status | tbd Behavior | Rationale |
 | --- | --- | --- |
-| `tombstone` (first import) | Skip by default | Don't import deleted issues |
+| `tombstone` (first import) | Skip by default | Don’t import deleted issues |
 | `tombstone` (re-import) | Set `status: closed`, add label `deleted-in-beads` | Preserve history |
 
 **Options:**
@@ -4104,7 +4136,7 @@ tbd sync
 | `bd label add` | `tbd label add` | ✅ Full | Identical |
 | `bd label remove` | `tbd label remove` | ✅ Full | Identical |
 | `bd label list` | `tbd label list` | ✅ Full | Lists all labels |
-| `bd dep add` | `tbd dep add` | ✅ Full | Only "blocks" type |
+| `bd dep add` | `tbd dep add` | ✅ Full | Only “blocks” type |
 | `bd dep tree` | `tbd dep tree` | 🔄 Future | Visualize dependencies |
 | `bd sync` | `tbd sync` | ✅ Full | Different mechanism, same UX |
 | `bd stats` | `tbd stats` | ✅ Full | Same statistics |
@@ -4140,7 +4172,7 @@ tbd sync
 | `priority` | `priority` | Identical (0-4) |
 | `assignee` | `assignee` | Identical |
 | `labels` | `labels` | Identical |
-| `dependencies` | `dependencies` | Only "blocks" type currently |
+| `dependencies` | `dependencies` | Only “blocks” type currently |
 | `created_at` | `created_at` | Identical |
 | `updated_at` | `updated_at` | Identical |
 | `closed_at` | `closed_at` | Identical |
@@ -5093,6 +5125,7 @@ repo/
 │   │ Committed to the repo:
 │   ├── config.yml                  # Project config
 │   ├── .gitignore                  # Controls what's gitignored below
+│   ├── .gitattributes              # Merge strategies (merge=union for ids.yml)
 │   ├── workspaces/                 # Persistent state (outbox, named workspaces)
 │   │
 │   │ Gitignored (local only):
@@ -5119,7 +5152,7 @@ repo/
 
 | Location | Files | Size |
 | --- | --- | --- |
-| `.tbd/` | 3 | <1 KB |
+| `.tbd/` | 4 | <1 KB |
 | `.tbd/docs/` | ~30 | ~100 KB |
 | `.tbd/data-sync/issues/` | 1,000 | ~2 MB |
 | `.tbd/data-sync/attic/` | 10-50 | <100 KB |
@@ -5255,8 +5288,6 @@ This is sufficient for the `ready` command algorithm.
 | *(n/a)* | `--dry-run` | ✅ tbd | Preview changes |
 | *(n/a)* | `--verbose` | ✅ tbd | Debug output |
 | *(n/a)* | `--quiet` | ✅ tbd | Minimal output |
-| *(n/a)* | `--non-interactive` | ✅ tbd | Agent/CI mode |
-| *(n/a)* | `--yes` | ✅ tbd | Auto-confirm |
 | *(n/a)* | `--color <when>` | ✅ tbd | Color control |
 
 ### A.3 Data Model Mapping
@@ -5594,7 +5625,7 @@ See [§2.7.5](#275-comparison-with-beads) for details.
 | `--no-daemon` | No daemon to disable |
 | `--no-auto-flush` | No auto-flush mechanism |
 | `--no-auto-import` | Different sync model |
-| `--sandbox` | tbd is always "sandbox safe" |
+| `--sandbox` | tbd is always “sandbox safe” |
 | `--allow-stale` | Different staleness model |
 
 ### B.11 Issue Types/Statuses Not Supported
@@ -5707,6 +5738,15 @@ never conflicts with existing ones.
 Concurrent imports with the same source would produce identical mappings (idempotent).
 Concurrent imports from different sources have distinct short IDs (no conflict).
 
+**Additional protection** (added in response to
+[#99](https://github.com/jlevy/tbd/issues/99)): `.tbd/.gitattributes` configures
+`merge=union` for all `ids.yml` files, preventing git from deleting rows during merge.
+The sync code also includes `reconcileMappings()` which detects missing mappings after
+merge and recovers original short IDs from git history before falling back to new random
+IDs. The `doctor --fix` command provides a manual recovery path.
+Together these provide three layers of defense: prevention (`.gitattributes`), detection
+and recovery (reconcileMappings), and manual repair (doctor).
+
 ### 8.4 ID Length
 
 **RESOLVED**: Adopted ULID-based internal IDs.

package/dist/docs/tbd-docs.md

@@ -729,8 +729,6 @@ tbd list --verbose                          # Enable verbose output
 tbd create "Test" --dry-run                 # Show what would happen
 tbd close proj-a7k2 --no-sync                 # Skip automatic sync
 tbd list --debug                            # Show internal IDs
-tbd update proj-a7k2 --yes                    # Assume yes to prompts
-tbd list --non-interactive                  # Fail if input required
 tbd list --color=never                      # Disable colors
 ```
 
@@ -741,8 +739,6 @@ Options:
 - `--quiet` - Suppress non-essential output
 - `--json` - Output as JSON
 - `--color <when>` - Colorize output: auto, always, never
-- `--non-interactive` - Disable all prompts, fail if input required
-- `--yes` - Assume yes to confirmation prompts
 - `--no-sync` - Skip automatic sync after write operations
 - `--debug` - Show internal IDs alongside display IDs
 
@@ -766,8 +762,6 @@ tbd sync                                    # Push changes
 | Flag | Purpose |
 | --- | --- |
 | `--json` | Machine-parseable output |
-| `--non-interactive` | Fail if input required (auto-enabled in CI) |
-| `--yes` | Auto-confirm prompts |
 | `--dry-run` | Preview changes before applying |
 | `--quiet` | Suppress informational output |
 

package/dist/id-mapping-0-R0X8zb.mjs

@@ -0,0 +1,3 @@
+import { a as hasShortId, c as parseIdMappingFromYaml, d 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 resolveToInternalId } from "./id-mapping-JGow6Jk4.mjs";
+
+export { loadIdMapping, parseIdMappingFromYaml, reconcileMappings, saveIdMapping };

package/dist/{id-mapping-CD5c_ZVA.mjs → id-mapping-JGow6Jk4.mjs}

@@ -1,4 +1,4 @@
-import { T as IdMappingYamlSchema, a as stringifyYaml, n as parseYamlToleratingDuplicateKeys } from "./yaml-utils-x_kr2IId.mjs";
+import { T as IdMappingYamlSchema, a as stringifyYaml, n as parseYamlToleratingDuplicateKeys } from "./yaml-utils-U7l9hhkh.mjs";
 import { mkdir, readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { writeFile } from "atomically";
@@ -374,6 +374,22 @@ function hasShortId(mapping, shortId) {
 	return mapping.shortToUlid.has(shortId);
 }
 /**
+* Create a short ID mapping for a new internal ID.
+* Generates a unique short ID and registers it in the mapping.
+*
+* @param internalId - The internal ID (is-{ulid})
+* @param mapping - The ID mapping to update
+* @returns The generated short ID
+*/
+function createShortIdMapping(internalId, mapping) {
+	const ulid = extractUlidFromInternalId(internalId);
+	const existing = mapping.ulidToShort.get(ulid);
+	if (existing) return existing;
+	const shortId = generateUniqueShortId(mapping);
+	addIdMapping(mapping, ulid, shortId);
+	return shortId;
+}
+/**
 * Resolve any ID input to an internal ID ({prefix}-{ulid}).
 *
 * Handles:
@@ -420,6 +436,44 @@ function parseIdMappingFromYaml(content) {
 	};
 }
 /**
+* Ensure all given internal IDs have short ID mappings.
+* Creates missing mappings for any IDs without entries.
+*
+* This repairs state after git merges that may add issue files
+* without corresponding mapping entries (e.g., when outbox issues
+* are merged from a feature branch but ids.yml doesn't include them).
+*
+* When a `historicalMapping` is provided, the function will try to recover
+* the original short ID from that mapping before generating a new random one.
+* This preserves ID stability so that existing references (in docs, PRs,
+* conversations) remain valid.
+*
+* @param internalIds - Array of internal IDs (is-{ulid}) to reconcile
+* @param mapping - The ID mapping to update (mutated in-place)
+* @param historicalMapping - Optional mapping from prior state (e.g., git history) to recover original short IDs
+* @returns Object with `created` (IDs that got new random short IDs) and `recovered` (IDs restored from history)
+*/
+function reconcileMappings(internalIds, mapping, historicalMapping) {
+	const created = [];
+	const recovered = [];
+	for (const id of internalIds) {
+		const ulid = extractUlidFromInternalId(id);
+		if (mapping.ulidToShort.has(ulid)) continue;
+		const historicalShortId = historicalMapping?.ulidToShort.get(ulid);
+		if (historicalShortId && !mapping.shortToUlid.has(historicalShortId)) {
+			addIdMapping(mapping, ulid, historicalShortId);
+			recovered.push(id);
+		} else {
+			createShortIdMapping(id, mapping);
+			created.push(id);
+		}
+	}
+	return {
+		created,
+		recovered
+	};
+}
+/**
 * Merge two ID mappings by combining all entries from both.
 * ID mappings are always additive (new IDs are only added, never removed),
 * so merging simply unions all key-value pairs.
@@ -448,5 +502,5 @@ function mergeIdMappings(local, remote) {
 }
 
 //#endregion
-export { normalizeIssueId as _, loadIdMapping as a, resolveToInternalId as c, extractShortId as d, extractUlidFromInternalId as f, makeInternalId as g, generateInternalId as h, hasShortId as i, saveIdMapping as l, formatDisplayId as m, calculateOptimalLength as n, mergeIdMappings as o, formatDebugId as p, generateUniqueShortId as r, parseIdMappingFromYaml as s, addIdMapping as t, extractPrefix as u, validateIssueId as v };
-//# sourceMappingURL=id-mapping-CD5c_ZVA.mjs.map
+export { generateInternalId as _, hasShortId as a, validateIssueId as b, parseIdMappingFromYaml as c, saveIdMapping as d, extractPrefix as f, formatDisplayId as g, formatDebugId as h, generateUniqueShortId as i, reconcileMappings as l, extractUlidFromInternalId as m, calculateOptimalLength as n, loadIdMapping as o, extractShortId as p, createShortIdMapping as r, mergeIdMappings as s, addIdMapping as t, resolveToInternalId as u, makeInternalId as v, normalizeIssueId as y };
+//# sourceMappingURL=id-mapping-JGow6Jk4.mjs.map

package/dist/{id-mapping-CD5c_ZVA.mjs.map → id-mapping-JGow6Jk4.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"id-mapping-CD5c_ZVA.mjs","names":[],"sources":["../src/lib/ids.ts","../src/lib/sort.ts","../src/file/id-mapping.ts"],"sourcesContent":["/**\n * ID generation and validation utilities.\n *\n * The system uses dual IDs for usability:\n * - Internal ID: is-{ulid} - ULID-based (26 lowercase chars), stored in files\n * - External ID: {prefix}-{short} - 4-5 base36 chars for CLI display/input\n *\n * For Beads compatibility, bd- prefix is accepted on input for external IDs.\n *\n * See: tbd-design.md §2.5 ID Generation\n */\n\nimport { monotonicFactory } from 'ulid';\nimport { randomBytes } from 'node:crypto';\n\n// Monotonic factory ensures ULIDs are strictly increasing even within the same\n// millisecond. This guarantees that lexicographic sort = creation order, which\n// is critical for deterministic list output (the tiebreaker sort is by ULID).\nconst ulid = monotonicFactory();\n\n// =============================================================================\n// Branded Types for Type-Safe ID Handling\n// =============================================================================\n\n/**\n * Branded type for internal issue IDs (is-{ulid} format).\n *\n * Internal IDs are stored in files and used as the canonical identifier.\n * Format: is-{26 lowercase alphanumeric chars}\n * Example: is-01hx5zzkbkactav9wevgemmvrz\n *\n * Use this type when:\n * - Reading/writing issue files\n * - Storing parent_id, dependencies, child_order_hints\n * - Passing IDs between internal functions\n */\ndeclare const InternalIssueIdBrand: unique symbol;\nexport type InternalIssueId = string & { [InternalIssueIdBrand]: never };\n\n/**\n * Branded type for display issue IDs ({prefix}-{short} format).\n *\n * Display IDs are shown to users and accepted as CLI input.\n * Format: {prefix}-{short} where short is typically 4 base36 chars\n * Example: tbd-a7k2, bd-100\n *\n * Use this type when:\n * - Formatting output for users\n * - Accepting user input (before resolution)\n * - Building tree views for display\n */\ndeclare const DisplayIssueIdBrand: unique symbol;\nexport type DisplayIssueId = string & { [DisplayIssueIdBrand]: never };\n\n/**\n * Cast a string to InternalIssueId after validation.\n * Use this when you've validated that a string is a valid internal ID.\n */\nexport function asInternalId(id: string): InternalIssueId {\n  return id as InternalIssueId;\n}\n\n/**\n * Cast a string to DisplayIssueId.\n * Use this when formatting an ID for display.\n */\nexport function asDisplayId(id: string): DisplayIssueId {\n  return id as DisplayIssueId;\n}\n\n/**\n * Prefix for internal IDs (ULID-based).\n * All internal IDs are formatted as: {INTERNAL_ID_PREFIX}-{ulid}\n */\nexport const INTERNAL_ID_PREFIX = 'is';\n\n/**\n * Length of internal ID prefix including the hyphen (e.g., \"is-\" = 3).\n */\nexport const INTERNAL_ID_PREFIX_LENGTH = INTERNAL_ID_PREFIX.length + 1;\n\n/**\n * Construct an internal ID from a ULID.\n *\n * @param ulidValue - The ULID (26 chars)\n * @returns Internal ID in format {prefix}-{ulid}\n */\nexport function makeInternalId(ulidValue: string): InternalIssueId {\n  return `${INTERNAL_ID_PREFIX}-${ulidValue.toLowerCase()}` as InternalIssueId;\n}\n\n/**\n * Generate a unique internal ID using ULID.\n * Format: is-{ulid} (26 lowercase alphanumeric chars)\n * Example: is-01hx5zzkbkactav9wevgemmvrz\n *\n * ULID provides:\n * - Time-ordered sorting (48-bit timestamp)\n * - 80-bit randomness (no collisions)\n * - Lexicographic sort = chronological order\n */\nexport function generateInternalId(): InternalIssueId {\n  return makeInternalId(ulid());\n}\n\n/**\n * Generate a short ID for external display.\n * Format: base36 characters (a-z, 0-9)\n * Example: a7k2\n *\n * @param length - Number of characters (default 4)\n */\nexport function generateShortId(length = 4): string {\n  const chars = '0123456789abcdefghijklmnopqrstuvwxyz';\n  let result = '';\n  const bytes = randomBytes(length);\n  for (let i = 0; i < length; i++) {\n    result += chars[bytes[i]! % 36];\n  }\n  return result;\n}\n\n// Regex pattern for validating internal IDs - built from prefix constant\nconst INTERNAL_ID_PATTERN = new RegExp(`^${INTERNAL_ID_PREFIX}-[0-9a-z]{26}$`);\n\n// Expected length of a full internal ID (prefix + hyphen + 26-char ULID)\nconst INTERNAL_ID_LENGTH = INTERNAL_ID_PREFIX_LENGTH + 26;\n\n/**\n * Validate an internal issue ID matches the ULID format.\n * Format: {prefix}-{26 lowercase alphanumeric chars}\n */\nexport function validateIssueId(id: string): boolean {\n  return INTERNAL_ID_PATTERN.test(id);\n}\n\n/**\n * Validate a short/external ID format.\n * Format: 1+ base36 characters (typically 4 for new IDs, but imports may preserve longer IDs).\n */\nexport function validateShortId(id: string): boolean {\n  return /^[0-9a-z]+$/.test(id);\n}\n\n/**\n * Check if an input looks like an internal ID (ULID-based).\n */\nexport function isInternalId(input: string): boolean {\n  const lower = input.toLowerCase();\n  // Check if it starts with the internal prefix and has correct length\n  const prefixWithHyphen = `${INTERNAL_ID_PREFIX}-`;\n  if (lower.startsWith(prefixWithHyphen) && lower.length === INTERNAL_ID_LENGTH) {\n    return INTERNAL_ID_PATTERN.test(lower);\n  }\n  return false;\n}\n\n/**\n * Check if an input looks like a short/external ID.\n * Returns true for IDs like \"a7k2\", \"bd-a7k2\", \"100\", \"tbd-100\".\n * Short IDs are 16 characters or less (ULIDs are 26 characters).\n */\nexport function isShortId(input: string): boolean {\n  const lower = input.toLowerCase();\n  // Strip prefix if present\n  const stripped = lower.replace(/^[a-z]+-/, '');\n  // Must be 1-16 alphanumeric chars (short IDs, not ULIDs which are 26 chars)\n  return /^[0-9a-z]+$/.test(stripped) && stripped.length >= 1 && stripped.length <= 16;\n}\n\n/**\n * Extract the short ID portion from an external ID.\n * Examples:\n *   \"tbd-100\" -> \"100\"\n *   \"bd-a7k2\" -> \"a7k2\"\n *   \"a7k2\" -> \"a7k2\"\n *   \"100\" -> \"100\"\n */\nexport function extractShortId(externalId: string): string {\n  return externalId.toLowerCase().replace(/^[a-z]+-/, '');\n}\n\n/**\n * Extract the prefix portion from an external ID.\n * Returns the prefix (letters before the hyphen) or null if no prefix found.\n * Examples:\n *   \"tbd-100\" -> \"tbd\"\n *   \"bd-a7k2\" -> \"bd\"\n *   \"TBD-100\" -> \"tbd\" (normalized to lowercase)\n *   \"a7k2\" -> null (no prefix)\n *   \"100\" -> null (no prefix)\n */\nexport function extractPrefix(externalId: string): string | null {\n  const match = /^([a-zA-Z]+)-/.exec(externalId);\n  return match?.[1]?.toLowerCase() ?? null;\n}\n\n/**\n * Extract the ULID portion from an internal ID.\n *\n * Internal IDs have the format: {prefix}-{ulid}\n * This function strips any prefix to return just the ULID.\n *\n * Examples:\n *   \"is-01hx5zzkbkactav9wevgemmvrz\" -> \"01hx5zzkbkactav9wevgemmvrz\"\n *   \"01hx5zzkbkactav9wevgemmvrz\" -> \"01hx5zzkbkactav9wevgemmvrz\" (no prefix)\n *\n * @param internalId - The internal ID (with or without prefix)\n * @returns The ULID portion without any prefix\n */\nexport function extractUlidFromInternalId(internalId: string): string {\n  // Strip any prefix in format {letters}- (e.g., \"is-\", \"bd-\")\n  return internalId.toLowerCase().replace(/^[a-z]+-/, '');\n}\n\n/** Prefix used in Beads for compatibility */\nconst BEADS_COMPAT_PREFIX = 'bd';\n\n/**\n * Normalize an internal issue ID.\n *\n * This function expects a full internal ID ({prefix}-{ulid}).\n * If given a short ID, it won't be able to resolve it without\n * access to the ID mapping.\n *\n * Handles:\n * - Uppercase (converts to lowercase)\n * - Ensures internal ID prefix\n * - Beads compatibility (bd- prefix)\n */\nexport function normalizeIssueId(input: string): string {\n  const lower = input.toLowerCase();\n  const internalPrefixWithHyphen = `${INTERNAL_ID_PREFIX}-`;\n  const beadsPrefixWithHyphen = `${BEADS_COMPAT_PREFIX}-`;\n\n  // If already a valid internal ID, return as-is\n  if (validateIssueId(lower)) {\n    return lower;\n  }\n\n  // If it starts with internal prefix but wrong length, might be corrupted\n  if (lower.startsWith(internalPrefixWithHyphen)) {\n    return lower; // Return as-is, let validation fail later\n  }\n\n  // If it starts with bd- (Beads compat), convert prefix\n  if (lower.startsWith(beadsPrefixWithHyphen)) {\n    const rest = lower.slice(beadsPrefixWithHyphen.length);\n    if (rest.length === 26) {\n      return makeInternalId(rest);\n    }\n    // Short ID - can't resolve without mapping\n    return lower;\n  }\n\n  // Bare ID without prefix\n  if (lower.length === 26 && /^[0-9a-z]{26}$/.test(lower)) {\n    return makeInternalId(lower);\n  }\n\n  // Can't normalize - return as-is\n  return lower;\n}\n\nimport type { IdMapping } from '../file/id-mapping.js';\n\n/**\n * Format an internal ID for display with the configured prefix.\n *\n * Uses the short ID (4 chars) from the mapping.\n * Throws an error if the mapping is missing or doesn't contain the ID.\n *\n * IMPORTANT: All user-facing output MUST use short IDs, never internal ULIDs.\n * If you see a ULID in user output, it's a bug.\n *\n * @param internalId - The internal ID (is-{ulid})\n * @param mapping - ID mapping for short ID lookup (required)\n * @param prefix - Display prefix (should come from config.display.id_prefix; defaults to 'tbd' as fallback)\n * @throws Error if mapping is missing or ID not found in mapping\n */\nexport function formatDisplayId(\n  internalId: InternalIssueId | string,\n  mapping: IdMapping,\n  prefix = 'tbd',\n): DisplayIssueId {\n  // Extract the ULID portion\n  const ulidPart = extractUlidFromInternalId(internalId);\n\n  // Get short ID from mapping\n  const shortId = mapping.ulidToShort.get(ulidPart);\n  if (!shortId) {\n    throw new Error(\n      `No short ID mapping found for internal ID: ${internalId}. ` +\n        `This is a bug - all issues must have a short ID mapping.`,\n    );\n  }\n\n  return `${prefix}-${shortId}` as DisplayIssueId;\n}\n\n/**\n * Format an ID for debug output, showing both public and internal IDs.\n *\n * @param internalId - The internal ID (is-{ulid})\n * @param mapping - ID mapping for short ID lookup\n * @param prefix - Display prefix (should come from config.display.id_prefix; defaults to 'tbd' as fallback)\n */\nexport function formatDebugId(\n  internalId: InternalIssueId | string,\n  mapping: IdMapping,\n  prefix = 'tbd',\n): string {\n  const displayId = formatDisplayId(internalId, mapping, prefix);\n  return `${displayId} (${internalId})`;\n}\n","/**\n * Natural sort utilities.\n *\n * Provides alphanumeric sorting where numeric portions are sorted numerically.\n * Similar to `sort -V` (version sort) or `sort -n` for numbers.\n *\n * Examples:\n *   [\"1\", \"2\", \"9\", \"10\", \"11\"] instead of [\"1\", \"10\", \"11\", \"2\", \"9\"]\n *   [\"a1\", \"a2\", \"a10\"] instead of [\"a1\", \"a10\", \"a2\"]\n *   [\"file1.txt\", \"file2.txt\", \"file10.txt\"] instead of [\"file1.txt\", \"file10.txt\", \"file2.txt\"]\n */\n\n/**\n * Split a string into alternating runs of digits and non-digits.\n * @param str - The string to split\n * @returns Array of [isNumeric, value] tuples\n */\nfunction splitIntoChunks(str: string): [boolean, string][] {\n  const chunks: [boolean, string][] = [];\n  let current = '';\n  let currentIsNumeric: boolean | null = null;\n\n  for (const char of str) {\n    const isDigit = char >= '0' && char <= '9';\n\n    if (currentIsNumeric === null) {\n      // First character\n      currentIsNumeric = isDigit;\n      current = char;\n    } else if (isDigit === currentIsNumeric) {\n      // Same type, continue accumulating\n      current += char;\n    } else {\n      // Type changed, push current chunk and start new one\n      chunks.push([currentIsNumeric, current]);\n      currentIsNumeric = isDigit;\n      current = char;\n    }\n  }\n\n  // Push final chunk\n  if (current) {\n    chunks.push([currentIsNumeric!, current]);\n  }\n\n  return chunks;\n}\n\n/**\n * Compare two strings using natural (alphanumeric) ordering.\n *\n * Numeric portions are compared numerically, non-numeric portions are\n * compared lexicographically (case-insensitive). Numbers sort before letters\n * when they appear at the same position in mixed comparisons, matching\n * the behavior of `sort -V` (version sort).\n *\n * @param a - First string\n * @param b - Second string\n * @returns Negative if a < b, positive if a > b, zero if equal\n */\nexport function naturalCompare(a: string, b: string): number {\n  // Handle empty strings\n  if (!a && !b) return 0;\n  if (!a) return -1;\n  if (!b) return 1;\n\n  const chunksA = splitIntoChunks(a);\n  const chunksB = splitIntoChunks(b);\n\n  const minLen = Math.min(chunksA.length, chunksB.length);\n\n  for (let i = 0; i < minLen; i++) {\n    const [isNumericA, valueA] = chunksA[i]!;\n    const [isNumericB, valueB] = chunksB[i]!;\n\n    if (isNumericA && isNumericB) {\n      // Both are numeric - compare as numbers\n      const numA = parseInt(valueA, 10);\n      const numB = parseInt(valueB, 10);\n      if (numA !== numB) {\n        return numA - numB;\n      }\n      // If numerically equal but different strings (e.g., \"01\" vs \"1\"),\n      // prefer shorter (fewer leading zeros)\n      if (valueA.length !== valueB.length) {\n        return valueA.length - valueB.length;\n      }\n    } else if (!isNumericA && !isNumericB) {\n      // Both are non-numeric - compare lexicographically (case-insensitive)\n      const lowerA = valueA.toLowerCase();\n      const lowerB = valueB.toLowerCase();\n      if (lowerA !== lowerB) {\n        return lowerA.localeCompare(lowerB);\n      }\n      // Same when lowercased - they're equal for sorting purposes\n    } else {\n      // Mixed: numeric comes before non-numeric\n      // (so \"1\" comes before \"a\" at the same position)\n      // This matches `sort -V` behavior\n      return isNumericA ? -1 : 1;\n    }\n  }\n\n  // All compared chunks are equal, shorter string comes first\n  return chunksA.length - chunksB.length;\n}\n\n/**\n * Sort an array of strings using natural (alphanumeric) ordering.\n *\n * @param arr - Array to sort\n * @returns New sorted array (does not mutate original)\n */\nexport function naturalSort(arr: readonly string[]): string[] {\n  return [...arr].sort(naturalCompare);\n}\n\n/**\n * Sort an array of objects by a string key using natural ordering.\n *\n * @param arr - Array to sort\n * @param keyFn - Function to extract the sort key from each element\n * @returns New sorted array (does not mutate original)\n */\nexport function naturalSortBy<T>(arr: readonly T[], keyFn: (item: T) => string): T[] {\n  return [...arr].sort((a, b) => naturalCompare(keyFn(a), keyFn(b)));\n}\n","/**\n * ID mapping management for short public IDs.\n *\n * Maps 4-char base36 short IDs to 26-char ULIDs.\n * Stored in .tbd/data-sync/mappings/ids.yml\n *\n * See: tbd-design.md §2.5 ID Generation\n */\n\nimport { readFile, mkdir } from 'node:fs/promises';\nimport { join, dirname } from 'node:path';\nimport { writeFile } from 'atomically';\n\nimport { parseYamlToleratingDuplicateKeys, stringifyYaml } from '../utils/yaml-utils.js';\n\nimport {\n  generateShortId,\n  extractUlidFromInternalId,\n  makeInternalId,\n  isInternalId,\n  extractShortId,\n  asInternalId,\n  type InternalIssueId,\n} from '../lib/ids.js';\nimport { naturalSort } from '../lib/sort.js';\nimport { IdMappingYamlSchema } from '../lib/schemas.js';\n\n/**\n * ID mapping from short ID to ULID.\n * Format in ids.yml:\n *   a7k2: 01hx5zzkbkactav9wevgemmvrz\n *   b3m9: 01hx5zzkbkbctav9wevgemmvrz\n */\nexport interface IdMapping {\n  shortToUlid: Map<string, string>;\n  ulidToShort: Map<string, string>;\n}\n\n/**\n * Get the path to the ids.yml mapping file.\n */\nfunction getMappingPath(baseDir: string): string {\n  return join(baseDir, 'mappings', 'ids.yml');\n}\n\n/**\n * Load the ID mapping from disk.\n * Returns empty mapping if file doesn't exist.\n */\nexport async function loadIdMapping(baseDir: string): Promise<IdMapping> {\n  const filePath = getMappingPath(baseDir);\n\n  let content: string;\n  try {\n    content = await readFile(filePath, 'utf-8');\n  } catch {\n    // File doesn't exist - return empty mapping\n    return {\n      shortToUlid: new Map(),\n      ulidToShort: new Map(),\n    };\n  }\n\n  // Parse tolerating duplicate keys — this handles the case where a git merge\n  // conflict resolution kept entries from both sides, creating duplicate YAML keys.\n  // Without this, the yaml parser throws \"Map keys must be unique\".\n  const { data: rawData, duplicateKeys } = parseYamlToleratingDuplicateKeys<unknown>(\n    content,\n    filePath,\n  );\n  const data = rawData ?? {};\n\n  if (duplicateKeys.length > 0) {\n    console.warn(\n      `Warning: ${filePath} contains ${duplicateKeys.length} duplicate key(s): ${duplicateKeys.join(', ')}. ` +\n        `This usually happens after a git merge conflict resolution. ` +\n        `The file will be auto-fixed on next save.`,\n    );\n  }\n\n  // Validate with Zod schema - ensures all keys are valid short IDs and values are ULIDs\n  const parseResult = IdMappingYamlSchema.safeParse(data);\n  if (!parseResult.success) {\n    throw new Error(`Invalid ID mapping format in ${filePath}: ${parseResult.error.message}`);\n  }\n  const validData = parseResult.data;\n\n  const shortToUlid = new Map<string, string>();\n  const ulidToShort = new Map<string, string>();\n\n  for (const [shortId, ulid] of Object.entries(validData)) {\n    shortToUlid.set(shortId, ulid);\n    ulidToShort.set(ulid, shortId);\n  }\n\n  return { shortToUlid, ulidToShort };\n}\n\n/**\n * Save the ID mapping to disk.\n */\nexport async function saveIdMapping(baseDir: string, mapping: IdMapping): Promise<void> {\n  const filePath = getMappingPath(baseDir);\n\n  // Ensure directory exists\n  await mkdir(dirname(filePath), { recursive: true });\n\n  // Convert Map to sorted object for deterministic output\n  // Use natural sort so \"1\", \"2\", \"10\" sorts correctly (not \"1\", \"10\", \"2\")\n  const data: Record<string, string> = {};\n  const sortedKeys = naturalSort(Array.from(mapping.shortToUlid.keys()));\n  for (const key of sortedKeys) {\n    data[key] = mapping.shortToUlid.get(key)!;\n  }\n\n  const content = stringifyYaml(data);\n  await writeFile(filePath, content);\n}\n\n/**\n * Calculate the optimal short ID length based on existing ID count.\n *\n * At 50K issues, switches from 4-char to 5-char IDs to keep\n * collision probability low (~3% per attempt with 4 chars at 50K).\n *\n * With 10 retries per length, actual failure probability is astronomically low.\n */\nexport function calculateOptimalLength(existingCount: number): number {\n  return existingCount < 50_000 ? 4 : 5;\n}\n\n/**\n * Generate a unique short ID that doesn't collide with existing ones.\n *\n * Calculates optimal length (4 or 5 chars) based on existing ID count,\n * then retries with the next length if collisions occur.\n *\n * @returns The new short ID\n * @throws If unable to generate a unique ID after max attempts\n */\nexport function generateUniqueShortId(mapping: IdMapping): string {\n  const ATTEMPTS_PER_LENGTH = 10;\n  const existingCount = mapping.shortToUlid.size;\n  const optimalLength = calculateOptimalLength(existingCount);\n\n  // Try optimal length first, then fall back to longer if needed\n  for (const length of [optimalLength, optimalLength + 1]) {\n    for (let attempt = 0; attempt < ATTEMPTS_PER_LENGTH; attempt++) {\n      const shortId = generateShortId(length);\n      if (!mapping.shortToUlid.has(shortId)) {\n        return shortId;\n      }\n    }\n  }\n\n  throw new Error(\n    `Failed to generate unique short ID after 20 attempts with ${existingCount} existing IDs. ` +\n      `This should be extremely rare - please report if you see this error.`,\n  );\n}\n\n/**\n * Register a new ID mapping.\n * @param ulid - The ULID (without is- prefix)\n * @param shortId - The short ID (4 chars)\n */\nexport function addIdMapping(mapping: IdMapping, ulid: string, shortId: string): void {\n  mapping.shortToUlid.set(shortId, ulid);\n  mapping.ulidToShort.set(ulid, shortId);\n}\n\n/**\n * Get the short ID for a ULID.\n * @param ulid - The ULID (without is- prefix)\n * @returns The short ID, or undefined if not found\n */\nexport function getShortId(mapping: IdMapping, ulid: string): string | undefined {\n  return mapping.ulidToShort.get(ulid);\n}\n\n/**\n * Get the ULID for a short ID.\n * @param shortId - The short ID\n * @returns The ULID (without is- prefix), or undefined if not found\n */\nexport function getUlid(mapping: IdMapping, shortId: string): string | undefined {\n  return mapping.shortToUlid.get(shortId);\n}\n\n/**\n * Check if a short ID exists in the mapping.\n */\nexport function hasShortId(mapping: IdMapping, shortId: string): boolean {\n  return mapping.shortToUlid.has(shortId);\n}\n\n/**\n * Create a short ID mapping for a new internal ID.\n * Generates a unique short ID and registers it in the mapping.\n *\n * @param internalId - The internal ID (is-{ulid})\n * @param mapping - The ID mapping to update\n * @returns The generated short ID\n */\nexport function createShortIdMapping(internalId: string, mapping: IdMapping): string {\n  // Extract ULID from internal ID (remove prefix)\n  const ulid = extractUlidFromInternalId(internalId);\n\n  // Check if already mapped\n  const existing = mapping.ulidToShort.get(ulid);\n  if (existing) {\n    return existing;\n  }\n\n  // Generate unique short ID\n  const shortId = generateUniqueShortId(mapping);\n\n  // Register mapping\n  addIdMapping(mapping, ulid, shortId);\n\n  return shortId;\n}\n\n/**\n * Resolve any ID input to an internal ID ({prefix}-{ulid}).\n *\n * Handles:\n * - Internal IDs: {prefix}-{ulid} -> {prefix}-{ulid}\n * - Short IDs: a7k2 -> {prefix}-{ulid from mapping}\n * - Prefixed short IDs: bd-a7k2 -> {prefix}-{ulid from mapping}\n *\n * @param input - The ID input (short ID, prefixed short ID, or internal ID)\n * @param mapping - The ID mapping for short ID resolution\n * @returns The internal ID ({prefix}-{ulid})\n * @throws If the short ID is not found in the mapping\n */\nexport function resolveToInternalId(input: string, mapping: IdMapping): InternalIssueId {\n  const lower = input.toLowerCase();\n\n  // If it's already an internal ID, return it\n  if (isInternalId(lower)) {\n    return asInternalId(lower);\n  }\n\n  // Extract the short ID portion (strips any prefix like \"bd-\" or \"is-\")\n  const shortId = extractShortId(lower);\n\n  // If it's a full ULID (26 chars), it might be a bare internal ID\n  if (shortId.length === 26 && /^[0-9a-z]{26}$/.test(shortId)) {\n    return makeInternalId(shortId);\n  }\n\n  // Must be a short ID - look it up in the mapping\n  const ulid = mapping.shortToUlid.get(shortId);\n  if (!ulid) {\n    throw new Error(`Unknown issue ID: ${input}. ` + `Short ID \"${shortId}\" not found in mapping.`);\n  }\n\n  return makeInternalId(ulid);\n}\n\n/**\n * Parse an ID mapping from raw YAML content.\n * Used for loading mappings from git show output during conflict resolution.\n *\n * @throws MergeConflictError if content contains merge conflict markers\n */\nexport function parseIdMappingFromYaml(content: string): IdMapping {\n  // Parse tolerating duplicate keys — handles post-merge-conflict duplicates\n  const { data: rawData, duplicateKeys } = parseYamlToleratingDuplicateKeys<unknown>(content);\n  const data = rawData ?? {};\n\n  if (duplicateKeys.length > 0) {\n    console.warn(\n      `Warning: ID mapping YAML contains ${duplicateKeys.length} duplicate key(s): ${duplicateKeys.join(', ')}. ` +\n        `Duplicates will be auto-resolved.`,\n    );\n  }\n\n  // Validate with Zod schema\n  const parseResult = IdMappingYamlSchema.safeParse(data);\n  if (!parseResult.success) {\n    throw new Error(`Invalid ID mapping format: ${parseResult.error.message}`);\n  }\n  const validData = parseResult.data;\n\n  const shortToUlid = new Map<string, string>();\n  const ulidToShort = new Map<string, string>();\n\n  for (const [shortId, ulid] of Object.entries(validData)) {\n    shortToUlid.set(shortId, ulid);\n    ulidToShort.set(ulid, shortId);\n  }\n\n  return { shortToUlid, ulidToShort };\n}\n\n/**\n * Merge two ID mappings by combining all entries from both.\n * ID mappings are always additive (new IDs are only added, never removed),\n * so merging simply unions all key-value pairs.\n *\n * If the same short ID maps to different ULIDs in each mapping (a conflict),\n * the local mapping takes precedence (caller should log a warning).\n *\n * @param local - The local ID mapping\n * @param remote - The remote ID mapping\n * @returns Merged mapping with all entries from both\n */\nexport function mergeIdMappings(local: IdMapping, remote: IdMapping): IdMapping {\n  const merged: IdMapping = {\n    shortToUlid: new Map(local.shortToUlid),\n    ulidToShort: new Map(local.ulidToShort),\n  };\n\n  // Add all remote entries that don't conflict\n  for (const [shortId, ulid] of remote.shortToUlid) {\n    if (!merged.shortToUlid.has(shortId)) {\n      merged.shortToUlid.set(shortId, ulid);\n      merged.ulidToShort.set(ulid, shortId);\n    }\n    // If shortId already exists with different ulid, keep local (conflict resolution)\n  }\n\n  // Also check for ULIDs that exist in remote but not in local\n  // (different short ID for same ULID - shouldn't happen but handle gracefully)\n  for (const [ulid, shortId] of remote.ulidToShort) {\n    if (!merged.ulidToShort.has(ulid) && !merged.shortToUlid.has(shortId)) {\n      merged.shortToUlid.set(shortId, ulid);\n      merged.ulidToShort.set(ulid, shortId);\n    }\n  }\n\n  return merged;\n}\n"],"mappings":"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"}
+{"version":3,"file":"id-mapping-JGow6Jk4.mjs","names":[],"sources":["../src/lib/ids.ts","../src/lib/sort.ts","../src/file/id-mapping.ts"],"sourcesContent":["/**\n * ID generation and validation utilities.\n *\n * The system uses dual IDs for usability:\n * - Internal ID: is-{ulid} - ULID-based (26 lowercase chars), stored in files\n * - External ID: {prefix}-{short} - 4-5 base36 chars for CLI display/input\n *\n * For Beads compatibility, bd- prefix is accepted on input for external IDs.\n *\n * See: tbd-design.md §2.5 ID Generation\n */\n\nimport { monotonicFactory } from 'ulid';\nimport { randomBytes } from 'node:crypto';\n\n// Monotonic factory ensures ULIDs are strictly increasing even within the same\n// millisecond. This guarantees that lexicographic sort = creation order, which\n// is critical for deterministic list output (the tiebreaker sort is by ULID).\nconst ulid = monotonicFactory();\n\n// =============================================================================\n// Branded Types for Type-Safe ID Handling\n// =============================================================================\n\n/**\n * Branded type for internal issue IDs (is-{ulid} format).\n *\n * Internal IDs are stored in files and used as the canonical identifier.\n * Format: is-{26 lowercase alphanumeric chars}\n * Example: is-01hx5zzkbkactav9wevgemmvrz\n *\n * Use this type when:\n * - Reading/writing issue files\n * - Storing parent_id, dependencies, child_order_hints\n * - Passing IDs between internal functions\n */\ndeclare const InternalIssueIdBrand: unique symbol;\nexport type InternalIssueId = string & { [InternalIssueIdBrand]: never };\n\n/**\n * Branded type for display issue IDs ({prefix}-{short} format).\n *\n * Display IDs are shown to users and accepted as CLI input.\n * Format: {prefix}-{short} where short is typically 4 base36 chars\n * Example: tbd-a7k2, bd-100\n *\n * Use this type when:\n * - Formatting output for users\n * - Accepting user input (before resolution)\n * - Building tree views for display\n */\ndeclare const DisplayIssueIdBrand: unique symbol;\nexport type DisplayIssueId = string & { [DisplayIssueIdBrand]: never };\n\n/**\n * Cast a string to InternalIssueId after validation.\n * Use this when you've validated that a string is a valid internal ID.\n */\nexport function asInternalId(id: string): InternalIssueId {\n  return id as InternalIssueId;\n}\n\n/**\n * Cast a string to DisplayIssueId.\n * Use this when formatting an ID for display.\n */\nexport function asDisplayId(id: string): DisplayIssueId {\n  return id as DisplayIssueId;\n}\n\n/**\n * Prefix for internal IDs (ULID-based).\n * All internal IDs are formatted as: {INTERNAL_ID_PREFIX}-{ulid}\n */\nexport const INTERNAL_ID_PREFIX = 'is';\n\n/**\n * Length of internal ID prefix including the hyphen (e.g., \"is-\" = 3).\n */\nexport const INTERNAL_ID_PREFIX_LENGTH = INTERNAL_ID_PREFIX.length + 1;\n\n/**\n * Construct an internal ID from a ULID.\n *\n * @param ulidValue - The ULID (26 chars)\n * @returns Internal ID in format {prefix}-{ulid}\n */\nexport function makeInternalId(ulidValue: string): InternalIssueId {\n  return `${INTERNAL_ID_PREFIX}-${ulidValue.toLowerCase()}` as InternalIssueId;\n}\n\n/**\n * Generate a unique internal ID using ULID.\n * Format: is-{ulid} (26 lowercase alphanumeric chars)\n * Example: is-01hx5zzkbkactav9wevgemmvrz\n *\n * ULID provides:\n * - Time-ordered sorting (48-bit timestamp)\n * - 80-bit randomness (no collisions)\n * - Lexicographic sort = chronological order\n */\nexport function generateInternalId(): InternalIssueId {\n  return makeInternalId(ulid());\n}\n\n/**\n * Generate a short ID for external display.\n * Format: base36 characters (a-z, 0-9)\n * Example: a7k2\n *\n * @param length - Number of characters (default 4)\n */\nexport function generateShortId(length = 4): string {\n  const chars = '0123456789abcdefghijklmnopqrstuvwxyz';\n  let result = '';\n  const bytes = randomBytes(length);\n  for (let i = 0; i < length; i++) {\n    result += chars[bytes[i]! % 36];\n  }\n  return result;\n}\n\n// Regex pattern for validating internal IDs - built from prefix constant\nconst INTERNAL_ID_PATTERN = new RegExp(`^${INTERNAL_ID_PREFIX}-[0-9a-z]{26}$`);\n\n// Expected length of a full internal ID (prefix + hyphen + 26-char ULID)\nconst INTERNAL_ID_LENGTH = INTERNAL_ID_PREFIX_LENGTH + 26;\n\n/**\n * Validate an internal issue ID matches the ULID format.\n * Format: {prefix}-{26 lowercase alphanumeric chars}\n */\nexport function validateIssueId(id: string): boolean {\n  return INTERNAL_ID_PATTERN.test(id);\n}\n\n/**\n * Validate a short/external ID format.\n * Format: 1+ base36 characters (typically 4 for new IDs, but imports may preserve longer IDs).\n */\nexport function validateShortId(id: string): boolean {\n  return /^[0-9a-z]+$/.test(id);\n}\n\n/**\n * Check if an input looks like an internal ID (ULID-based).\n */\nexport function isInternalId(input: string): boolean {\n  const lower = input.toLowerCase();\n  // Check if it starts with the internal prefix and has correct length\n  const prefixWithHyphen = `${INTERNAL_ID_PREFIX}-`;\n  if (lower.startsWith(prefixWithHyphen) && lower.length === INTERNAL_ID_LENGTH) {\n    return INTERNAL_ID_PATTERN.test(lower);\n  }\n  return false;\n}\n\n/**\n * Check if an input looks like a short/external ID.\n * Returns true for IDs like \"a7k2\", \"bd-a7k2\", \"100\", \"tbd-100\".\n * Short IDs are 16 characters or less (ULIDs are 26 characters).\n */\nexport function isShortId(input: string): boolean {\n  const lower = input.toLowerCase();\n  // Strip prefix if present\n  const stripped = lower.replace(/^[a-z]+-/, '');\n  // Must be 1-16 alphanumeric chars (short IDs, not ULIDs which are 26 chars)\n  return /^[0-9a-z]+$/.test(stripped) && stripped.length >= 1 && stripped.length <= 16;\n}\n\n/**\n * Extract the short ID portion from an external ID.\n * Examples:\n *   \"tbd-100\" -> \"100\"\n *   \"bd-a7k2\" -> \"a7k2\"\n *   \"a7k2\" -> \"a7k2\"\n *   \"100\" -> \"100\"\n */\nexport function extractShortId(externalId: string): string {\n  return externalId.toLowerCase().replace(/^[a-z]+-/, '');\n}\n\n/**\n * Extract the prefix portion from an external ID.\n * Returns the prefix (letters before the hyphen) or null if no prefix found.\n * Examples:\n *   \"tbd-100\" -> \"tbd\"\n *   \"bd-a7k2\" -> \"bd\"\n *   \"TBD-100\" -> \"tbd\" (normalized to lowercase)\n *   \"a7k2\" -> null (no prefix)\n *   \"100\" -> null (no prefix)\n */\nexport function extractPrefix(externalId: string): string | null {\n  const match = /^([a-zA-Z]+)-/.exec(externalId);\n  return match?.[1]?.toLowerCase() ?? null;\n}\n\n/**\n * Extract the ULID portion from an internal ID.\n *\n * Internal IDs have the format: {prefix}-{ulid}\n * This function strips any prefix to return just the ULID.\n *\n * Examples:\n *   \"is-01hx5zzkbkactav9wevgemmvrz\" -> \"01hx5zzkbkactav9wevgemmvrz\"\n *   \"01hx5zzkbkactav9wevgemmvrz\" -> \"01hx5zzkbkactav9wevgemmvrz\" (no prefix)\n *\n * @param internalId - The internal ID (with or without prefix)\n * @returns The ULID portion without any prefix\n */\nexport function extractUlidFromInternalId(internalId: string): string {\n  // Strip any prefix in format {letters}- (e.g., \"is-\", \"bd-\")\n  return internalId.toLowerCase().replace(/^[a-z]+-/, '');\n}\n\n/** Prefix used in Beads for compatibility */\nconst BEADS_COMPAT_PREFIX = 'bd';\n\n/**\n * Normalize an internal issue ID.\n *\n * This function expects a full internal ID ({prefix}-{ulid}).\n * If given a short ID, it won't be able to resolve it without\n * access to the ID mapping.\n *\n * Handles:\n * - Uppercase (converts to lowercase)\n * - Ensures internal ID prefix\n * - Beads compatibility (bd- prefix)\n */\nexport function normalizeIssueId(input: string): string {\n  const lower = input.toLowerCase();\n  const internalPrefixWithHyphen = `${INTERNAL_ID_PREFIX}-`;\n  const beadsPrefixWithHyphen = `${BEADS_COMPAT_PREFIX}-`;\n\n  // If already a valid internal ID, return as-is\n  if (validateIssueId(lower)) {\n    return lower;\n  }\n\n  // If it starts with internal prefix but wrong length, might be corrupted\n  if (lower.startsWith(internalPrefixWithHyphen)) {\n    return lower; // Return as-is, let validation fail later\n  }\n\n  // If it starts with bd- (Beads compat), convert prefix\n  if (lower.startsWith(beadsPrefixWithHyphen)) {\n    const rest = lower.slice(beadsPrefixWithHyphen.length);\n    if (rest.length === 26) {\n      return makeInternalId(rest);\n    }\n    // Short ID - can't resolve without mapping\n    return lower;\n  }\n\n  // Bare ID without prefix\n  if (lower.length === 26 && /^[0-9a-z]{26}$/.test(lower)) {\n    return makeInternalId(lower);\n  }\n\n  // Can't normalize - return as-is\n  return lower;\n}\n\nimport type { IdMapping } from '../file/id-mapping.js';\n\n/**\n * Format an internal ID for display with the configured prefix.\n *\n * Uses the short ID (4 chars) from the mapping.\n * Throws an error if the mapping is missing or doesn't contain the ID.\n *\n * IMPORTANT: All user-facing output MUST use short IDs, never internal ULIDs.\n * If you see a ULID in user output, it's a bug.\n *\n * @param internalId - The internal ID (is-{ulid})\n * @param mapping - ID mapping for short ID lookup (required)\n * @param prefix - Display prefix (should come from config.display.id_prefix; defaults to 'tbd' as fallback)\n * @throws Error if mapping is missing or ID not found in mapping\n */\nexport function formatDisplayId(\n  internalId: InternalIssueId | string,\n  mapping: IdMapping,\n  prefix = 'tbd',\n): DisplayIssueId {\n  // Extract the ULID portion\n  const ulidPart = extractUlidFromInternalId(internalId);\n\n  // Get short ID from mapping\n  const shortId = mapping.ulidToShort.get(ulidPart);\n  if (!shortId) {\n    throw new Error(\n      `No short ID mapping found for internal ID: ${internalId}. ` +\n        `This is a bug - all issues must have a short ID mapping.`,\n    );\n  }\n\n  return `${prefix}-${shortId}` as DisplayIssueId;\n}\n\n/**\n * Format an ID for debug output, showing both public and internal IDs.\n *\n * @param internalId - The internal ID (is-{ulid})\n * @param mapping - ID mapping for short ID lookup\n * @param prefix - Display prefix (should come from config.display.id_prefix; defaults to 'tbd' as fallback)\n */\nexport function formatDebugId(\n  internalId: InternalIssueId | string,\n  mapping: IdMapping,\n  prefix = 'tbd',\n): string {\n  const displayId = formatDisplayId(internalId, mapping, prefix);\n  return `${displayId} (${internalId})`;\n}\n","/**\n * Natural sort utilities.\n *\n * Provides alphanumeric sorting where numeric portions are sorted numerically.\n * Similar to `sort -V` (version sort) or `sort -n` for numbers.\n *\n * Examples:\n *   [\"1\", \"2\", \"9\", \"10\", \"11\"] instead of [\"1\", \"10\", \"11\", \"2\", \"9\"]\n *   [\"a1\", \"a2\", \"a10\"] instead of [\"a1\", \"a10\", \"a2\"]\n *   [\"file1.txt\", \"file2.txt\", \"file10.txt\"] instead of [\"file1.txt\", \"file10.txt\", \"file2.txt\"]\n */\n\n/**\n * Split a string into alternating runs of digits and non-digits.\n * @param str - The string to split\n * @returns Array of [isNumeric, value] tuples\n */\nfunction splitIntoChunks(str: string): [boolean, string][] {\n  const chunks: [boolean, string][] = [];\n  let current = '';\n  let currentIsNumeric: boolean | null = null;\n\n  for (const char of str) {\n    const isDigit = char >= '0' && char <= '9';\n\n    if (currentIsNumeric === null) {\n      // First character\n      currentIsNumeric = isDigit;\n      current = char;\n    } else if (isDigit === currentIsNumeric) {\n      // Same type, continue accumulating\n      current += char;\n    } else {\n      // Type changed, push current chunk and start new one\n      chunks.push([currentIsNumeric, current]);\n      currentIsNumeric = isDigit;\n      current = char;\n    }\n  }\n\n  // Push final chunk\n  if (current) {\n    chunks.push([currentIsNumeric!, current]);\n  }\n\n  return chunks;\n}\n\n/**\n * Compare two strings using natural (alphanumeric) ordering.\n *\n * Numeric portions are compared numerically, non-numeric portions are\n * compared lexicographically (case-insensitive). Numbers sort before letters\n * when they appear at the same position in mixed comparisons, matching\n * the behavior of `sort -V` (version sort).\n *\n * @param a - First string\n * @param b - Second string\n * @returns Negative if a < b, positive if a > b, zero if equal\n */\nexport function naturalCompare(a: string, b: string): number {\n  // Handle empty strings\n  if (!a && !b) return 0;\n  if (!a) return -1;\n  if (!b) return 1;\n\n  const chunksA = splitIntoChunks(a);\n  const chunksB = splitIntoChunks(b);\n\n  const minLen = Math.min(chunksA.length, chunksB.length);\n\n  for (let i = 0; i < minLen; i++) {\n    const [isNumericA, valueA] = chunksA[i]!;\n    const [isNumericB, valueB] = chunksB[i]!;\n\n    if (isNumericA && isNumericB) {\n      // Both are numeric - compare as numbers\n      const numA = parseInt(valueA, 10);\n      const numB = parseInt(valueB, 10);\n      if (numA !== numB) {\n        return numA - numB;\n      }\n      // If numerically equal but different strings (e.g., \"01\" vs \"1\"),\n      // prefer shorter (fewer leading zeros)\n      if (valueA.length !== valueB.length) {\n        return valueA.length - valueB.length;\n      }\n    } else if (!isNumericA && !isNumericB) {\n      // Both are non-numeric - compare lexicographically (case-insensitive)\n      const lowerA = valueA.toLowerCase();\n      const lowerB = valueB.toLowerCase();\n      if (lowerA !== lowerB) {\n        return lowerA.localeCompare(lowerB);\n      }\n      // Same when lowercased - they're equal for sorting purposes\n    } else {\n      // Mixed: numeric comes before non-numeric\n      // (so \"1\" comes before \"a\" at the same position)\n      // This matches `sort -V` behavior\n      return isNumericA ? -1 : 1;\n    }\n  }\n\n  // All compared chunks are equal, shorter string comes first\n  return chunksA.length - chunksB.length;\n}\n\n/**\n * Sort an array of strings using natural (alphanumeric) ordering.\n *\n * @param arr - Array to sort\n * @returns New sorted array (does not mutate original)\n */\nexport function naturalSort(arr: readonly string[]): string[] {\n  return [...arr].sort(naturalCompare);\n}\n\n/**\n * Sort an array of objects by a string key using natural ordering.\n *\n * @param arr - Array to sort\n * @param keyFn - Function to extract the sort key from each element\n * @returns New sorted array (does not mutate original)\n */\nexport function naturalSortBy<T>(arr: readonly T[], keyFn: (item: T) => string): T[] {\n  return [...arr].sort((a, b) => naturalCompare(keyFn(a), keyFn(b)));\n}\n","/**\n * ID mapping management for short public IDs.\n *\n * Maps 4-char base36 short IDs to 26-char ULIDs.\n * Stored in .tbd/data-sync/mappings/ids.yml\n *\n * See: tbd-design.md §2.5 ID Generation\n */\n\nimport { readFile, mkdir } from 'node:fs/promises';\nimport { join, dirname } from 'node:path';\nimport { writeFile } from 'atomically';\n\nimport { parseYamlToleratingDuplicateKeys, stringifyYaml } from '../utils/yaml-utils.js';\n\nimport {\n  generateShortId,\n  extractUlidFromInternalId,\n  makeInternalId,\n  isInternalId,\n  extractShortId,\n  asInternalId,\n  type InternalIssueId,\n} from '../lib/ids.js';\nimport { naturalSort } from '../lib/sort.js';\nimport { IdMappingYamlSchema } from '../lib/schemas.js';\n\n/**\n * ID mapping from short ID to ULID.\n * Format in ids.yml:\n *   a7k2: 01hx5zzkbkactav9wevgemmvrz\n *   b3m9: 01hx5zzkbkbctav9wevgemmvrz\n */\nexport interface IdMapping {\n  shortToUlid: Map<string, string>;\n  ulidToShort: Map<string, string>;\n}\n\n/**\n * Get the path to the ids.yml mapping file.\n */\nfunction getMappingPath(baseDir: string): string {\n  return join(baseDir, 'mappings', 'ids.yml');\n}\n\n/**\n * Load the ID mapping from disk.\n * Returns empty mapping if file doesn't exist.\n */\nexport async function loadIdMapping(baseDir: string): Promise<IdMapping> {\n  const filePath = getMappingPath(baseDir);\n\n  let content: string;\n  try {\n    content = await readFile(filePath, 'utf-8');\n  } catch {\n    // File doesn't exist - return empty mapping\n    return {\n      shortToUlid: new Map(),\n      ulidToShort: new Map(),\n    };\n  }\n\n  // Parse tolerating duplicate keys — this handles the case where a git merge\n  // conflict resolution kept entries from both sides, creating duplicate YAML keys.\n  // Without this, the yaml parser throws \"Map keys must be unique\".\n  const { data: rawData, duplicateKeys } = parseYamlToleratingDuplicateKeys<unknown>(\n    content,\n    filePath,\n  );\n  const data = rawData ?? {};\n\n  if (duplicateKeys.length > 0) {\n    console.warn(\n      `Warning: ${filePath} contains ${duplicateKeys.length} duplicate key(s): ${duplicateKeys.join(', ')}. ` +\n        `This usually happens after a git merge conflict resolution. ` +\n        `The file will be auto-fixed on next save.`,\n    );\n  }\n\n  // Validate with Zod schema - ensures all keys are valid short IDs and values are ULIDs\n  const parseResult = IdMappingYamlSchema.safeParse(data);\n  if (!parseResult.success) {\n    throw new Error(`Invalid ID mapping format in ${filePath}: ${parseResult.error.message}`);\n  }\n  const validData = parseResult.data;\n\n  const shortToUlid = new Map<string, string>();\n  const ulidToShort = new Map<string, string>();\n\n  for (const [shortId, ulid] of Object.entries(validData)) {\n    shortToUlid.set(shortId, ulid);\n    ulidToShort.set(ulid, shortId);\n  }\n\n  return { shortToUlid, ulidToShort };\n}\n\n/**\n * Save the ID mapping to disk.\n */\nexport async function saveIdMapping(baseDir: string, mapping: IdMapping): Promise<void> {\n  const filePath = getMappingPath(baseDir);\n\n  // Ensure directory exists\n  await mkdir(dirname(filePath), { recursive: true });\n\n  // Convert Map to sorted object for deterministic output\n  // Use natural sort so \"1\", \"2\", \"10\" sorts correctly (not \"1\", \"10\", \"2\")\n  const data: Record<string, string> = {};\n  const sortedKeys = naturalSort(Array.from(mapping.shortToUlid.keys()));\n  for (const key of sortedKeys) {\n    data[key] = mapping.shortToUlid.get(key)!;\n  }\n\n  const content = stringifyYaml(data);\n  await writeFile(filePath, content);\n}\n\n/**\n * Calculate the optimal short ID length based on existing ID count.\n *\n * At 50K issues, switches from 4-char to 5-char IDs to keep\n * collision probability low (~3% per attempt with 4 chars at 50K).\n *\n * With 10 retries per length, actual failure probability is astronomically low.\n */\nexport function calculateOptimalLength(existingCount: number): number {\n  return existingCount < 50_000 ? 4 : 5;\n}\n\n/**\n * Generate a unique short ID that doesn't collide with existing ones.\n *\n * Calculates optimal length (4 or 5 chars) based on existing ID count,\n * then retries with the next length if collisions occur.\n *\n * @returns The new short ID\n * @throws If unable to generate a unique ID after max attempts\n */\nexport function generateUniqueShortId(mapping: IdMapping): string {\n  const ATTEMPTS_PER_LENGTH = 10;\n  const existingCount = mapping.shortToUlid.size;\n  const optimalLength = calculateOptimalLength(existingCount);\n\n  // Try optimal length first, then fall back to longer if needed\n  for (const length of [optimalLength, optimalLength + 1]) {\n    for (let attempt = 0; attempt < ATTEMPTS_PER_LENGTH; attempt++) {\n      const shortId = generateShortId(length);\n      if (!mapping.shortToUlid.has(shortId)) {\n        return shortId;\n      }\n    }\n  }\n\n  throw new Error(\n    `Failed to generate unique short ID after 20 attempts with ${existingCount} existing IDs. ` +\n      `This should be extremely rare - please report if you see this error.`,\n  );\n}\n\n/**\n * Register a new ID mapping.\n * @param ulid - The ULID (without is- prefix)\n * @param shortId - The short ID (4 chars)\n */\nexport function addIdMapping(mapping: IdMapping, ulid: string, shortId: string): void {\n  mapping.shortToUlid.set(shortId, ulid);\n  mapping.ulidToShort.set(ulid, shortId);\n}\n\n/**\n * Get the short ID for a ULID.\n * @param ulid - The ULID (without is- prefix)\n * @returns The short ID, or undefined if not found\n */\nexport function getShortId(mapping: IdMapping, ulid: string): string | undefined {\n  return mapping.ulidToShort.get(ulid);\n}\n\n/**\n * Get the ULID for a short ID.\n * @param shortId - The short ID\n * @returns The ULID (without is- prefix), or undefined if not found\n */\nexport function getUlid(mapping: IdMapping, shortId: string): string | undefined {\n  return mapping.shortToUlid.get(shortId);\n}\n\n/**\n * Check if a short ID exists in the mapping.\n */\nexport function hasShortId(mapping: IdMapping, shortId: string): boolean {\n  return mapping.shortToUlid.has(shortId);\n}\n\n/**\n * Create a short ID mapping for a new internal ID.\n * Generates a unique short ID and registers it in the mapping.\n *\n * @param internalId - The internal ID (is-{ulid})\n * @param mapping - The ID mapping to update\n * @returns The generated short ID\n */\nexport function createShortIdMapping(internalId: string, mapping: IdMapping): string {\n  // Extract ULID from internal ID (remove prefix)\n  const ulid = extractUlidFromInternalId(internalId);\n\n  // Check if already mapped\n  const existing = mapping.ulidToShort.get(ulid);\n  if (existing) {\n    return existing;\n  }\n\n  // Generate unique short ID\n  const shortId = generateUniqueShortId(mapping);\n\n  // Register mapping\n  addIdMapping(mapping, ulid, shortId);\n\n  return shortId;\n}\n\n/**\n * Resolve any ID input to an internal ID ({prefix}-{ulid}).\n *\n * Handles:\n * - Internal IDs: {prefix}-{ulid} -> {prefix}-{ulid}\n * - Short IDs: a7k2 -> {prefix}-{ulid from mapping}\n * - Prefixed short IDs: bd-a7k2 -> {prefix}-{ulid from mapping}\n *\n * @param input - The ID input (short ID, prefixed short ID, or internal ID)\n * @param mapping - The ID mapping for short ID resolution\n * @returns The internal ID ({prefix}-{ulid})\n * @throws If the short ID is not found in the mapping\n */\nexport function resolveToInternalId(input: string, mapping: IdMapping): InternalIssueId {\n  const lower = input.toLowerCase();\n\n  // If it's already an internal ID, return it\n  if (isInternalId(lower)) {\n    return asInternalId(lower);\n  }\n\n  // Extract the short ID portion (strips any prefix like \"bd-\" or \"is-\")\n  const shortId = extractShortId(lower);\n\n  // If it's a full ULID (26 chars), it might be a bare internal ID\n  if (shortId.length === 26 && /^[0-9a-z]{26}$/.test(shortId)) {\n    return makeInternalId(shortId);\n  }\n\n  // Must be a short ID - look it up in the mapping\n  const ulid = mapping.shortToUlid.get(shortId);\n  if (!ulid) {\n    throw new Error(`Unknown issue ID: ${input}. ` + `Short ID \"${shortId}\" not found in mapping.`);\n  }\n\n  return makeInternalId(ulid);\n}\n\n/**\n * Parse an ID mapping from raw YAML content.\n * Used for loading mappings from git show output during conflict resolution.\n *\n * @throws MergeConflictError if content contains merge conflict markers\n */\nexport function parseIdMappingFromYaml(content: string): IdMapping {\n  // Parse tolerating duplicate keys — handles post-merge-conflict duplicates\n  const { data: rawData, duplicateKeys } = parseYamlToleratingDuplicateKeys<unknown>(content);\n  const data = rawData ?? {};\n\n  if (duplicateKeys.length > 0) {\n    console.warn(\n      `Warning: ID mapping YAML contains ${duplicateKeys.length} duplicate key(s): ${duplicateKeys.join(', ')}. ` +\n        `Duplicates will be auto-resolved.`,\n    );\n  }\n\n  // Validate with Zod schema\n  const parseResult = IdMappingYamlSchema.safeParse(data);\n  if (!parseResult.success) {\n    throw new Error(`Invalid ID mapping format: ${parseResult.error.message}`);\n  }\n  const validData = parseResult.data;\n\n  const shortToUlid = new Map<string, string>();\n  const ulidToShort = new Map<string, string>();\n\n  for (const [shortId, ulid] of Object.entries(validData)) {\n    shortToUlid.set(shortId, ulid);\n    ulidToShort.set(ulid, shortId);\n  }\n\n  return { shortToUlid, ulidToShort };\n}\n\n/**\n * Ensure all given internal IDs have short ID mappings.\n * Creates missing mappings for any IDs without entries.\n *\n * This repairs state after git merges that may add issue files\n * without corresponding mapping entries (e.g., when outbox issues\n * are merged from a feature branch but ids.yml doesn't include them).\n *\n * When a `historicalMapping` is provided, the function will try to recover\n * the original short ID from that mapping before generating a new random one.\n * This preserves ID stability so that existing references (in docs, PRs,\n * conversations) remain valid.\n *\n * @param internalIds - Array of internal IDs (is-{ulid}) to reconcile\n * @param mapping - The ID mapping to update (mutated in-place)\n * @param historicalMapping - Optional mapping from prior state (e.g., git history) to recover original short IDs\n * @returns Object with `created` (IDs that got new random short IDs) and `recovered` (IDs restored from history)\n */\nexport function reconcileMappings(\n  internalIds: string[],\n  mapping: IdMapping,\n  historicalMapping?: IdMapping,\n): { created: string[]; recovered: string[] } {\n  const created: string[] = [];\n  const recovered: string[] = [];\n\n  for (const id of internalIds) {\n    const ulid = extractUlidFromInternalId(id);\n    if (mapping.ulidToShort.has(ulid)) {\n      continue; // Already has a mapping\n    }\n\n    // Try to recover original short ID from historical mapping\n    const historicalShortId = historicalMapping?.ulidToShort.get(ulid);\n    if (historicalShortId && !mapping.shortToUlid.has(historicalShortId)) {\n      // Recovered: restore the original short ID\n      addIdMapping(mapping, ulid, historicalShortId);\n      recovered.push(id);\n    } else {\n      // No history available or short ID conflicts — generate new random one\n      createShortIdMapping(id, mapping);\n      created.push(id);\n    }\n  }\n\n  return { created, recovered };\n}\n\n/**\n * Merge two ID mappings by combining all entries from both.\n * ID mappings are always additive (new IDs are only added, never removed),\n * so merging simply unions all key-value pairs.\n *\n * If the same short ID maps to different ULIDs in each mapping (a conflict),\n * the local mapping takes precedence (caller should log a warning).\n *\n * @param local - The local ID mapping\n * @param remote - The remote ID mapping\n * @returns Merged mapping with all entries from both\n */\nexport function mergeIdMappings(local: IdMapping, remote: IdMapping): IdMapping {\n  const merged: IdMapping = {\n    shortToUlid: new Map(local.shortToUlid),\n    ulidToShort: new Map(local.ulidToShort),\n  };\n\n  // Add all remote entries that don't conflict\n  for (const [shortId, ulid] of remote.shortToUlid) {\n    if (!merged.shortToUlid.has(shortId)) {\n      merged.shortToUlid.set(shortId, ulid);\n      merged.ulidToShort.set(ulid, shortId);\n    }\n    // If shortId already exists with different ulid, keep local (conflict resolution)\n  }\n\n  // Also check for ULIDs that exist in remote but not in local\n  // (different short ID for same ULID - shouldn't happen but handle gracefully)\n  for (const [ulid, shortId] of remote.ulidToShort) {\n    if (!merged.ulidToShort.has(ulid) && !merged.shortToUlid.has(shortId)) {\n      merged.shortToUlid.set(shortId, ulid);\n      merged.ulidToShort.set(ulid, shortId);\n    }\n  }\n\n  return merged;\n}\n"],"mappings":"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"}

package/dist/index.d.mts

@@ -106,6 +106,12 @@ declare const Dependency: z.ZodObject<{
  *
  * Note: Fields use .nullable() in addition to .optional() because
  * YAML parses `field: null` as JavaScript null, not undefined.
+ *
+ * Design note: We could add the short ID to this schema. We didn't originally
+ * because it's one more field to maintain consistency around across files.
+ * Having it here might make recovery of lost ID mappings far easier, but for
+ * now we have more reliable management of the mappings file (ids.yml) and
+ * consider it authoritative. See IdMappingYamlSchema (§2.6.8).
  */
 declare const IssueSchema: z.ZodObject<{
   id: z.ZodString;

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { A as LOCAL_STATE_FIELD_ORDER, C as GitRemoteName, D as IssueKind, E as IssueId, F as ShortId, I as Timestamp, L as Ulid, M as META_FIELD_ORDER, N as MetaSchema, O as IssueSchema, P as Priority, R as Version, S as GitBranchName, T as IdMappingYamlSchema, _ as DependencyRelationType, b as EntityType, d as ATTIC_ENTRY_FIELD_ORDER, f as AtticEntrySchema, g as Dependency, h as ConfigSchema, j as LocalStateSchema, k as IssueStatus, m as CONFIG_FIELD_ORDER, p as BaseEntity, v as DocCacheConfigSchema, w as ISSUE_FIELD_ORDER, x as ExternalIssueIdInput, y as DocsCacheSchema } from "./yaml-utils-x_kr2IId.mjs";
-import { c as noopLogger, i as serializeIssue, n as parseIssue, t as VERSION } from "./src-BjMRpmMh.mjs";
+import { A as LOCAL_STATE_FIELD_ORDER, C as GitRemoteName, D as IssueKind, E as IssueId, F as ShortId, I as Timestamp, L as Ulid, M as META_FIELD_ORDER, N as MetaSchema, O as IssueSchema, P as Priority, R as Version, S as GitBranchName, T as IdMappingYamlSchema, _ as DependencyRelationType, b as EntityType, d as ATTIC_ENTRY_FIELD_ORDER, f as AtticEntrySchema, g as Dependency, h as ConfigSchema, j as LocalStateSchema, k as IssueStatus, m as CONFIG_FIELD_ORDER, p as BaseEntity, v as DocCacheConfigSchema, w as ISSUE_FIELD_ORDER, x as ExternalIssueIdInput, y as DocsCacheSchema } from "./yaml-utils-U7l9hhkh.mjs";
+import { c as noopLogger, i as serializeIssue, n as parseIssue, t as VERSION } from "./src-7qUDeWJf.mjs";
 
 export { ATTIC_ENTRY_FIELD_ORDER, AtticEntrySchema, BaseEntity, CONFIG_FIELD_ORDER, ConfigSchema, Dependency, DependencyRelationType, DocCacheConfigSchema, DocsCacheSchema, EntityType, ExternalIssueIdInput, GitBranchName, GitRemoteName, ISSUE_FIELD_ORDER, IdMappingYamlSchema, IssueId, IssueKind, IssueSchema, IssueStatus, LOCAL_STATE_FIELD_ORDER, LocalStateSchema, META_FIELD_ORDER, MetaSchema, Priority, ShortId, Timestamp, Ulid, VERSION, Version, noopLogger, parseIssue, serializeIssue };