get-tbd 0.1.13 → 0.1.15

package/dist/cli.mjs

@@ -1,7 +1,7 @@
-import { S as LocalStateSchema, a as insertAfterFrontmatter, i as serializeIssue, l as ConfigSchema, n as parseIssue, o as stripFrontmatter, r as parseMarkdownWithFrontmatter, t as VERSION$1, x as IssueStatus, y as IssueKind } from "./src-BfhjLZXE.mjs";
+import { S as IssueKind, T as LocalStateSchema, a as insertAfterFrontmatter, b as IdMappingYamlSchema, c as stringifyYaml, d as ConfigSchema, i as serializeIssue, l as AtticEntrySchema, n as parseIssue, o as stripFrontmatter, r as parseMarkdownWithFrontmatter, s as parseYamlWithConflictDetection, t as VERSION$1, w as IssueStatus } from "./src-Ct16P2Ox.mjs";
 import { createRequire } from "node:module";
 import matter from "gray-matter";
-import { parse, stringify } from "yaml";
+import { parse } from "yaml";
 import { Command } from "commander";
 import pc from "picocolors";
 import { marked } from "marked";
@@ -963,11 +963,8 @@ async function readConfigWithMigration(baseDir) {
 */
 async function writeConfig(baseDir, config) {
 	const configPath = join(baseDir, CONFIG_FILE);
-	let content = 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);
 }
 /**
@@ -1026,10 +1023,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, stringify(state, {
-		sortMapEntries: true,
-		lineWidth: 0
-	}));
+	await writeFile(statePath, stringifyYaml(state, { lineWidth: 0 }));
 }
 /**
 * Update specific fields in local state (merge with existing).
@@ -1286,6 +1280,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 = (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
 /**
@@ -2131,7 +2186,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);
@@ -2195,7 +2258,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);
 });
 
@@ -2566,7 +2629,10 @@ async function loadIdMapping(baseDir) {
 			ulidToShort: /* @__PURE__ */ new Map()
 		};
 	}
-	const data = 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)) {
@@ -2587,7 +2653,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, stringify(data));
+	await writeFile(filePath, stringifyYaml(data));
 }
 /**
 * Calculate the optimal short ID length based on existing ID count.
@@ -2656,6 +2722,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
@@ -2864,8 +2979,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 {
@@ -3520,15 +3636,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);
@@ -4841,8 +4950,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')
@@ -5528,7 +5637,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 {
@@ -5674,7 +5800,7 @@ async function readState() {
 * Update local state file.
 */
 async function updateState(updates) {
-	await writeFile(STATE_FILE, stringify({
+	await writeFile(STATE_FILE, stringifyYaml({
 		...await readState(),
 		...updates
 	}));
@@ -6143,7 +6269,7 @@ async function saveConflictToAttic(atticDir, conflict, winnerSource) {
 		}
 	};
 	const safeTimestamp = timestamp.replace(/:/g, "-");
-	await writeFile(join(atticDir, `${conflict.issue_id}_${safeTimestamp}_${conflict.field}.yml`), 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.
@@ -7677,7 +7803,9 @@ async function listAtticEntries(filterById) {
 		if (!parsed) continue;
 		if (filterById && parsed.entityId !== filterById) continue;
 		try {
-			const entry = 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 {}
 	}
@@ -8316,7 +8444,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):"));
@@ -8657,8 +8785,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.");
@@ -8840,6 +8968,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 {
@@ -8968,7 +9097,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 |
@@ -9453,16 +9582,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 () => {
@@ -9520,13 +9639,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,
@@ -9680,7 +9800,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);
 });
 
@@ -10047,47 +10167,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 = (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
 /**
@@ -10882,8 +10961,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);
@@ -10922,7 +11007,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) {
@@ -11195,7 +11286,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;
@@ -11219,7 +11310,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:");
@@ -11421,15 +11513,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).