get-tbd 0.1.21 → 0.1.23

package/dist/cli.mjs

@@ -1,6 +1,7 @@
-import { A as LOCAL_STATE_FIELD_ORDER, D as IssueKind, a as stringifyYaml, c as ordering, d as ATTIC_ENTRY_FIELD_ORDER, f as AtticEntrySchema, h as ConfigSchema, i as sortKeys, j as LocalStateSchema, k as IssueStatus, l as PAGINATION_LINE_THRESHOLD, m as CONFIG_FIELD_ORDER, r as parseYamlWithConflictDetection, s as comparisonChain, t as detectDuplicateYamlKeys, u as PARENT_CONTEXT_MAX_LINES } from "./yaml-utils-x_kr2IId.mjs";
-import { a as insertAfterFrontmatter, c as noopLogger, i as serializeIssue, n as parseIssue, o as parseMarkdown, r as parseMarkdownWithFrontmatter, s as stripFrontmatter, t as VERSION$1 } from "./src-BjMRpmMh.mjs";
-import { _ as normalizeIssueId, a as loadIdMapping, c as resolveToInternalId, d as extractShortId, f as extractUlidFromInternalId, g as makeInternalId, h as generateInternalId, i as hasShortId, l as saveIdMapping, m as formatDisplayId, o as mergeIdMappings, p as formatDebugId, r as generateUniqueShortId, s as parseIdMappingFromYaml, t as addIdMapping, u as extractPrefix, v as validateIssueId } from "./id-mapping-CD5c_ZVA.mjs";
+import { D as IssueKind, a as stringifyYaml, c as ordering, d as ATTIC_ENTRY_FIELD_ORDER, f as AtticEntrySchema, i as sortKeys, k as IssueStatus, l as PAGINATION_LINE_THRESHOLD, r as parseYamlWithConflictDetection, s as comparisonChain, t as detectDuplicateYamlKeys, u as PARENT_CONTEXT_MAX_LINES } from "./yaml-utils-U7l9hhkh.mjs";
+import { a as insertAfterFrontmatter, c as noopLogger, i as serializeIssue, n as parseIssue, o as parseMarkdown, r as parseMarkdownWithFrontmatter, s as stripFrontmatter, t as VERSION$1 } from "./src-7qUDeWJf.mjs";
+import { A as isValidWorkspaceName, C as TBD_SHORTCUTS_STANDARD, D as WORKTREE_DIR, E as WORKSPACES_DIR, M as resolveDataSyncDir, O as WORKTREE_DIR_NAME, S as TBD_GUIDELINES_DIR, T as TBD_TEMPLATES_DIR, _ as DEFAULT_SHORTCUT_PATHS, a as isInitialized, b as TBD_DIR, c as readConfigWithMigration, d as writeConfig, g as DEFAULT_GUIDELINES_PATHS, h as DATA_SYNC_DIR_NAME, i as initConfig, j as resolveAtticDir, k as getWorkspaceDir, l as readLocalState, m as DATA_SYNC_DIR, n as findTbdRoot, o as markWelcomeSeen, p as CHARS_PER_TOKEN, r as hasSeenWelcome, s as readConfig, u as updateLocalState, v as DEFAULT_TEMPLATE_PATHS, w as TBD_SHORTCUTS_SYSTEM, x as TBD_DOCS_DIR, y as SYNC_BRANCH } from "./config-CmEAGaxz.mjs";
+import { _ as generateInternalId, a as hasShortId, b as validateIssueId, c as parseIdMappingFromYaml, d as saveIdMapping, f as extractPrefix, g as formatDisplayId, h as formatDebugId, i as generateUniqueShortId, l as reconcileMappings, m as extractUlidFromInternalId, o as loadIdMapping, p as extractShortId, s as mergeIdMappings, t as addIdMapping, u as resolveToInternalId, v as makeInternalId, y as normalizeIssueId } from "./id-mapping-JGow6Jk4.mjs";
 import { createRequire } from "node:module";
 import matter from "gray-matter";
 import { parse } from "yaml";
@@ -10,7 +11,7 @@ import { marked } from "marked";
 import { markedTerminal } from "marked-terminal";
 import { execFile, execSync, spawn, spawnSync } from "node:child_process";
 import { access, chmod, cp, mkdir, readFile, readdir, rename, rm, stat, unlink } from "node:fs/promises";
-import { basename, dirname, isAbsolute, join, normalize, parse as parse$1, relative, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
 import { writeFile } from "atomically";
 import { homedir } from "node:os";
 import { promisify } from "node:util";
@@ -52,15 +53,12 @@ const VERSION = getVersion();
 */
 function getCommandContext(command) {
 	const opts = command.optsWithGlobals();
-	const isCI = Boolean(process.env.CI);
 	return {
 		dryRun: opts.dryRun ?? false,
 		verbose: opts.verbose ?? false,
 		quiet: opts.quiet ?? false,
 		json: opts.json ?? false,
 		color: opts.color ?? "auto",
-		nonInteractive: opts.nonInteractive ?? (!process.stdin.isTTY || isCI),
-		yes: opts.yes ?? false,
 		sync: opts.sync !== false,
 		debug: opts.debug ?? false
 	};
@@ -550,634 +548,6 @@ var OutputManager = class {
 	}
 };
 
-//#endregion
-//#region src/lib/paths.ts
-/**
-* Centralized path constants for tbd.
-*
-* Directory structure (per spec):
-*
-* On main/dev branches:
-*   .tbd/
-*     Committed to the repo:
-*       config.yml            - Project configuration
-*       .gitignore            - Controls what's gitignored below
-*       workspaces/           - Persistent state (outbox, named workspaces)
-*     Gitignored (local only):
-*       state.yml             - Local state
-*       docs/                 - Installed documentation (regenerated on setup)
-*       data-sync-worktree/   - Hidden worktree checkout of tbd-sync branch
-*         .tbd/data-sync/     - issues/, mappings/, attic/, meta.yml
-*
-* On tbd-sync branch:
-*   .tbd/
-*     data-sync/
-*       issues/
-*       mappings/
-*       attic/
-*       meta.yml
-*/
-/** The tbd configuration directory on main branch */
-const TBD_DIR = ".tbd";
-/** The config file path */
-const CONFIG_FILE = join(TBD_DIR, "config.yml");
-/** The local state file (gitignored) */
-const STATE_FILE = join(TBD_DIR, "state.yml");
-/** The worktree directory name */
-const WORKTREE_DIR_NAME = "data-sync-worktree";
-/** The worktree path (gitignored) */
-const WORKTREE_DIR = join(TBD_DIR, WORKTREE_DIR_NAME);
-/** The data directory name on the sync branch */
-const DATA_SYNC_DIR_NAME = "data-sync";
-/**
-* The base directory for synced data.
-*
-* NOTE: This is currently pointing directly to .tbd/data-sync/ which is WRONG
-* per the spec. The correct path should be via the worktree:
-*   .tbd/data-sync-worktree/.tbd/data-sync/
-*
-* TODO(tbd-208): Update this to use the worktree path once worktree
-* management is implemented.
-*/
-const DATA_SYNC_DIR = join(TBD_DIR, DATA_SYNC_DIR_NAME);
-/**
-* The correct path for synced data via worktree (per spec).
-* Use this once worktree management is implemented.
-*/
-const DATA_SYNC_DIR_VIA_WORKTREE = join(WORKTREE_DIR, TBD_DIR, DATA_SYNC_DIR_NAME);
-/** Issues directory */
-const ISSUES_DIR = join(DATA_SYNC_DIR, "issues");
-/** Mappings directory */
-const MAPPINGS_DIR = join(DATA_SYNC_DIR, "mappings");
-/** Attic directory for conflict resolution */
-const ATTIC_DIR = join(DATA_SYNC_DIR, "attic");
-/** Meta file for schema version */
-const META_FILE = join(DATA_SYNC_DIR, "meta.yml");
-/** The sync branch name */
-const SYNC_BRANCH = "tbd-sync";
-/** The workspaces directory name within .tbd/ */
-const WORKSPACES_DIR_NAME = "workspaces";
-/** Full path to workspaces directory: .tbd/workspaces/ */
-const WORKSPACES_DIR = join(TBD_DIR, WORKSPACES_DIR_NAME);
-/**
-* Get the path to a named workspace directory.
-*
-* Workspaces are stored at: .tbd/workspaces/{name}/
-*
-* @param workspaceName - The name of the workspace (e.g., 'outbox', 'my-feature')
-* @returns Path to the workspace directory
-*/
-function getWorkspaceDir(workspaceName) {
-	return join(WORKSPACES_DIR, workspaceName);
-}
-/**
-* Validate a workspace name.
-*
-* Valid workspace names:
-* - Lowercase alphanumeric characters
-* - Hyphens and underscores allowed
-* - Must not be empty
-* - Must not contain path separators or dots at start
-*
-* @param name - The workspace name to validate
-* @returns true if the name is valid
-*/
-function isValidWorkspaceName(name) {
-	if (!name || name.length === 0) return false;
-	if (name.startsWith(".")) return false;
-	return /^[a-z0-9][a-z0-9_-]*$/.test(name);
-}
-/** Docs directory name within .tbd/ */
-const DOCS_DIR = "docs";
-/** Shortcuts directory name within docs/ */
-const SHORTCUTS_DIR = "shortcuts";
-/** System shortcuts directory name (core docs like skill-baseline.md) */
-const SYSTEM_DIR = "system";
-/** Standard shortcuts directory name (workflow shortcuts) */
-const STANDARD_DIR = "standard";
-/** Guidelines directory name (coding rules and best practices) */
-const GUIDELINES_DIR = "guidelines";
-/** Templates directory name (document templates) */
-const TEMPLATES_DIR = "templates";
-/** Full path to docs directory: .tbd/docs/ */
-const TBD_DOCS_DIR = join(TBD_DIR, DOCS_DIR);
-/** Full path to shortcuts directory: .tbd/docs/shortcuts/ */
-const TBD_SHORTCUTS_DIR = join(TBD_DOCS_DIR, SHORTCUTS_DIR);
-/** Full path to system shortcuts: .tbd/docs/shortcuts/system/ */
-const TBD_SHORTCUTS_SYSTEM = join(TBD_SHORTCUTS_DIR, SYSTEM_DIR);
-/** Full path to standard shortcuts: .tbd/docs/shortcuts/standard/ */
-const TBD_SHORTCUTS_STANDARD = join(TBD_SHORTCUTS_DIR, STANDARD_DIR);
-/** Full path to guidelines: .tbd/docs/guidelines/ (top-level, not under shortcuts) */
-const TBD_GUIDELINES_DIR = join(TBD_DOCS_DIR, GUIDELINES_DIR);
-/** Full path to templates: .tbd/docs/templates/ (top-level, not under shortcuts) */
-const TBD_TEMPLATES_DIR = join(TBD_DOCS_DIR, TEMPLATES_DIR);
-/** Built-in docs source paths (relative to package docs/) */
-const BUILTIN_SHORTCUTS_SYSTEM = join(SHORTCUTS_DIR, SYSTEM_DIR);
-const BUILTIN_SHORTCUTS_STANDARD = join(SHORTCUTS_DIR, STANDARD_DIR);
-/**
-* Default shortcut lookup paths (searched in order, relative to tbd root).
-* Earlier paths take precedence over later paths.
-* Note: Guidelines and templates are now separate top-level directories.
-*/
-const DEFAULT_SHORTCUT_PATHS = [TBD_SHORTCUTS_SYSTEM, TBD_SHORTCUTS_STANDARD];
-/**
-* Default guidelines lookup paths (relative to tbd root).
-*/
-const DEFAULT_GUIDELINES_PATHS = [TBD_GUIDELINES_DIR];
-/**
-* Default template lookup paths (relative to tbd root).
-*/
-const DEFAULT_TEMPLATE_PATHS = [TBD_TEMPLATES_DIR];
-/**
-* Error thrown when worktree is missing and fallback is not allowed.
-* Defined inline to avoid circular dependency with errors.ts.
-*/
-var WorktreeMissingError$1 = class extends Error {
-	constructor(message = "Worktree not found at .tbd/data-sync-worktree/. Run 'tbd doctor --fix' to repair.") {
-		super(message);
-		this.name = "WorktreeMissingError";
-	}
-};
-/**
-* Cache for resolved data sync directory.
-* Reset when baseDir changes.
-*/
-let _resolvedDataSyncDir = null;
-let _resolvedBaseDir = null;
-let _resolvedAllowFallback = null;
-/**
-* Resolve the actual data sync directory path.
-*
-* This function detects whether we're running with a git worktree
-* (production) or in a test environment without worktree.
-*
-* Order of preference:
-* 1. Worktree path if worktree exists: .tbd/data-sync-worktree/.tbd/data-sync/
-* 2. Direct path as fallback (only if allowFallback: true)
-*
-* @param baseDir - The tbd root directory (from requireInit or findTbdRoot)
-* @param options - Options for path resolution
-* @returns Resolved data sync directory path
-* @throws WorktreeMissingError if worktree missing and allowFallback is false
-*
-* See: plan-2026-01-28-sync-worktree-recovery-and-hardening.md
-*/
-async function resolveDataSyncDir(baseDir, options) {
-	const allowFallback = options?.allowFallback ?? true;
-	if (_resolvedDataSyncDir && _resolvedBaseDir === baseDir && _resolvedAllowFallback === allowFallback) return _resolvedDataSyncDir;
-	const worktreePath = join(baseDir, DATA_SYNC_DIR_VIA_WORKTREE);
-	const directPath = join(baseDir, DATA_SYNC_DIR);
-	try {
-		await access(worktreePath);
-		_resolvedDataSyncDir = worktreePath;
-		_resolvedBaseDir = baseDir;
-		_resolvedAllowFallback = allowFallback;
-		return worktreePath;
-	} catch {
-		if (!allowFallback) throw new WorktreeMissingError$1();
-		if (process.env.DEBUG || process.env.TBD_DEBUG) console.warn("[tbd:paths] resolveDataSyncDir: worktree not found, falling back to direct path");
-		_resolvedDataSyncDir = directPath;
-		_resolvedBaseDir = baseDir;
-		_resolvedAllowFallback = allowFallback;
-		return directPath;
-	}
-}
-/**
-* Resolve attic directory path.
-*/
-async function resolveAtticDir(baseDir, options) {
-	return join(await resolveDataSyncDir(baseDir, options), "attic");
-}
-/**
-* Characters per token ratio for estimating token counts.
-*
-* Based on research of OpenAI (tiktoken) and Claude tokenizers:
-* - Pure English prose: ~4-5 chars/token
-* - Code and symbols: ~3 chars/token
-* - Mixed markdown/code docs: ~3.5 chars/token
-*
-* We use 3.5 as our docs are markdown with code examples.
-* This provides ~15-20% accuracy, sufficient for cost estimation.
-*/
-const CHARS_PER_TOKEN = 3.5;
-
-//#endregion
-//#region src/lib/tbd-format.ts
-/**
-* tbd Directory Format Versioning
-* ================================
-*
-* This file is the SINGLE SOURCE OF TRUTH for .tbd/ directory format versions.
-*
-* WHEN TO BUMP THE FORMAT VERSION:
-* - Bump when changes REQUIRE migration (deleting files, changing formats, moving files)
-* - **Bump when changing config schema** (adding, removing, or modifying fields)
-* - Do NOT bump for additive changes that don't affect config.yml (new directories, etc.)
-*
-* HOW TO ADD A NEW FORMAT VERSION:
-* 1. Add entry to FORMAT_HISTORY with detailed description
-* 2. Implement migrate_fXX_to_fYY() function
-* 3. Add case to migrateToLatest()
-* 4. Update CURRENT_FORMAT
-* 5. Add tests for the migration path
-*
-* FORWARD COMPATIBILITY POLICY:
-* ConfigSchema uses Zod's strip() mode, which discards unknown fields. To prevent
-* data loss when users mix tbd versions:
-*
-* 1. When changing config schema, bump the format version (e.g., f03 → f04)
-* 2. config.ts checks format compatibility via isCompatibleFormat()
-* 3. Older tbd versions will error with "format 'fXX' is from a newer tbd version"
-* 4. The error tells users to upgrade: npm install -g get-tbd@latest
-*
-* This ensures older versions fail fast rather than silently corrupting config.
-* See ConfigSchema in schemas.ts and checkFormatCompatibility() in config.ts.
-*/
-/**
-* Current format version.
-* Bump this ONLY for breaking changes that require migration.
-*/
-const CURRENT_FORMAT = "f03";
-/**
-* Initial format version for configs that don't have tbd_format field.
-*/
-const INITIAL_FORMAT = "f01";
-/**
-* Complete history of format versions with their changes.
-* This serves as documentation and enables version detection.
-*/
-const FORMAT_HISTORY = {
-	f01: {
-		introduced: "0.1.0",
-		description: "Initial format",
-		structure: {
-			"config.yml": "Project configuration",
-			"state.yml": "Local state (gitignored)",
-			"docs/": "Documentation cache (gitignored)",
-			"issues/": "Issue YAML files"
-		}
-	},
-	f02: {
-		introduced: "0.1.5",
-		description: "Adds configurable doc_cache",
-		changes: [
-			"Added doc_cache: key to config.yml for configurable doc sources",
-			"Added settings.doc_auto_sync_hours for automatic doc refresh",
-			"Added last_doc_sync_at to state.yml for tracking sync time"
-		],
-		migration: "Populates default doc_cache config from bundled docs"
-	},
-	f03: {
-		introduced: "0.1.6",
-		description: "Consolidates docs_cache config structure",
-		changes: [
-			"Consolidated doc_cache: and docs: into single docs_cache: key",
-			"Moved doc_cache: -> docs_cache.files:",
-			"Moved docs.paths: -> docs_cache.lookup_path:",
-			"Removed separate docs: key"
-		],
-		migration: "Migrates old config keys to new docs_cache structure"
-	}
-};
-/**
-* Migrate from f01 to f02.
-* - Adds tbd_format field
-* - Adds doc_auto_sync_hours setting (default: 24)
-* - doc_cache will be populated separately during setup (requires file system access)
-*/
-function migrate_f01_to_f02(config) {
-	const changes = [];
-	const migrated = { ...config };
-	migrated.tbd_format = "f02";
-	changes.push("Added tbd_format: f02");
-	migrated.settings ??= {};
-	if (migrated.settings.doc_auto_sync_hours === void 0) {
-		migrated.settings.doc_auto_sync_hours = 24;
-		changes.push("Added settings.doc_auto_sync_hours: 24");
-	}
-	return {
-		config: migrated,
-		fromFormat: "f01",
-		toFormat: "f02",
-		changed: changes.length > 0,
-		changes
-	};
-}
-/**
-* Migrate from f02 to f03.
-* - Consolidates doc_cache: and docs: into docs_cache:
-* - Moves doc_cache: -> docs_cache.files:
-* - Moves docs.paths: -> docs_cache.lookup_path:
-* - Removes separate docs: and doc_cache: keys
-*/
-function migrate_f02_to_f03(config) {
-	const changes = [];
-	const migrated = { ...config };
-	migrated.tbd_format = "f03";
-	changes.push("Updated tbd_format: f03");
-	migrated.docs_cache ??= {};
-	if (migrated.doc_cache && Object.keys(migrated.doc_cache).length > 0) {
-		migrated.docs_cache.files = { ...migrated.doc_cache };
-		changes.push("Moved doc_cache: -> docs_cache.files:");
-		delete migrated.doc_cache;
-	}
-	if (migrated.docs?.paths && migrated.docs.paths.length > 0) {
-		migrated.docs_cache.lookup_path = [...migrated.docs.paths];
-		changes.push("Moved docs.paths: -> docs_cache.lookup_path:");
-	}
-	if (migrated.docs) {
-		delete migrated.docs;
-		changes.push("Removed docs: key");
-	}
-	return {
-		config: migrated,
-		fromFormat: "f02",
-		toFormat: "f03",
-		changed: changes.length > 0,
-		changes
-	};
-}
-/**
-* Detect the format version of a config.
-* Returns INITIAL_FORMAT ('f01') if no tbd_format field is present.
-*/
-function detectFormat(config) {
-	const format = config.tbd_format;
-	if (!format) return INITIAL_FORMAT;
-	if (format in FORMAT_HISTORY) return format;
-	return CURRENT_FORMAT;
-}
-/**
-* Check if a config needs migration.
-*/
-function needsMigration(config) {
-	return detectFormat(config) !== CURRENT_FORMAT;
-}
-/**
-* Migrate a config to the latest format version.
-*
-* This function applies all necessary migrations in sequence.
-* It does NOT populate doc_cache - that requires file system access
-* and should be done separately during setup.
-*
-* @param config - The raw config to migrate
-* @returns Migration result with the migrated config and change log
-*/
-function migrateToLatest(config) {
-	const fromFormat = detectFormat(config);
-	if (fromFormat === CURRENT_FORMAT) return {
-		config,
-		fromFormat,
-		toFormat: CURRENT_FORMAT,
-		changed: false,
-		changes: []
-	};
-	let current = config;
-	let currentFormat = fromFormat;
-	const allChanges = [];
-	if (currentFormat === "f01") {
-		const result = migrate_f01_to_f02(current);
-		current = result.config;
-		currentFormat = "f02";
-		allChanges.push(...result.changes);
-	}
-	if (currentFormat === "f02") {
-		const result = migrate_f02_to_f03(current);
-		current = result.config;
-		currentFormat = "f03";
-		allChanges.push(...result.changes);
-	}
-	return {
-		config: current,
-		fromFormat,
-		toFormat: currentFormat,
-		changed: allChanges.length > 0,
-		changes: allChanges
-	};
-}
-/**
-* Check if a format version is compatible with the current tbd version.
-* Future format versions are considered incompatible (would need tbd upgrade).
-*/
-function isCompatibleFormat(format) {
-	const formatVersions = Object.keys(FORMAT_HISTORY);
-	const currentIndex = formatVersions.indexOf(CURRENT_FORMAT);
-	const checkIndex = formatVersions.indexOf(format);
-	if (checkIndex === -1) return false;
-	return checkIndex <= currentIndex;
-}
-
-//#endregion
-//#region src/file/config.ts
-/**
-* Config file operations.
-*
-* Config is stored at .tbd/config.yml and contains project-level settings.
-*
-* ⚠️ FORMAT VERSIONING: See tbd-format.ts for version history and migration rules.
-*
-* See: tbd-design.md §2.2.2 Config File
-*/
-/**
-* Error thrown when the config format version is from a newer tbd version.
-* This prevents older tbd versions from silently stripping new config fields.
-*/
-var IncompatibleFormatError = class extends Error {
-	constructor(foundFormat, supportedFormat) {
-		super(`Config format '${foundFormat}' is from a newer tbd version.\nThis tbd version supports up to format '${supportedFormat}'.\nPlease upgrade tbd: npm install -g get-tbd@latest`);
-		this.foundFormat = foundFormat;
-		this.supportedFormat = supportedFormat;
-		this.name = "IncompatibleFormatError";
-	}
-};
-/**
-* Check if config format is compatible, throw if not.
-* This prevents older tbd versions from silently stripping fields added by newer versions.
-*/
-function checkFormatCompatibility(data) {
-	const format = data.tbd_format;
-	if (format && !isCompatibleFormat(format)) throw new IncompatibleFormatError(format, CURRENT_FORMAT);
-}
-/**
-* Create default config for a new project.
-* @param prefix - Required: the project prefix for display IDs (e.g., "proj", "myapp")
-*/
-function createDefaultConfig(version, prefix) {
-	return ConfigSchema.parse({
-		tbd_format: CURRENT_FORMAT,
-		tbd_version: version,
-		sync: {
-			branch: SYNC_BRANCH,
-			remote: "origin"
-		},
-		display: { id_prefix: prefix },
-		settings: {
-			auto_sync: false,
-			doc_auto_sync_hours: 24
-		}
-	});
-}
-/**
-* Initialize a new config file with default settings.
-* Creates .tbd directory if it doesn't exist.
-* @param prefix - Required: the project prefix for display IDs (e.g., "proj", "myapp")
-*/
-async function initConfig(baseDir, version, prefix) {
-	await mkdir(join(baseDir, ".tbd"), { recursive: true });
-	const config = createDefaultConfig(version, prefix);
-	await writeConfig(baseDir, config);
-	return config;
-}
-/**
-* Read config from file with automatic migration if needed.
-*
-* ⚠️ FORMAT VERSIONING: See tbd-format.ts for version history and migration rules.
-*
-* @throws {IncompatibleFormatError} If config is from a newer tbd version.
-* @throws If config file doesn't exist or is invalid.
-*/
-async function readConfig(baseDir) {
-	const data = parse(await readFile(join(baseDir, CONFIG_FILE), "utf-8"));
-	checkFormatCompatibility(data);
-	if (needsMigration(data)) {
-		const result = migrateToLatest(data);
-		return ConfigSchema.parse(result.config);
-	}
-	return ConfigSchema.parse(data);
-}
-/**
-* Read config from file, returning migration info if a migration was applied.
-* Use this when you need to know if the config was migrated.
-*
-* @throws {IncompatibleFormatError} If config is from a newer tbd version.
-*/
-async function readConfigWithMigration(baseDir) {
-	const data = parse(await readFile(join(baseDir, CONFIG_FILE), "utf-8"));
-	checkFormatCompatibility(data);
-	if (needsMigration(data)) {
-		const result = migrateToLatest(data);
-		return {
-			config: ConfigSchema.parse(result.config),
-			migrated: result.changed,
-			changes: result.changes
-		};
-	}
-	return {
-		config: ConfigSchema.parse(data),
-		migrated: false,
-		changes: []
-	};
-}
-/**
-* Write config to file with explanatory comments.
-*/
-async function writeConfig(baseDir, config) {
-	const configPath = join(baseDir, CONFIG_FILE);
-	let content = stringifyYaml(sortKeys(config, CONFIG_FIELD_ORDER), {
-		lineWidth: 0,
-		sortMapEntries: false
-	});
-	if (config.docs_cache && Object.keys(config.docs_cache).length > 0) content = content.replace("docs_cache:", "# Documentation cache configuration.\n# files: Maps destination paths (relative to .tbd/docs/) to source locations.\n#   Sources can be:\n#   - internal: prefix for bundled docs (e.g., \"internal:shortcuts/standard/code-review-and-commit.md\")\n#   - Full URL for external docs (e.g., \"https://raw.githubusercontent.com/org/repo/main/file.md\")\n# lookup_path: Search paths for doc lookup (like shell $PATH). Earlier paths take precedence.\n#\n# To sync docs: tbd sync --docs\n# To check status: tbd sync --status\n#\n# Auto-sync: Docs are automatically synced when stale (default: every 24 hours).\n# Configure with settings.doc_auto_sync_hours (0 = disabled).\ndocs_cache:");
-	await writeFile(configPath, content);
-}
-/**
-* Check if tbd is properly initialized in the given directory.
-* Returns true only if .tbd/config.yml exists (not just a .tbd/ directory).
-*
-* This prevents spurious .tbd/ directories (e.g., containing only state.yml
-* created by a bug) from being mistaken for tbd roots. A valid tbd root
-* always has config.yml created during `tbd init`.
-*/
-async function hasTbdDir(dir) {
-	const configPath = join(dir, CONFIG_FILE);
-	try {
-		await access(configPath);
-		return true;
-	} catch {
-		return false;
-	}
-}
-/**
-* Find the tbd repository root by walking up the directory tree.
-* Similar to how git finds .git/ directories.
-*
-* @param startDir - Directory to start searching from
-* @returns The tbd root directory path, or null if not found
-*/
-async function findTbdRoot(startDir) {
-	let currentDir = startDir;
-	const { root } = parse$1(startDir);
-	while (currentDir !== root) {
-		if (await hasTbdDir(currentDir)) return currentDir;
-		currentDir = dirname(currentDir);
-	}
-	if (await hasTbdDir(root)) return root;
-	return null;
-}
-/**
-* Check if tbd is initialized in the given directory or any parent directory.
-* Walks up the directory tree looking for .tbd/.
-*/
-async function isInitialized(baseDir) {
-	return await findTbdRoot(baseDir) !== null;
-}
-/**
-* Read local state from .tbd/state.yml
-* Returns empty state if file doesn't exist.
-*/
-async function readLocalState(baseDir) {
-	const statePath = join(baseDir, STATE_FILE);
-	try {
-		const data = parse(await readFile(statePath, "utf-8"));
-		return LocalStateSchema.parse(data ?? {});
-	} catch {
-		return {};
-	}
-}
-/**
-* Write local state to .tbd/state.yml
-*
-* Uses `atomically` for safe writes (atomic rename, auto parent-dir creation).
-* However, we intentionally guard against .tbd/ not existing: `atomically`
-* would auto-create it, which is wrong if baseDir is a subdirectory rather
-* than the true tbd root. Only `tbd init` (via initConfig) should create .tbd/.
-*/
-async function writeLocalState(baseDir, state) {
-	const tbdDir = join(baseDir, ".tbd");
-	try {
-		await access(tbdDir);
-	} catch {
-		throw new Error(`Cannot write state: .tbd/ directory does not exist at ${baseDir}. Run 'tbd init' first or ensure the correct tbd root is being used.`);
-	}
-	await writeFile(join(baseDir, STATE_FILE), stringifyYaml(sortKeys(state, LOCAL_STATE_FIELD_ORDER), {
-		lineWidth: 0,
-		sortMapEntries: false
-	}));
-}
-/**
-* Update specific fields in local state (merge with existing).
-*/
-async function updateLocalState(baseDir, updates) {
-	const updated = {
-		...await readLocalState(baseDir),
-		...updates
-	};
-	await writeLocalState(baseDir, updated);
-	return updated;
-}
-/**
-* Check if the user has seen the welcome message.
-*/
-async function hasSeenWelcome(baseDir) {
-	return (await readLocalState(baseDir)).welcome_seen === true;
-}
-/**
-* Mark the welcome message as seen.
-*/
-async function markWelcomeSeen(baseDir) {
-	await updateLocalState(baseDir, { welcome_seen: true });
-}
-
 //#endregion
 //#region src/cli/lib/errors.ts
 /**
@@ -5312,6 +4682,9 @@ async function importFromWorkspace(tbdRoot, dataSyncDir, options) {
 	const sourceMapping = await loadIdMapping(sourceDir);
 	const targetMapping = await loadIdMapping(dataSyncDir);
 	for (const [shortId, ulid] of sourceMapping.shortToUlid) if (!targetMapping.shortToUlid.has(shortId)) addIdMapping(targetMapping, ulid, shortId);
+	const reconcileResult = reconcileMappings(sourceIssues.map((i) => i.id), targetMapping, sourceMapping);
+	if (reconcileResult.recovered.length > 0) log.info(`Recovered ${reconcileResult.recovered.length} ID mapping(s) from workspace`);
+	if (reconcileResult.created.length > 0) log.info(`Created ${reconcileResult.created.length} new ID mapping(s) for imported issues`);
 	await saveIdMapping(dataSyncDir, targetMapping);
 	let cleared = false;
 	if (shouldClear && imported > 0) {
@@ -5466,8 +4839,8 @@ var SyncHandler = class extends BaseCommand {
 		else if (options.push) await this.pushChanges(syncBranch, remote);
 		else await this.fullSync(syncBranch, remote, {
 			force: options.force,
-			noAutoSave: options.noAutoSave,
-			noOutbox: options.noOutbox
+			autoSave: options.autoSave,
+			outbox: options.outbox
 		});
 	}
 	/**
@@ -5770,6 +5143,24 @@ var SyncHandler = class extends BaseCommand {
 					await git("-C", worktreePath, "merge", `${remote}/${syncBranch}`, "-m", "tbd sync: merge remote changes");
 					this.output.debug(`Merged ${behindCommits} commit(s) from remote`);
 					if (headBeforeMerge) await this.showGitLogDebug("Commits received", `${headBeforeMerge}..${syncBranch}`);
+					const postMergeIssues = await listIssues(this.dataSyncDir);
+					const postMergeMapping = await loadIdMapping(this.dataSyncDir);
+					let historicalMapping;
+					try {
+						const remoteIdsContent = await git("show", `${remote}/${syncBranch}:${DATA_SYNC_DIR}/mappings/ids.yml`);
+						if (remoteIdsContent) historicalMapping = parseIdMappingFromYaml(remoteIdsContent);
+					} catch {}
+					const reconcileResult = reconcileMappings(postMergeIssues.map((i) => i.id), postMergeMapping, historicalMapping);
+					const totalReconciled = reconcileResult.created.length + reconcileResult.recovered.length;
+					if (totalReconciled > 0) {
+						await saveIdMapping(this.dataSyncDir, postMergeMapping);
+						await git("-C", worktreePath, "add", "-A");
+						try {
+							await git("-C", worktreePath, "commit", "--no-verify", "-m", `tbd sync: reconcile ${totalReconciled} missing ID mapping(s)`);
+						} catch {}
+						if (reconcileResult.recovered.length > 0) this.output.debug(`Recovered ${reconcileResult.recovered.length} ID mapping(s) from history`);
+						if (reconcileResult.created.length > 0) this.output.debug(`Created ${reconcileResult.created.length} new ID mapping(s) (no history available)`);
+					}
 				} catch {
 					this.output.info(`Merge conflict, attempting file-level resolution`);
 					const localIssues = await listIssues(this.dataSyncDir);
@@ -5782,18 +5173,29 @@ var SyncHandler = class extends BaseCommand {
 					} catch {
 						this.output.debug(`Issue ${localIssue.id} not on remote, keeping local`);
 					}
+					let conflictRemoteMapping;
 					try {
 						const remoteIdsContent = await git("show", `${remote}/${syncBranch}:${DATA_SYNC_DIR}/mappings/ids.yml`);
 						if (remoteIdsContent) {
+							conflictRemoteMapping = parseIdMappingFromYaml(remoteIdsContent);
 							const localMapping = await loadIdMapping(this.dataSyncDir);
-							const remoteMapping = parseIdMappingFromYaml(remoteIdsContent);
-							const mergedMapping = mergeIdMappings(localMapping, remoteMapping);
+							const mergedMapping = mergeIdMappings(localMapping, conflictRemoteMapping);
 							await saveIdMapping(this.dataSyncDir, mergedMapping);
-							this.output.debug(`Merged ID mappings: ${localMapping.shortToUlid.size} local + ${remoteMapping.shortToUlid.size} remote = ${mergedMapping.shortToUlid.size} total`);
+							this.output.debug(`Merged ID mappings: ${localMapping.shortToUlid.size} local + ${conflictRemoteMapping.shortToUlid.size} remote = ${mergedMapping.shortToUlid.size} total`);
 						}
 					} catch (error) {
 						this.output.debug(`Could not merge ids.yml: ${error.message}`);
 					}
+					{
+						const allIssues = await listIssues(this.dataSyncDir);
+						const currentMapping = await loadIdMapping(this.dataSyncDir);
+						const reconcileResult = reconcileMappings(allIssues.map((i) => i.id), currentMapping, conflictRemoteMapping);
+						if (reconcileResult.created.length + reconcileResult.recovered.length > 0) {
+							await saveIdMapping(this.dataSyncDir, currentMapping);
+							if (reconcileResult.recovered.length > 0) this.output.debug(`Recovered ${reconcileResult.recovered.length} ID mapping(s) from remote`);
+							if (reconcileResult.created.length > 0) this.output.debug(`Created ${reconcileResult.created.length} new ID mapping(s) after conflict resolution`);
+						}
+					}
 					await git("-C", worktreePath, "add", "-A");
 					const conflictCheck = await git("-C", worktreePath, "diff", "--cached", "-S<<<<<<< ", "--name-only");
 					if (conflictCheck.trim()) {
@@ -5857,7 +5259,7 @@ var SyncHandler = class extends BaseCommand {
 				this.output.error(`Push failed: ${displayError}`);
 				console.log(`  ${aheadCommits} commit(s) not pushed to remote.`);
 			});
-			if (errorType === "permanent" && !options.noAutoSave) await this.handlePermanentFailure();
+			if (errorType === "permanent" && options.autoSave !== false) await this.handlePermanentFailure();
 			else if (!this.ctx.json) if (errorType === "transient") {
 				console.log("");
 				console.log("  This appears to be a temporary issue. Options:");
@@ -5872,7 +5274,7 @@ var SyncHandler = class extends BaseCommand {
 			}
 			return;
 		}
-		if (!options.noOutbox) await this.maybeImportOutbox(syncBranch, remote);
+		if (options.outbox !== false) await this.maybeImportOutbox(syncBranch, remote);
 		this.output.data({
 			summary,
 			conflicts: conflicts.length
@@ -6895,6 +6297,7 @@ var DoctorHandler = class extends BaseCommand {
 		healthChecks.push(await this.checkIdMappingDuplicates(options.fix));
 		healthChecks.push(await this.checkTempFiles(options.fix));
 		healthChecks.push(this.checkIssueValidity(this.issues));
+		healthChecks.push(await this.checkMissingMappings(options.fix));
 		healthChecks.push(await this.checkWorktree(options.fix));
 		healthChecks.push(await this.checkDataLocation(options.fix));
 		healthChecks.push(await this.checkLocalSyncBranch());
@@ -7119,7 +6522,7 @@ var DoctorHandler = class extends BaseCommand {
 			status: "ok"
 		};
 		if (fix && !this.checkDryRun("Fix duplicate ID mapping keys")) try {
-			const { loadIdMapping, saveIdMapping } = await import("./id-mapping-BqSnxlxk.mjs");
+			const { loadIdMapping, saveIdMapping } = await import("./id-mapping-0-R0X8zb.mjs");
 			const mapping = await loadIdMapping(this.dataSyncDir);
 			await saveIdMapping(this.dataSyncDir, mapping);
 			return {
@@ -7238,6 +6641,63 @@ var DoctorHandler = class extends BaseCommand {
 			suggestion: "Manually fix or delete invalid issue files"
 		};
 	}
+	/**
+	* Check for issues that have no short ID mapping in ids.yml.
+	*
+	* This can happen when a git merge brings in issue files (e.g., from
+	* a feature branch with outbox issues) without the corresponding
+	* ids.yml entries. Without a mapping, any command that tries to
+	* display the issue ID will crash.
+	*
+	* With --fix, creates missing mappings automatically.
+	*/
+	async checkMissingMappings(fix) {
+		if (this.issues.length === 0) return {
+			name: "ID mapping coverage",
+			status: "ok"
+		};
+		const { loadIdMapping, saveIdMapping, reconcileMappings } = await import("./id-mapping-0-R0X8zb.mjs");
+		const mapping = await loadIdMapping(this.dataSyncDir);
+		const missingIds = [];
+		for (const issue of this.issues) {
+			const ulid = extractUlidFromInternalId(issue.id);
+			if (!mapping.ulidToShort.has(ulid)) missingIds.push(issue.id);
+		}
+		if (missingIds.length === 0) return {
+			name: "ID mapping coverage",
+			status: "ok"
+		};
+		if (fix && !this.checkDryRun("Create missing ID mappings")) {
+			const { parseIdMappingFromYaml } = await import("./id-mapping-0-R0X8zb.mjs");
+			let historicalMapping;
+			try {
+				const syncBranch = (await import("./config-CB1tcqTZ.mjs").then((m) => m.readConfig(this.cwd))).sync.branch;
+				const priorContent = await git("log", "-1", "--format=%H", syncBranch, "--", `${DATA_SYNC_DIR}/mappings/ids.yml`);
+				if (priorContent.trim()) {
+					const idsContent = await git("show", `${priorContent.trim()}:${DATA_SYNC_DIR}/mappings/ids.yml`);
+					if (idsContent) historicalMapping = parseIdMappingFromYaml(idsContent);
+				}
+			} catch {}
+			const result = reconcileMappings(missingIds, mapping, historicalMapping);
+			await saveIdMapping(this.dataSyncDir, mapping);
+			const parts = [];
+			if (result.recovered.length > 0) parts.push(`recovered ${result.recovered.length} from git history`);
+			if (result.created.length > 0) parts.push(`created ${result.created.length} new`);
+			return {
+				name: "ID mapping coverage",
+				status: "ok",
+				message: parts.join(", ")
+			};
+		}
+		return {
+			name: "ID mapping coverage",
+			status: "error",
+			message: `${missingIds.length} issue(s) without short ID mapping`,
+			details: missingIds.map((id) => `${id} (no short ID)`),
+			fixable: true,
+			suggestion: "Run: tbd doctor --fix to create missing mappings"
+		};
+	}
 	async checkClaudeSkill() {
 		const claudePaths = getClaudePaths(this.cwd);
 		try {
@@ -10939,6 +10399,9 @@ var SetupDefaultHandler = class extends BaseCommand {
 		]);
 		if (tbdGitignoreResult.created) console.log(`  ${colors.success("✓")} Created .tbd/.gitignore`);
 		else if (tbdGitignoreResult.added.length > 0) console.log(`  ${colors.success("✓")} Updated .tbd/.gitignore with new patterns`);
+		const gitattributesResult = await ensureGitignorePatterns(join(projectDir, TBD_DIR, ".gitattributes"), ["# Protect ID mappings from merge deletion (always keep all rows)", "**/mappings/ids.yml merge=union"]);
+		if (gitattributesResult.created) console.log(`  ${colors.success("✓")} Created .tbd/.gitattributes (merge protection)`);
+		else if (gitattributesResult.added.length > 0) console.log(`  ${colors.success("✓")} Updated .tbd/.gitattributes (merge protection)`);
 		console.log("Checking integrations...");
 		await new SetupAutoHandler(this.cmd).run(projectDir);
 		console.log("");
@@ -11069,6 +10532,9 @@ Example:
 		]);
 		if (tbdGitignoreResult.created) console.log(`  ${colors.success("✓")} Created .tbd/.gitignore`);
 		else if (tbdGitignoreResult.added.length > 0) console.log(`  ${colors.success("✓")} Updated .tbd/.gitignore`);
+		const gitattributesResult = await ensureGitignorePatterns(join(cwd, TBD_DIR, ".gitattributes"), ["# Protect ID mappings from merge deletion (always keep all rows)", "**/mappings/ids.yml merge=union"]);
+		if (gitattributesResult.created) console.log(`  ${colors.success("✓")} Created .tbd/.gitattributes (merge protection)`);
+		else if (gitattributesResult.added.length > 0) console.log(`  ${colors.success("✓")} Updated .tbd/.gitattributes (merge protection)`);
 		try {
 			await initWorktree(cwd);
 			const health = await checkWorktreeHealth(cwd);
@@ -11441,7 +10907,7 @@ const workspaceCommand = new Command("workspace").description("Manage workspaces
 function createProgram() {
 	const program = new Command().name("tbd").description("Git-native issue tracking for AI agents and humans").version(VERSION, "--version", "Show version number").helpOption("--help", "Display help for command").showHelpAfterError("(add --help for additional information)");
 	configureColoredHelp(program);
-	program.option("--dry-run", "Show what would be done without making changes").option("--verbose", "Enable verbose output").option("--quiet", "Suppress non-essential output").option("--json", "Output as JSON").option("--color <when>", "Colorize output: auto, always, never", "auto").option("--non-interactive", "Disable all prompts, fail if input required").option("--yes", "Assume yes to confirmation prompts").option("--no-sync", "Skip automatic sync after write operations").option("--debug", "Show internal IDs alongside public IDs for debugging");
+	program.option("--dry-run", "Show what would be done without making changes").option("--verbose", "Enable verbose output").option("--quiet", "Suppress non-essential output").option("--json", "Output as JSON").option("--color <when>", "Colorize output: auto, always, never", "auto").option("--no-sync", "Skip automatic sync after write operations").option("--debug", "Show internal IDs alongside public IDs for debugging");
 	program.commandsGroup("Documentation:");
 	program.addCommand(readmeCommand);
 	program.addCommand(primeCommand);