get-tbd 0.1.13 → 0.1.15

package/dist/bin.mjs

@@ -6638,8 +6638,16 @@ const IssueId = stringType().regex(/^is-[0-9a-z]{26}$/);
 * Short ID: 1+ base36 characters used for external/display IDs.
 * Typically 4 chars for new IDs (e.g., a7k2, b3m9).
 * Imports may preserve longer numeric IDs (e.g., "100" from "tbd-100").
+* Legacy imports may include dots (e.g., "208.1" from hierarchical numbering).
+* Imports may include dashes/underscores (e.g., "stat-in_progress" from JSONL).
 */
-const ShortId = stringType().regex(/^[0-9a-z]+$/);
+const ShortId = stringType().regex(/^[0-9a-z._-]+$/);
+/**
+* ULID: 26 lowercase alphanumeric characters.
+* Used in internal IDs and ID mappings.
+* Example: 01hx5zzkbkactav9wevgemmvrz
+*/
+const Ulid = stringType().regex(/^[0-9a-z]{26}$/);
 /**
 * External Issue ID input: accepts {prefix}-{short} or just {short}.
 * Examples: bd-a7k2, a7k2, bd-100, 100
@@ -6744,15 +6752,15 @@ const GitRemoteName = stringType().min(1).max(255).regex(/^[a-zA-Z0-9._-]+$/, "I
 /**
 * Doc cache configuration - maps destination paths to source locations.
 *
-* Keys are destination paths relative to .tbd/docs/ (e.g., "shortcuts/standard/commit-code.md")
+* Keys are destination paths relative to .tbd/docs/ (e.g., "shortcuts/standard/code-review-and-commit.md")
 * Values are source locations:
-* - internal: prefix for bundled docs (e.g., "internal:shortcuts/standard/commit-code.md")
+* - internal: prefix for bundled docs (e.g., "internal:shortcuts/standard/code-review-and-commit.md")
 * - Full URL for external docs (e.g., "https://raw.githubusercontent.com/org/repo/main/file.md")
 *
 * Example:
 * ```yaml
 * doc_cache:
-*   shortcuts/standard/commit-code.md: internal:shortcuts/standard/commit-code.md
+*   shortcuts/standard/code-review-and-commit.md: internal:shortcuts/standard/code-review-and-commit.md
 *   shortcuts/custom/my-shortcut.md: https://raw.githubusercontent.com/org/repo/main/shortcuts/my-shortcut.md
 * ```
 */
@@ -6835,77 +6843,12 @@ const AtticEntrySchema = objectType({
 		remote_updated_at: Timestamp
 	})
 });
-
-//#endregion
-//#region src/utils/markdown-utils.ts
 /**
-* Markdown utilities for processing markdown content.
-*
-* Uses gray-matter for consistent frontmatter parsing across the codebase.
-*/
-/**
-* Normalize line endings to LF.
-*/
-function normalizeLineEndings(content) {
-	return content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
-}
-/**
-* Parse markdown content into frontmatter and body.
-* Handles both LF and CRLF line endings.
-*
-* @returns Object with frontmatter (null if none) and body
+* ID mapping YAML file schema for ids.yml.
+* Maps short IDs to ULIDs.
+* Format: { "a7k2": "01hx5zzkbkactav9wevgemmvrz", ... }
 */
-function parseMarkdown(content) {
-	const normalized = normalizeLineEndings(content);
-	if (!matter.test(normalized)) return {
-		frontmatter: null,
-		body: content
-	};
-	try {
-		const parsed = matter(normalized);
-		const data = parsed.data;
-		let frontmatter = null;
-		if (data && Object.keys(data).length > 0) {
-			const lines = [];
-			for (const [key, value] of Object.entries(data)) if (Array.isArray(value)) {
-				lines.push(`${key}:`);
-				for (const item of value) lines.push(`  - ${String(item)}`);
-			} else if (typeof value === "object" && value !== null) {
-				lines.push(`${key}:`);
-				for (const [subKey, subValue] of Object.entries(value)) lines.push(`  ${subKey}: ${String(subValue)}`);
-			} else lines.push(`${key}: ${String(value)}`);
-			frontmatter = lines.join("\n");
-		} else frontmatter = "";
-		const body = parsed.content.replace(/^\n+/, "");
-		return {
-			frontmatter,
-			body
-		};
-	} catch {
-		return {
-			frontmatter: null,
-			body: content
-		};
-	}
-}
-/**
-* Strip YAML frontmatter from markdown content.
-* Returns the body content without frontmatter, with leading newlines trimmed.
-* Handles both LF and CRLF line endings.
-*/
-function stripFrontmatter(content) {
-	return parseMarkdown(content).body;
-}
-/**
-* Insert content after YAML frontmatter.
-* If no frontmatter exists, prepends the content.
-* Content is inserted directly after ---. Include leading newlines in toInsert if needed.
-*/
-function insertAfterFrontmatter(content, toInsert) {
-	const { frontmatter, body } = parseMarkdown(content);
-	if (frontmatter === null) return toInsert + content;
-	return `${frontmatter ? `---\n${frontmatter}\n---` : "---\n---"}\n${toInsert}\n\n${body}`;
-}
+const IdMappingYamlSchema = recordType(ShortId, Ulid);
 
 //#endregion
 //#region ../../node_modules/.pnpm/yaml@2.8.2/node_modules/yaml/dist/nodes/identity.js
@@ -13557,6 +13500,197 @@ var require_dist$2 = /* @__PURE__ */ __commonJSMin(((exports) => {
 	exports.visitAsync = visit.visitAsync;
 }));
 
+//#endregion
+//#region src/lib/settings.ts
+var import_dist$2 = require_dist$2();
+/**
+* Default line width for YAML serialization.
+* 88 characters is a good balance between readability and avoiding excessive wrapping.
+* (Matches Python's Black formatter default.)
+*/
+const YAML_LINE_WIDTH = 88;
+/**
+* Default string type for YAML serialization.
+* 'PLAIN' means no forced quoting - YAML only quotes when necessary.
+*/
+const YAML_DEFAULT_STRING_TYPE = "PLAIN";
+/**
+* Default key type for YAML serialization.
+* 'PLAIN' means object keys are unquoted unless required.
+*/
+const YAML_DEFAULT_KEY_TYPE = "PLAIN";
+/**
+* Default YAML serialization options for readable output.
+*
+* Design principles:
+* - No forced quoting: YAML only quotes when necessary for special characters
+* - Reasonable line wrapping: 88 chars prevents overly long lines
+* - Plain keys: No unnecessary quotes around object keys
+* - Sorted keys: Deterministic output for diffs and version control
+*/
+const YAML_STRINGIFY_OPTIONS = {
+	lineWidth: YAML_LINE_WIDTH,
+	defaultStringType: YAML_DEFAULT_STRING_TYPE,
+	defaultKeyType: YAML_DEFAULT_KEY_TYPE,
+	sortMapEntries: true
+};
+/**
+* YAML serialization options for compact output (e.g., frontmatter).
+* Uses lineWidth: 0 to prevent wrapping within values.
+*/
+const YAML_STRINGIFY_OPTIONS_COMPACT = {
+	lineWidth: 0,
+	defaultStringType: YAML_DEFAULT_STRING_TYPE,
+	defaultKeyType: YAML_DEFAULT_KEY_TYPE,
+	sortMapEntries: true
+};
+
+//#endregion
+//#region src/utils/yaml-utils.ts
+/**
+* YAML utility functions.
+*
+* Provides centralized YAML parsing and serialization with:
+* - Merge conflict detection for user-editable files
+* - Consistent, readable formatting defaults
+* - Proper handling of special characters (colons, quotes, etc.)
+*
+* IMPORTANT: Always use these utilities instead of raw yaml package functions.
+* This ensures consistent formatting and proper error handling across the codebase.
+*/
+/**
+* Serialize data to YAML with readable formatting.
+*
+* Uses consistent defaults:
+* - No forced quoting (YAML only quotes when necessary)
+* - lineWidth of 88 provides reasonable wrapping for long strings
+* - Plain keys without quotes
+* - Sorted keys for deterministic output
+*
+* @param data - Data to serialize
+* @param options - Optional overrides for default options
+* @returns YAML string
+*/
+function stringifyYaml(data, options) {
+	return (0, import_dist$2.stringify)(data, {
+		...YAML_STRINGIFY_OPTIONS,
+		...options
+	});
+}
+/**
+* Serialize data to YAML without line wrapping (compact mode).
+* Useful for frontmatter where values should stay on single lines.
+*
+* @param data - Data to serialize
+* @returns YAML string with no line wrapping
+*/
+function stringifyYamlCompact(data) {
+	return (0, import_dist$2.stringify)(data, YAML_STRINGIFY_OPTIONS_COMPACT);
+}
+/**
+* Error thrown when YAML content contains unresolved merge conflict markers.
+*/
+var MergeConflictError = class extends Error {
+	constructor(message, filePath) {
+		super(message);
+		this.filePath = filePath;
+		this.name = "MergeConflictError";
+	}
+};
+/**
+* Regex patterns for git merge conflict markers.
+*/
+const CONFLICT_PATTERNS = {
+	start: /^<<<<<<< /m,
+	separator: /^=======/m,
+	end: /^>>>>>>> /m
+};
+/**
+* Check if content contains git merge conflict markers.
+*/
+function hasMergeConflictMarkers(content) {
+	return CONFLICT_PATTERNS.start.test(content) || CONFLICT_PATTERNS.separator.test(content) || CONFLICT_PATTERNS.end.test(content);
+}
+/**
+* Parse YAML content with merge conflict detection.
+*
+* If the content contains merge conflict markers, throws a MergeConflictError
+* with a helpful message instead of a cryptic YAML parse error.
+*
+* @param content - The YAML content to parse
+* @param filePath - Optional file path for error messages
+* @returns Parsed YAML data
+* @throws MergeConflictError if content has conflict markers
+* @throws Error if YAML is invalid for other reasons
+*/
+function parseYamlWithConflictDetection(content, filePath) {
+	if (hasMergeConflictMarkers(content)) throw new MergeConflictError(`File${filePath ? ` in ${filePath}` : ""} contains unresolved git merge conflict markers.\nThis usually happens when 'tbd sync' encountered conflicts that weren't properly resolved.\nTo fix: manually edit the file to resolve conflicts, or run 'tbd doctor --fix'.`, filePath);
+	return (0, import_dist$2.parse)(content);
+}
+
+//#endregion
+//#region src/utils/markdown-utils.ts
+/**
+* Markdown utilities for processing markdown content.
+*
+* Uses gray-matter for parsing and centralized yaml-utils for stringify to ensure
+* proper handling of special YAML characters (colons, quotes, etc.).
+*/
+/**
+* Normalize line endings to LF.
+*/
+function normalizeLineEndings(content) {
+	return content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+/**
+* Parse markdown content into frontmatter and body.
+* Handles both LF and CRLF line endings.
+*
+* @returns Object with frontmatter (null if none) and body
+*/
+function parseMarkdown(content) {
+	const normalized = normalizeLineEndings(content);
+	if (!matter.test(normalized)) return {
+		frontmatter: null,
+		body: content
+	};
+	try {
+		const parsed = matter(normalized);
+		const data = parsed.data;
+		let frontmatter = null;
+		if (data && Object.keys(data).length > 0) frontmatter = stringifyYamlCompact(data).trimEnd();
+		else frontmatter = "";
+		const body = parsed.content.replace(/^\n+/, "");
+		return {
+			frontmatter,
+			body
+		};
+	} catch {
+		return {
+			frontmatter: null,
+			body: content
+		};
+	}
+}
+/**
+* Strip YAML frontmatter from markdown content.
+* Returns the body content without frontmatter, with leading newlines trimmed.
+* Handles both LF and CRLF line endings.
+*/
+function stripFrontmatter(content) {
+	return parseMarkdown(content).body;
+}
+/**
+* Insert content after YAML frontmatter.
+* If no frontmatter exists, prepends the content.
+* Content is inserted directly after ---. Include leading newlines in toInsert if needed.
+*/
+function insertAfterFrontmatter(content, toInsert) {
+	const { frontmatter, body } = parseMarkdown(content);
+	if (frontmatter === null) return toInsert + content;
+	return `${frontmatter ? `---\n${frontmatter}\n---` : "---\n---"}\n${toInsert}\n\n${body}`;
+}
+
 //#endregion
 //#region src/file/parser.ts
 /**
@@ -13577,14 +13711,13 @@ var require_dist$2 = /* @__PURE__ */ __commonJSMin(((exports) => {
 *
 * See: tbd-design.md §2.1 Markdown + YAML Front Matter Format
 */
-var import_dist$2 = require_dist$2();
 /**
 * gray-matter options using the 'yaml' package as engine.
 * This preserves date strings instead of converting them to Date objects.
 */
 const matterOptions = { engines: { yaml: {
 	parse: (str) => (0, import_dist$2.parse)(str),
-	stringify: (obj) => (0, import_dist$2.stringify)(obj)
+	stringify: (obj) => stringifyYaml(obj)
 } } };
 /**
 * Parse a Markdown file with YAML front matter.
@@ -13641,8 +13774,7 @@ function serializeIssue(issue) {
 	for (const key of Object.keys(metadata).sort()) sortedMetadata[key] = metadata[key];
 	const parts = [
 		"---",
-		(0, import_dist$2.stringify)(sortedMetadata, {
-			sortMapEntries: true,
+		stringifyYaml(sortedMetadata, {
 			lineWidth: 0,
 			nullStr: "null"
 		}).trim(),
@@ -13664,7 +13796,7 @@ function serializeIssue(issue) {
 * Package version, derived from git at build time.
 * Format: X.Y.Z for releases, X.Y.Z-dev.N.hash for dev builds.
 */
-const VERSION$1 = "0.1.13";
+const VERSION$1 = "0.1.15";
 
 //#endregion
 //#region src/cli/lib/version.ts
@@ -97476,11 +97608,8 @@ async function readConfigWithMigration(baseDir) {
 */
 async function writeConfig(baseDir, config) {
 	const configPath = join(baseDir, CONFIG_FILE);
-	let content = (0, import_dist$2.stringify)(config, {
-		sortMapEntries: true,
-		lineWidth: 0
-	});
-	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/commit-code.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:");
+	let content = stringifyYaml(config, { lineWidth: 0 });
+	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);
 }
 /**
@@ -97539,10 +97668,7 @@ async function readLocalState(baseDir) {
 async function writeLocalState(baseDir, state) {
 	const statePath = join(baseDir, STATE_FILE);
 	await mkdir(join(baseDir, ".tbd"), { recursive: true });
-	await writeFile(statePath, (0, import_dist$2.stringify)(state, {
-		sortMapEntries: true,
-		lineWidth: 0
-	}));
+	await writeFile(statePath, stringifyYaml(state, { lineWidth: 0 }));
 }
 /**
 * Update specific fields in local state (merge with existing).
@@ -97799,6 +97925,67 @@ async function ensureGitignorePatterns(gitignorePath, patterns, header) {
 	};
 }
 
+//#endregion
+//#region src/cli/lib/prefix-detection.ts
+/**
+* Prefix validation and beads prefix extraction module.
+*
+* Provides functions to validate prefixes and extract prefix from beads config.
+* Used by setup commands to validate user-provided prefixes and migrate from beads.
+*/
+/** Maximum length for a valid prefix */
+const MAX_PREFIX_LENGTH = 20;
+/** Minimum length for a valid prefix */
+const MIN_PREFIX_LENGTH = 1;
+/** Recommended minimum length */
+const RECOMMENDED_MIN_LENGTH = 2;
+/** Recommended maximum length */
+const RECOMMENDED_MAX_LENGTH = 8;
+/**
+* Check if a prefix is valid (hard rules, always enforced).
+* - Must be 1-20 characters
+* - Must start with a letter (a-z)
+* - Must end with alphanumeric (a-z0-9)
+* - Middle characters can be alphanumeric, dot, or underscore
+* - No dashes allowed (breaks ID syntax)
+*/
+function isValidPrefix(s) {
+	if (!s) return false;
+	if (s.length < MIN_PREFIX_LENGTH || s.length > MAX_PREFIX_LENGTH) return false;
+	if (!/^[a-z]/.test(s)) return false;
+	if (s.length > 1 && !/[a-z0-9]$/.test(s)) return false;
+	return /^[a-z][a-z0-9._]*$/.test(s);
+}
+/**
+* Check if a prefix follows recommended format (soft rules).
+* - Must be 2-8 characters
+* - Must be alphabetic only (a-z)
+*
+* Prefixes that don't match this can still be used with --force.
+*/
+function isRecommendedPrefix(s) {
+	if (!s) return false;
+	if (s.length < RECOMMENDED_MIN_LENGTH || s.length > RECOMMENDED_MAX_LENGTH) return false;
+	return /^[a-z]+$/.test(s);
+}
+/**
+* Get prefix from existing beads config.
+*
+* Looks for .beads/config.yaml and extracts display.id_prefix
+*
+* @param cwd Current working directory
+* @returns The beads prefix, or null if not found
+*/
+async function getBeadsPrefix(cwd) {
+	try {
+		const prefix = ((0, import_dist$2.parse)(await readFile(join(cwd, ".beads", "config.yaml"), "utf-8"))?.display)?.id_prefix;
+		if (typeof prefix === "string" && isValidPrefix(prefix)) return prefix;
+		return null;
+	} catch {
+		return null;
+	}
+}
+
 //#endregion
 //#region src/utils/time-utils.ts
 /**
@@ -98644,7 +98831,15 @@ var InitHandler = class extends BaseCommand {
 		} catch (error) {
 			if (error instanceof CLIError) throw error;
 		}
-		if (!options.prefix) throw new ValidationError("The --prefix option is required\n\nUsage: tbd init --prefix=<name>\n\nThe prefix is used for display IDs (e.g., proj-a7k2, myapp-b3m9)\nChoose a short 2-4 letter prefix for your project (e.g., tbd, myp).\n\nFor full setup with integrations: tbd setup --auto --prefix=<name>");
+		if (!options.prefix) throw new ValidationError("The --prefix option is required\n\nUsage: tbd init --prefix=<name>\n\nThe prefix is used for display IDs (e.g., proj-a7k2, myapp-b3m9)\nChoose a short 2-8 letter prefix for your project (e.g., tbd, myp, proj).\n\nFor full setup with integrations: tbd setup --auto --prefix=<name>");
+		const prefix = options.prefix;
+		if (!isValidPrefix(prefix)) throw new ValidationError("Invalid prefix format.\nPrefix must be 1-20 lowercase characters:\n  - Must start with a letter (a-z)\n  - Must end with alphanumeric (a-z, 0-9)\n  - Middle characters can include dots (.) and underscores (_)\n  - No dashes allowed (breaks ID syntax)\n\nExample:\n  tbd init --prefix=tbd");
+		if (!isRecommendedPrefix(prefix) && !options.force) throw new ValidationError(`Prefix "${prefix}" is not recommended.\nRecommended prefixes are 2-8 alphabetic characters (e.g., "tbd", "myp", "proj").
+
+If you really want to use this prefix, add --force to override.
+
+Example:
+  tbd init --prefix=${prefix} --force`);
 		if (this.checkDryRun("Would initialize tbd repository", options)) return;
 		await this.execute(async () => {
 			await initConfig(cwd, VERSION, options.prefix);
@@ -98708,7 +98903,7 @@ var InitHandler = class extends BaseCommand {
 		});
 	}
 };
-const initCommand = new Command("init").description("Initialize tbd in a git repository").option("--prefix <name>", "Project prefix for display IDs (e.g., \"proj\", \"myapp\")").option("--sync-branch <name>", "Sync branch name (default: tbd-sync)").option("--remote <name>", "Remote name (default: origin)").action(async (options, command) => {
+const initCommand = new Command("init").description("Initialize tbd in a git repository").option("--prefix <name>", "Project prefix for display IDs (2-8 alphabetic recommended)").option("--force", "Allow non-recommended prefix format").option("--sync-branch <name>", "Sync branch name (default: tbd-sync)").option("--remote <name>", "Remote name (default: origin)").action(async (options, command) => {
 	await new InitHandler(command).run(options);
 });
 
@@ -99174,7 +99369,10 @@ async function loadIdMapping(baseDir) {
 			ulidToShort: /* @__PURE__ */ new Map()
 		};
 	}
-	const data = (0, import_dist$2.parse)(content) || {};
+	const rawData = parseYamlWithConflictDetection(content, filePath) ?? {};
+	const parseResult = IdMappingYamlSchema.safeParse(rawData);
+	if (!parseResult.success) throw new Error(`Invalid ID mapping format in ${filePath}: ${parseResult.error.message}`);
+	const data = parseResult.data;
 	const shortToUlid = /* @__PURE__ */ new Map();
 	const ulidToShort = /* @__PURE__ */ new Map();
 	for (const [shortId, ulid] of Object.entries(data)) {
@@ -99195,7 +99393,7 @@ async function saveIdMapping(baseDir, mapping) {
 	const data = {};
 	const sortedKeys = naturalSort(Array.from(mapping.shortToUlid.keys()));
 	for (const key of sortedKeys) data[key] = mapping.shortToUlid.get(key);
-	await writeFile(filePath, (0, import_dist$2.stringify)(data));
+	await writeFile(filePath, stringifyYaml(data));
 }
 /**
 * Calculate the optimal short ID length based on existing ID count.
@@ -99264,6 +99462,55 @@ function resolveToInternalId(input, mapping) {
 	if (!ulid) throw new Error(`Unknown issue ID: ${input}. Short ID "${shortId}" not found in mapping.`);
 	return makeInternalId(ulid);
 }
+/**
+* Parse an ID mapping from raw YAML content.
+* Used for loading mappings from git show output during conflict resolution.
+*
+* @throws MergeConflictError if content contains merge conflict markers
+*/
+function parseIdMappingFromYaml(content) {
+	const rawData = parseYamlWithConflictDetection(content) ?? {};
+	const parseResult = IdMappingYamlSchema.safeParse(rawData);
+	if (!parseResult.success) throw new Error(`Invalid ID mapping format: ${parseResult.error.message}`);
+	const data = parseResult.data;
+	const shortToUlid = /* @__PURE__ */ new Map();
+	const ulidToShort = /* @__PURE__ */ new Map();
+	for (const [shortId, ulid] of Object.entries(data)) {
+		shortToUlid.set(shortId, ulid);
+		ulidToShort.set(ulid, shortId);
+	}
+	return {
+		shortToUlid,
+		ulidToShort
+	};
+}
+/**
+* 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.
+*
+* If the same short ID maps to different ULIDs in each mapping (a conflict),
+* the local mapping takes precedence (caller should log a warning).
+*
+* @param local - The local ID mapping
+* @param remote - The remote ID mapping
+* @returns Merged mapping with all entries from both
+*/
+function mergeIdMappings(local, remote) {
+	const merged = {
+		shortToUlid: new Map(local.shortToUlid),
+		ulidToShort: new Map(local.ulidToShort)
+	};
+	for (const [shortId, ulid] of remote.shortToUlid) if (!merged.shortToUlid.has(shortId)) {
+		merged.shortToUlid.set(shortId, ulid);
+		merged.ulidToShort.set(ulid, shortId);
+	}
+	for (const [ulid, shortId] of remote.ulidToShort) if (!merged.ulidToShort.has(ulid) && !merged.shortToUlid.has(shortId)) {
+		merged.shortToUlid.set(shortId, ulid);
+		merged.ulidToShort.set(ulid, shortId);
+	}
+	return merged;
+}
 
 //#endregion
 //#region src/lib/priority.ts
@@ -99472,8 +99719,9 @@ var CreateHandler = class extends BaseCommand {
 		let description = options.description;
 		if (options.file) try {
 			description = await readFile(options.file, "utf-8");
-		} catch {
-			throw new CLIError(`Failed to read description from file: ${options.file}`);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			throw new CLIError(`Failed to read description from file '${options.file}': ${message}`);
 		}
 		let specPath;
 		if (options.spec) try {
@@ -100128,15 +100376,8 @@ function normalizePath(path) {
 */
 var ListHandler = class extends BaseCommand {
 	async run(options) {
-		const tbdRoot = await requireInit();
-		let issues;
-		let dataCtx;
-		try {
-			dataCtx = await loadDataContext(tbdRoot);
-			issues = await listIssues(dataCtx.dataSyncDir);
-		} catch {
-			throw new CLIError("Failed to read issues");
-		}
+		const dataCtx = await loadDataContext(await requireInit());
+		let issues = await listIssues(dataCtx.dataSyncDir);
 		issues = this.filterIssues(issues, options, dataCtx.mapping);
 		issues = this.sortIssues(issues, options.sort ?? "priority", dataCtx.mapping);
 		issues = applyLimit(issues, options.limit);
@@ -101449,8 +101690,8 @@ var DocSync = class {
 	* Parse a source string into a DocSource.
 	*
 	* @example
-	* parseSource('internal:shortcuts/standard/commit-code.md')
-	* // => { type: 'internal', location: 'shortcuts/standard/commit-code.md' }
+	* parseSource('internal:shortcuts/standard/code-review-and-commit.md')
+	* // => { type: 'internal', location: 'shortcuts/standard/code-review-and-commit.md' }
 	*
 	* @example
 	* parseSource('https://raw.githubusercontent.com/org/repo/main/file.md')
@@ -102136,7 +102377,24 @@ var SyncHandler = class extends BaseCommand {
 					} catch {
 						this.output.debug(`Issue ${localIssue.id} not on remote, keeping local`);
 					}
+					try {
+						const remoteIdsContent = await git("show", `${remote}/${syncBranch}:${DATA_SYNC_DIR}/mappings/ids.yml`);
+						if (remoteIdsContent) {
+							const localMapping = await loadIdMapping(this.dataSyncDir);
+							const remoteMapping = parseIdMappingFromYaml(remoteIdsContent);
+							const mergedMapping = mergeIdMappings(localMapping, remoteMapping);
+							await saveIdMapping(this.dataSyncDir, mergedMapping);
+							this.output.debug(`Merged ID mappings: ${localMapping.shortToUlid.size} local + ${remoteMapping.shortToUlid.size} remote = ${mergedMapping.shortToUlid.size} total`);
+						}
+					} catch (error) {
+						this.output.debug(`Could not merge ids.yml: ${error.message}`);
+					}
 					await git("-C", worktreePath, "add", "-A");
+					const conflictCheck = await git("-C", worktreePath, "diff", "--cached", "-S<<<<<<< ", "--name-only");
+					if (conflictCheck.trim()) {
+						const conflictedFiles = conflictCheck.trim().split("\n");
+						throw new SyncError(`Cannot commit: ${conflictedFiles.length} file(s) still have merge conflict markers:\n` + conflictedFiles.map((f) => `  - ${f}`).join("\n") + `\n\nThis is a bug in tbd sync. Please report it and manually resolve conflicts in:\n  ${worktreePath}`);
+					}
 					try {
 						await git("-C", worktreePath, "commit", "--no-verify", "-m", "tbd sync: resolved merge conflicts");
 					} catch {
@@ -102282,7 +102540,7 @@ async function readState() {
 * Update local state file.
 */
 async function updateState(updates) {
-	await writeFile(STATE_FILE, (0, import_dist$2.stringify)({
+	await writeFile(STATE_FILE, stringifyYaml({
 		...await readState(),
 		...updates
 	}));
@@ -102751,7 +103009,7 @@ async function saveConflictToAttic(atticDir, conflict, winnerSource) {
 		}
 	};
 	const safeTimestamp = timestamp.replace(/:/g, "-");
-	await writeFile(join(atticDir, `${conflict.issue_id}_${safeTimestamp}_${conflict.field}.yml`), (0, import_dist$2.stringify)(entry, { sortMapEntries: true }));
+	await writeFile(join(atticDir, `${conflict.issue_id}_${safeTimestamp}_${conflict.field}.yml`), stringifyYaml(entry));
 }
 /**
 * Get the target/source directory for workspace operations.
@@ -104285,7 +104543,9 @@ async function listAtticEntries(filterById) {
 		if (!parsed) continue;
 		if (filterById && parsed.entityId !== filterById) continue;
 		try {
-			const entry = (0, import_dist$2.parse)(await readFile(join(atticPath, file), "utf-8"));
+			const filePath = join(atticPath, file);
+			const rawData = parseYamlWithConflictDetection(await readFile(filePath, "utf-8"), filePath);
+			const entry = AtticEntrySchema.parse(rawData);
 			entries.push(entry);
 		} catch {}
 	}
@@ -104997,7 +105257,7 @@ var DocsHandler = class extends BaseCommand {
 		console.log(colors.bold("Workflows (Shortcuts):"));
 		console.log("  tbd shortcut --list          List all available shortcuts");
 		console.log("  tbd shortcut new-plan-spec   Plan a new feature");
-		console.log("  tbd shortcut commit-code     Commit code properly");
+		console.log("  tbd shortcut code-review-and-commit     Commit code properly");
 		console.log("  tbd shortcut create-or-update-pr-simple  Create a pull request");
 		console.log("");
 		console.log(colors.bold("Guidelines (Coding Standards):"));
@@ -105338,8 +105598,8 @@ var UninstallHandler = class extends BaseCommand {
 				force: true
 			});
 			console.log(`  ${colors.success("✓")} Removed .tbd directory`);
-		} catch {
-			throw new CLIError("Failed to remove .tbd directory");
+		} catch (error) {
+			throw new CLIError(`Failed to remove .tbd directory: ${error instanceof Error ? error.message : String(error)}`);
 		}
 		console.log("");
 		this.output.success("tbd has been uninstalled from this repository.");
@@ -105521,6 +105781,7 @@ var DocCache = class {
 			return {
 				title: typeof parsed.title === "string" ? parsed.title : void 0,
 				description: typeof parsed.description === "string" ? parsed.description : void 0,
+				category: typeof parsed.category === "string" ? parsed.category : void 0,
 				tags: Array.isArray(parsed.tags) ? parsed.tags.filter((t) => typeof t === "string") : void 0
 			};
 		} catch {
@@ -105649,7 +105910,7 @@ function buildTableRows(docs, skipNames = []) {
 * // ## Available Shortcuts
 * // | Name | Description |
 * // | --- | --- |
-* // | commit-code | Run pre-commit checks, review changes, and commit code |
+* // | code-review-and-commit | Run pre-commit checks, review changes, and commit code |
 * // ...
 * // ## Available Guidelines
 * // | Name | Description |
@@ -106134,16 +106395,6 @@ async function addDoc(tbdRoot, options) {
 *
 * See: docs/project/specs/active/plan-2026-01-22-doc-cache-abstraction.md
 */
-/**
-* Infer category from shortcut name.
-* Returns undefined if no category matches.
-*/
-function inferCategory(name) {
-	if (name.includes("plan-spec") || name.includes("architecture") || name.includes("research") || name.includes("validation-spec") || name.includes("implementation-spec") || name.includes("beads-from-spec") || name.includes("update-spec") || name.includes("refine-spec") || name.includes("revise-")) return "planning";
-	if (name.includes("implement-") || name.includes("coding-spike")) return "implementation";
-	if (name.includes("review-") || name.includes("precommit") || name.includes("cleanup-") || name.includes("validation-plan")) return "quality";
-	if (name.includes("commit-") || name.includes("pr-") || name.includes("merge-")) return "shipping";
-}
 var ShortcutHandler = class extends BaseCommand {
 	async run(query, options) {
 		await this.execute(async () => {
@@ -106201,13 +106452,14 @@ var ShortcutHandler = class extends BaseCommand {
 	async handleList(cache, includeAll, category) {
 		let docs = cache.list(includeAll);
 		if (category) docs = docs.filter((d) => {
-			return inferCategory(d.name) === category;
+			return d.frontmatter?.category === category;
 		});
 		if (this.ctx.json) {
 			this.output.data(docs.map((d) => ({
 				name: d.name,
 				title: d.frontmatter?.title,
 				description: d.frontmatter?.description,
+				category: d.frontmatter?.category,
 				path: d.path,
 				sourceDir: d.sourceDir,
 				sizeBytes: d.sizeBytes,
@@ -106361,7 +106613,7 @@ var ShortcutHandler = class extends BaseCommand {
 		}
 	}
 };
-const shortcutCommand = new Command("shortcut").description("Find and output documentation shortcuts").argument("[query]", "Shortcut name or description to search for").option("--list", "List all available shortcuts").option("--all", "Include shadowed shortcuts (use with --list)").option("--category <category>", "Filter by category: planning, implementation, quality, shipping").option("--refresh", "Refresh the cached shortcut directory").option("--quiet", "Suppress output (use with --refresh)").option("--add <url>", "Add a shortcut from a URL").option("--name <name>", "Name for the added shortcut (required with --add)").action(async (query, options, command) => {
+const shortcutCommand = new Command("shortcut").description("Find and output documentation shortcuts").argument("[query]", "Shortcut name or description to search for").option("--list", "List all available shortcuts").option("--all", "Include shadowed shortcuts (use with --list)").option("--category <category>", "Filter by category: planning, documentation, review, git, cleanup, session, meta").option("--refresh", "Refresh the cached shortcut directory").option("--quiet", "Suppress output (use with --refresh)").option("--add <url>", "Add a shortcut from a URL").option("--name <name>", "Name for the added shortcut (required with --add)").action(async (query, options, command) => {
 	await new ShortcutHandler(command).run(query, options);
 });
 
@@ -106728,47 +106980,6 @@ const templateCommand = new Command("template").description("Find and output doc
 	await new TemplateHandler(command).run(query, options);
 });
 
-//#endregion
-//#region src/cli/lib/prefix-detection.ts
-/**
-* Prefix validation and beads prefix extraction module.
-*
-* Provides functions to validate prefixes and extract prefix from beads config.
-* Used by setup commands to validate user-provided prefixes and migrate from beads.
-*/
-/** Maximum length for a valid prefix */
-const MAX_PREFIX_LENGTH = 10;
-/** Minimum length for a valid prefix */
-const MIN_PREFIX_LENGTH = 1;
-/**
-* Check if a prefix is valid.
-* - Must be 1-10 characters
-* - Must start with a letter
-* - Must be alphanumeric only (lowercase)
-*/
-function isValidPrefix(s) {
-	if (!s) return false;
-	if (s.length < MIN_PREFIX_LENGTH || s.length > MAX_PREFIX_LENGTH) return false;
-	return /^[a-z][a-z0-9]*$/.test(s);
-}
-/**
-* Get prefix from existing beads config.
-*
-* Looks for .beads/config.yaml and extracts display.id_prefix
-*
-* @param cwd Current working directory
-* @returns The beads prefix, or null if not found
-*/
-async function getBeadsPrefix(cwd) {
-	try {
-		const prefix = ((0, import_dist$2.parse)(await readFile(join(cwd, ".beads", "config.yaml"), "utf-8"))?.display)?.id_prefix;
-		if (typeof prefix === "string" && isValidPrefix(prefix)) return prefix;
-		return null;
-	} catch {
-		return null;
-	}
-}
-
 //#endregion
 //#region src/cli/commands/setup.ts
 /**
@@ -107563,8 +107774,14 @@ var SetupDefaultHandler = class extends BaseCommand {
 		}
 		const beadsPrefix = await getBeadsPrefix(cwd);
 		const prefix = options.prefix ?? beadsPrefix;
-		if (!prefix) throw new CLIError("Could not read prefix from beads config.\nPlease specify a prefix (2-4 letters recommended):\n  tbd setup --auto --prefix=tbd");
-		if (!isValidPrefix(prefix)) throw new CLIError("Invalid prefix format.\nPrefix must be 1-10 lowercase alphanumeric characters, starting with a letter.\nRecommended: 2-4 letters for clear, readable issue IDs.\nPlease specify a valid prefix:\n  tbd setup --auto --prefix=tbd");
+		if (!prefix) throw new CLIError("Could not read prefix from beads config.\nPlease specify a prefix (2-8 letters recommended):\n  tbd setup --auto --prefix=tbd");
+		if (!isValidPrefix(prefix)) throw new CLIError("Invalid prefix format.\nPrefix must be 1-20 lowercase characters:\n  - Must start with a letter (a-z)\n  - Must end with alphanumeric (a-z, 0-9)\n  - Middle characters can include dots (.) and underscores (_)\n  - No dashes allowed (breaks ID syntax)\n\nPlease specify a valid prefix:\n  tbd setup --from-beads --prefix=tbd");
+		if (!(beadsPrefix && prefix === beadsPrefix) && !isRecommendedPrefix(prefix) && !options.force) throw new CLIError(`Prefix "${prefix}" is not recommended.\nRecommended prefixes are 2-8 alphabetic characters (e.g., "tbd", "myp", "proj").
+
+If you really want to use this prefix, add --force to override.
+
+Example:
+  tbd setup --from-beads --prefix=${prefix} --force`);
 		await this.initializeTbd(cwd, prefix);
 		if (options.ghCli === false) {
 			const config = await readConfig(cwd);
@@ -107603,7 +107820,13 @@ var SetupDefaultHandler = class extends BaseCommand {
 		const colors = this.output.getColors();
 		const prefix = options.prefix;
 		if (!prefix) throw new CLIError("--prefix is required for tbd setup --auto\n\nThe --prefix flag specifies your project name for issue IDs.\nUse a short 2-4 letter prefix so issue IDs stand out clearly.\n\nExample:\n  tbd setup --auto --prefix=tbd    # Issues: tbd-a1b2\n  tbd setup --auto --prefix=myp    # Issues: myp-c3d4\n\nNote: If migrating from beads, the prefix is automatically read from your beads config.");
-		if (!isValidPrefix(prefix)) throw new CLIError("Invalid prefix format.\nPrefix must be 1-10 lowercase alphanumeric characters, starting with a letter.\nRecommended: 2-4 letters for clear, readable issue IDs.\n\nExample:\n  tbd setup --auto --prefix=tbd");
+		if (!isValidPrefix(prefix)) throw new CLIError("Invalid prefix format.\nPrefix must be 1-20 lowercase characters:\n  - Must start with a letter (a-z)\n  - Must end with alphanumeric (a-z, 0-9)\n  - Middle characters can include dots (.) and underscores (_)\n  - No dashes allowed (breaks ID syntax)\n\nExample:\n  tbd setup --auto --prefix=tbd");
+		if (!isRecommendedPrefix(prefix) && !options.force) throw new CLIError(`Prefix "${prefix}" is not recommended.\nRecommended prefixes are 2-8 alphabetic characters (e.g., "tbd", "myp", "proj").
+
+If you really want to use this prefix, add --force to override.
+
+Example:
+  tbd setup --auto --prefix=${prefix} --force`);
 		console.log(`Initializing with prefix "${prefix}"...`);
 		await this.initializeTbd(cwd, prefix);
 		if (options.ghCli === false) {
@@ -107876,7 +108099,7 @@ var SetupAutoHandler = class extends BaseCommand {
 		return result;
 	}
 };
-const setupCommand = new Command("setup").description("Configure tbd integration with editors and tools").option("--auto", "Non-interactive mode with smart defaults (for agents/scripts)").option("--interactive", "Interactive mode with prompts (for humans)").option("--from-beads", "Migrate from Beads to tbd").option("--prefix <name>", "Project prefix for issue IDs (required for fresh setup)").option("--no-gh-cli", "Disable automatic GitHub CLI installation hook").action(async (options, command) => {
+const setupCommand = new Command("setup").description("Configure tbd integration with editors and tools").option("--auto", "Non-interactive mode with smart defaults (for agents/scripts)").option("--interactive", "Interactive mode with prompts (for humans)").option("--from-beads", "Migrate from Beads to tbd").option("--prefix <name>", "Project prefix for issue IDs (required for fresh setup)").option("--force", "Allow non-recommended prefix format (not 2-8 alphabetic)").option("--no-gh-cli", "Disable automatic GitHub CLI installation hook").action(async (options, command) => {
 	if (options.auto || options.interactive) {
 		await new SetupDefaultHandler(command).run(options);
 		return;
@@ -107900,7 +108123,8 @@ const setupCommand = new Command("setup").description("Configure tbd integration
 	console.log("  --from-beads        Migrate from Beads to tbd (implies --auto)");
 	console.log("");
 	console.log("Options:");
-	console.log("  --prefix <name>     Project prefix for issue IDs (e.g., \"tbd\", \"myapp\")");
+	console.log("  --prefix <name>     Project prefix for issue IDs (2-8 alphabetic recommended)");
+	console.log("  --force             Allow non-recommended prefix format");
 	console.log("  --no-gh-cli         Disable automatic GitHub CLI installation hook");
 	console.log("");
 	console.log("Examples:");
@@ -108102,15 +108326,31 @@ function isJsonMode() {
 	return process.argv.includes("--json");
 }
 /**
+* Check if --debug flag is present in argv.
+*/
+function isDebugMode() {
+	return process.argv.includes("--debug");
+}
+/**
 * Output error in the appropriate format (JSON or text).
+* In debug mode, shows full error details and stack trace.
 */
 function outputError(message, error) {
+	const debugMode = isDebugMode();
 	if (isJsonMode()) {
 		const errorObj = { error: message };
 		if (error instanceof CLIError) errorObj.type = error.name;
 		if (error && error.message !== message) errorObj.details = error.message;
+		if (debugMode && error?.stack) errorObj.stack = error.stack;
 		console.error(JSON.stringify(errorObj));
-	} else console.error(`Error: ${message}`);
+	} else {
+		console.error(`Error: ${message}`);
+		if (debugMode && error?.stack) {
+			console.error("");
+			console.error("Stack trace:");
+			console.error(error.stack);
+		}
+	}
 }
 /**
 * Check if running with no command (just options or nothing).