clawt 3.4.1 → 3.4.3

package/src/commands/remove.ts

@@ -4,7 +4,7 @@ import { ClawtError } from '../errors/index.js';
 import { MESSAGES } from '../constants/index.js';
 import type { RemoveOptions } from '../types/index.js';
 import {
-  validateMainWorktree,
+  runPreChecks,
   getProjectName,
   getProjectWorktreeDir,
   getProjectWorktrees,
@@ -23,7 +23,6 @@ import {
   resolveTargetWorktrees,
   getValidateBranchName,
   deleteValidateBranch,
-  requireProjectConfig,
   getCurrentBranch,
 } from '../utils/index.js';
 import type { WorktreeMultiResolveMessages } from '../utils/index.js';
@@ -56,8 +55,7 @@ export function registerRemoveCommand(program: Command): void {
  * @param {RemoveOptions} options - 命令选项
  */
 async function handleRemove(options: RemoveOptions): Promise<void> {
-  validateMainWorktree();
-  requireProjectConfig();
+  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true });
 
   const projectName = getProjectName();
   logger.info(`remove 命令执行，项目: ${projectName}`);

package/src/commands/reset.ts

@@ -2,7 +2,7 @@ import type { Command } from 'commander';
 import { logger } from '../logger/index.js';
 import { MESSAGES } from '../constants/index.js';
 import {
-  validateMainWorktree,
+  runPreChecks,
   getGitTopLevel,
   getConfigValue,
   isWorkingDirClean,
@@ -11,7 +11,6 @@ import {
   confirmDestructiveAction,
   printSuccess,
   printInfo,
-  requireProjectConfig,
 } from '../utils/index.js';
 
 /**
@@ -31,8 +30,7 @@ export function registerResetCommand(program: Command): void {
  * 执行 reset 命令：重置主 worktree 工作区和暂存区
  */
 async function handleReset(): Promise<void> {
-  validateMainWorktree();
-  requireProjectConfig();
+  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true });
 
   const mainWorktreePath = getGitTopLevel();
   logger.info('reset 命令执行');

package/src/commands/resume.ts

@@ -4,7 +4,7 @@ import { MESSAGES } from '../constants/index.js';
 import type { ResumeOptions } from '../types/index.js';
 import type { WorktreeInfo } from '../types/index.js';
 import {
-  validateMainWorktree,
+  runPreChecks,
   validateClaudeCodeInstalled,
   getProjectWorktrees,
   launchInteractiveClaude,
@@ -47,7 +47,7 @@ export function registerResumeCommand(program: Command): void {
  * @param {ResumeOptions} options - 命令选项
  */
 async function handleResume(options: ResumeOptions): Promise<void> {
-  validateMainWorktree();
+  runPreChecks({ mainWorktree: true, headExists: true });
   validateClaudeCodeInstalled();
 
   logger.info(`resume 命令执行，分支过滤: ${options.branch ?? '(无)'}`);

package/src/commands/run.ts

@@ -4,7 +4,7 @@ import { ClawtError } from '../errors/index.js';
 import { MESSAGES } from '../constants/index.js';
 import type { RunOptions, WorktreeInfo } from '../types/index.js';
 import {
-  validateMainWorktree,
+  runPreChecks,
   validateClaudeCodeInstalled,
   createWorktrees,
   createWorktreesByBranches,
@@ -20,6 +20,7 @@ import {
   executeBatchTasks,
   printDryRunPreview,
   ensureOnMainWorkBranch,
+  guardMainWorkBranch,
 } from '../utils/index.js';
 
 /**
@@ -119,10 +120,11 @@ function handleDryRunFromFile(options: RunOptions): void {
  * @param {RunOptions} options - 命令选项
  */
 async function handleRun(options: RunOptions): Promise<void> {
-  validateMainWorktree();
+  runPreChecks({ mainWorktree: true, headExists: true });
 
   // dry-run 模式跳过项目配置前置校验
   if (!options.dryRun) {
+    await guardMainWorkBranch();
     await ensureOnMainWorkBranch();
   }
 

package/src/commands/status.ts

@@ -1,10 +1,10 @@
 import type { Command } from 'commander';
 import chalk from 'chalk';
-import { MESSAGES } from '../constants/index.js';
+import { MESSAGES, VALIDATE_BRANCH_PREFIX } from '../constants/index.js';
 import { logger } from '../logger/index.js';
 import type { StatusOptions, WorktreeDetailedStatus, MainWorktreeStatus, SnapshotSummary, StatusResult, WorktreeInfo } from '../types/index.js';
 import {
-  validateMainWorktree,
+  runPreChecks,
   getProjectName,
   getCurrentBranch,
   isWorkingDirClean,
@@ -22,6 +22,8 @@ import {
   printDoubleSeparator,
   printSeparator,
   InteractivePanel,
+  loadProjectConfig,
+  checkBranchExists,
 } from '../utils/index.js';
 
 /**
@@ -44,7 +46,7 @@ export function registerStatusCommand(program: Command): void {
  * @param {StatusOptions} options - 命令选项
  */
 async function handleStatus(options: StatusOptions): Promise<void> {
-  validateMainWorktree();
+  runPreChecks({ mainWorktree: true, headExists: true });
 
   // 交互式面板模式
   if (options.interactive) {
@@ -74,11 +76,18 @@ export function collectStatus(): StatusResult {
   const currentBranch = getCurrentBranch();
   const isClean = isWorkingDirClean();
 
+  // 配置分支信息收集
+  const projectConfig = loadProjectConfig();
+  const configuredMainBranch = projectConfig?.clawtMainWorkBranch || null;
+  const configuredBranchExists = configuredMainBranch ? checkBranchExists(configuredMainBranch) : null;
+
   // 主 worktree 状态
   const main: MainWorktreeStatus = {
     branch: currentBranch,
     isClean,
     projectName,
+    configuredMainBranch,
+    configuredBranchExists,
   };
 
   // 各 worktree 详细状态
@@ -265,6 +274,18 @@ function printMainSection(main: MainWorktreeStatus): void {
   } else {
     printInfo(`    状态: ${chalk.yellow('✗ 有未提交修改')}`);
   }
+
+  // 配置分支信息展示
+  if (main.configuredMainBranch !== null) {
+    if (main.configuredBranchExists === false) {
+      printInfo(`    ${chalk.red(MESSAGES.STATUS_CONFIGURED_BRANCH_DELETED(main.configuredMainBranch))}`);
+    } else if (main.branch !== main.configuredMainBranch && !main.branch.startsWith(VALIDATE_BRANCH_PREFIX)) {
+      printInfo(`    ${chalk.yellow(MESSAGES.STATUS_CONFIGURED_BRANCH_MISMATCH(main.configuredMainBranch))}`);
+    } else {
+      printInfo(`    ${chalk.gray(MESSAGES.STATUS_CONFIGURED_BRANCH(main.configuredMainBranch))}`);
+    }
+  }
+
   printInfo('');
 }
 

package/src/commands/sync.ts

@@ -4,7 +4,7 @@ import { ClawtError } from '../errors/index.js';
 import { MESSAGES, AUTO_SAVE_COMMIT_MESSAGE } from '../constants/index.js';
 import type { SyncOptions } from '../types/index.js';
 import {
-  validateMainWorktree,
+  runPreChecks,
   getGitTopLevel,
   getProjectWorktrees,
   isWorkingDirClean,
@@ -16,10 +16,10 @@ import {
   printInfo,
   printWarning,
   resolveTargetWorktree,
-  requireProjectConfig,
   getMainWorkBranch,
   rebuildValidateBranch,
   getValidateBranchName,
+  guardMainWorkBranch,
 } from '../utils/index.js';
 import type { WorktreeResolveMessages } from '../utils/index.js';
 
@@ -127,8 +127,8 @@ export async function executeSyncForBranch(targetWorktreePath: string, branch: s
  * @param {SyncOptions} options - 命令选项
  */
 async function handleSync(options: SyncOptions): Promise<void> {
-  validateMainWorktree();
-  requireProjectConfig();
+  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true });
+  await guardMainWorkBranch();
 
   logger.info(`sync 命令执行，分支: ${options.branch ?? '(未指定)'}`);
 

package/src/commands/validate.ts

@@ -4,7 +4,7 @@ import { MESSAGES } from '../constants/index.js';
 import type { ValidateOptions } from '../types/index.js';
 import { executeSyncForBranch } from './sync.js';
 import {
-  validateMainWorktree,
+  runPreChecks,
   getProjectName,
   getGitTopLevel,
   getProjectWorktrees,
@@ -25,7 +25,6 @@ import {
   printWarning,
   printInfo,
   resolveTargetWorktree,
-  requireProjectConfig,
   ensureOnMainWorkBranch,
   handleDirtyWorkingDir,
   getValidateRunCommand,
@@ -98,9 +97,7 @@ async function handlePatchApplyFailure(targetWorktreePath: string, branchName: s
  * @param {ValidateOptions} options - 命令选项
  */
 async function handleValidateClean(options: ValidateOptions): Promise<void> {
-  validateMainWorktree();
-  // 显式前置校验：确保项目已初始化
-  requireProjectConfig();
+  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true });
 
   const projectName = getProjectName();
   const mainWorktreePath = getGitTopLevel();
@@ -264,8 +261,7 @@ async function handleValidate(options: ValidateOptions): Promise<void> {
     return;
   }
 
-  validateMainWorktree();
-  requireProjectConfig();
+  runPreChecks({ mainWorktree: true, headExists: true, projectConfig: true });
 
   const projectName = getProjectName();
   const mainWorktreePath = getGitTopLevel();

package/src/constants/interactive-panel.ts

@@ -40,5 +40,5 @@ export const PANEL_SHORTCUT_KEYS = {
 /** 日期分隔线前缀 */
 export const PANEL_DATE_SEPARATOR_PREFIX = '════';
 
-/** 固定占用行数（顶部分隔线 + 快照摘要 + 底部分隔线 + 底栏） */
-export const PANEL_FIXED_ROWS = 4;
+/** 固定占用行数（配置分支信息 + 快照摘要 + 顶部分隔线 + 底部分隔线 + 底栏） */
+export const PANEL_FIXED_ROWS = 5;

package/src/constants/messages/common.ts

@@ -6,6 +6,8 @@ export const COMMON_MESSAGES = {
   GIT_NOT_INSTALLED: 'Git 未安装或不在 PATH 中，请先安装 Git',
   /** Claude Code CLI 未安装 */
   CLAUDE_NOT_INSTALLED: 'Claude Code CLI 未安装，请先安装：npm install -g @anthropic-ai/claude-code',
+  /** HEAD 不存在（仓库无任何 commit） */
+  HEAD_NOT_FOUND: '当前仓库尚未创建任何提交，请先执行 git commit 创建首次提交后再使用 clawt',
   /** 分支已存在 */
   BRANCH_EXISTS: (name: string) => `分支 ${name} 已存在，无法创建`,
   /** 分支名清理后为空 */
@@ -38,4 +40,10 @@ export const COMMON_MESSAGES = {
   SEPARATOR: '────────────────────────────────────────',
   /** 粗分隔线 */
   DOUBLE_SEPARATOR: '════════════════════════════════════════',
+  /** 守卫检测：配置的主工作分支已不存在 */
+  GUARD_BRANCH_NOT_EXISTS: (branchName: string) =>
+    `配置的主工作分支 ${branchName} 已不存在，请执行 clawt init 重新设置主工作分支`,
+  /** 守卫检测：当前分支与配置的主工作分支不一致 */
+  GUARD_BRANCH_MISMATCH: (configuredBranch: string, currentBranch: string) =>
+    `当前分支 ${currentBranch} 与配置的主工作分支 ${configuredBranch} 不一致，如需更新请执行 clawt init`,
 } as const;

package/src/constants/messages/index.ts

@@ -16,11 +16,11 @@ import { UPDATE_MESSAGES, UPDATE_COMMANDS } from './update.js';
 import { INIT_MESSAGES } from './init.js';
 import { COVER_VALIDATE_MESSAGES } from './cover-validate.js';
 import { HOME_MESSAGES } from './home.js';
-import { PANEL_FOOTER_SHORTCUTS, PANEL_FOOTER_COUNTDOWN, PANEL_OVERFLOW_DOWN_HINT, PANEL_OVERFLOW_UP_HINT, PANEL_SNAPSHOT_SUMMARY, PANEL_NO_WORKTREES as PANEL_NO_WORKTREES_MSG, PANEL_PRESS_ENTER_TO_RETURN, PANEL_NOT_TTY, PANEL_TITLE } from './interactive-panel.js';
+import { PANEL_FOOTER_SHORTCUTS, PANEL_FOOTER_COUNTDOWN, PANEL_OVERFLOW_DOWN_HINT, PANEL_OVERFLOW_UP_HINT, PANEL_SNAPSHOT_SUMMARY, PANEL_NO_WORKTREES as PANEL_NO_WORKTREES_MSG, PANEL_PRESS_ENTER_TO_RETURN, PANEL_NOT_TTY, PANEL_TITLE, PANEL_CONFIGURED_BRANCH, PANEL_CONFIGURED_BRANCH_DELETED, PANEL_CONFIGURED_BRANCH_MISMATCH, PANEL_NOT_INITIALIZED } from './interactive-panel.js';
 
 export { CONFIG_ALIAS_DISABLED_HINT };
 export { UPDATE_MESSAGES, UPDATE_COMMANDS };
-export { PANEL_FOOTER_SHORTCUTS, PANEL_FOOTER_COUNTDOWN, PANEL_OVERFLOW_DOWN_HINT, PANEL_OVERFLOW_UP_HINT, PANEL_SNAPSHOT_SUMMARY, PANEL_NO_WORKTREES_MSG, PANEL_PRESS_ENTER_TO_RETURN, PANEL_NOT_TTY, PANEL_TITLE };
+export { PANEL_FOOTER_SHORTCUTS, PANEL_FOOTER_COUNTDOWN, PANEL_OVERFLOW_DOWN_HINT, PANEL_OVERFLOW_UP_HINT, PANEL_SNAPSHOT_SUMMARY, PANEL_NO_WORKTREES_MSG, PANEL_PRESS_ENTER_TO_RETURN, PANEL_NOT_TTY, PANEL_TITLE, PANEL_CONFIGURED_BRANCH, PANEL_CONFIGURED_BRANCH_DELETED, PANEL_CONFIGURED_BRANCH_MISMATCH, PANEL_NOT_INITIALIZED };
 
 /**
  * 提示消息模板

package/src/constants/messages/interactive-panel.ts

@@ -59,3 +59,30 @@ export const PANEL_NOT_TTY = '交互式面板需要 TTY 终端环境，请直接
  * @returns {string} 格式化的标题
  */
 export const PANEL_TITLE = (projectName: string): string => chalk.bold.cyan(`项目状态总览: ${projectName}`);
+
+/**
+ * 面板配置分支信息（正常）
+ * @param {string} branchName - 分支名
+ * @returns {string} 格式化的分支信息
+ */
+export const PANEL_CONFIGURED_BRANCH = (branchName: string): string =>
+  chalk.gray(`主工作分支: ${branchName}`);
+
+/**
+ * 面板配置分支信息（分支已删除）
+ * @param {string} branchName - 分支名
+ * @returns {string} 格式化的分支信息
+ */
+export const PANEL_CONFIGURED_BRANCH_DELETED = (branchName: string): string =>
+  chalk.red(`✗ 主工作分支: ${branchName}（已不存在）`);
+
+/**
+ * 面板配置分支信息（分支不一致）
+ * @param {string} branchName - 分支名
+ * @returns {string} 格式化的分支信息
+ */
+export const PANEL_CONFIGURED_BRANCH_MISMATCH = (branchName: string): string =>
+  chalk.yellow(`⚠ 主工作分支: ${branchName}（不一致）`);
+
+/** 面板配置分支信息（未初始化） */
+export const PANEL_NOT_INITIALIZED = chalk.gray('未初始化（执行 clawt init 设置主工作分支）');

package/src/constants/messages/status.ts

@@ -30,4 +30,13 @@ export const STATUS_MESSAGES = {
   STATUS_LAST_VALIDATED: (relativeTime: string) => `上次验证: ${relativeTime}`,
   /** status 未验证警示 */
   STATUS_NOT_VALIDATED: '✗ 未验证',
+  /** status 配置的主工作分支（正常状态） */
+  STATUS_CONFIGURED_BRANCH: (branchName: string) =>
+    `主工作分支: ${branchName}`,
+  /** status 配置的主工作分支已不存在 */
+  STATUS_CONFIGURED_BRANCH_DELETED: (branchName: string) =>
+    `✗ 主工作分支: ${branchName}（已不存在，请执行 clawt init 重新设置）`,
+  /** status 当前分支与配置的主工作分支不一致 */
+  STATUS_CONFIGURED_BRANCH_MISMATCH: (branchName: string) =>
+    `⚠ 主工作分支: ${branchName}（当前分支不一致，如需更新请执行 clawt init）`,
 } as const;

package/src/types/status.ts

@@ -28,6 +28,10 @@ export interface MainWorktreeStatus {
   isClean: boolean;
   /** 项目名 */
   projectName: string;
+  /** 配置的主工作分支名（项目未初始化时为 null） */
+  configuredMainBranch: string | null;
+  /** 配置的主工作分支是否存在（项目未初始化时为 null） */
+  configuredBranchExists: boolean | null;
 }
 
 /** validate 快照信息 */

package/src/utils/index.ts

@@ -50,7 +50,7 @@ export {
   createBranch,
 } from './git.js';
 export { sanitizeBranchName, generateBranchNames, validateBranchesNotExist } from './branch.js';
-export { validateMainWorktree, validateGitInstalled, validateClaudeCodeInstalled } from './validation.js';
+export { validateMainWorktree, validateGitInstalled, validateClaudeCodeInstalled, validateHeadExists, runPreChecks } from './validation.js';
 export { createWorktrees, getProjectWorktrees, getProjectWorktreeDir, cleanupWorktrees, getWorktreeStatus, createWorktreesByBranches } from './worktree.js';
 export { loadConfig, writeDefaultConfig, writeConfig, saveConfig, getConfigValue, ensureClawtDirs, parseConcurrency } from './config.js';
 export { printSuccess, printError, printWarning, printInfo, printHint, printSeparator, printDoubleSeparator, confirmAction, confirmDestructiveAction, formatWorktreeStatus, isWorktreeIdle, formatDuration, formatRelativeTime, formatDiskSize, formatLocalISOString } from './formatter.js';
@@ -70,7 +70,7 @@ export { truncateTaskDesc, printDryRunPreview } from './dry-run.js';
 export { applyAliases } from './alias.js';
 export { isValidConfigKey, getValidConfigKeys, parseConfigValue, promptConfigValue, formatConfigValue, interactiveConfigEditor } from './config-strategy.js';
 export { checkForUpdates } from './update-checker.js';
-export { getProjectConfigPath, loadProjectConfig, saveProjectConfig, requireProjectConfig, getMainWorkBranch, getValidateRunCommand } from './project-config.js';
+export { getProjectConfigPath, loadProjectConfig, saveProjectConfig, requireProjectConfig, getMainWorkBranch, guardMainWorkBranchExists, guardMainWorkBranch, getValidateRunCommand } from './project-config.js';
 export { getValidateBranchName, createValidateBranch, deleteValidateBranch, rebuildValidateBranch, ensureOnMainWorkBranch, handleDirtyWorkingDir } from './validate-branch.js';
 export { safeStringify } from './json.js';
 export { executeRunCommand } from './validate-runner.js';

package/src/utils/interactive-panel-render.ts

@@ -7,6 +7,7 @@ import {
   PANEL_DATE_SEPARATOR_PREFIX,
   PANEL_FIXED_ROWS,
   UNKNOWN_DATE_GROUP,
+  VALIDATE_BRANCH_PREFIX,
 } from '../constants/index.js';
 import {
   PANEL_FOOTER_SHORTCUTS,
@@ -16,8 +17,12 @@ import {
   PANEL_SNAPSHOT_SUMMARY,
   PANEL_NO_WORKTREES_MSG,
   PANEL_TITLE,
+  PANEL_CONFIGURED_BRANCH,
+  PANEL_CONFIGURED_BRANCH_DELETED,
+  PANEL_CONFIGURED_BRANCH_MISMATCH,
+  PANEL_NOT_INITIALIZED,
 } from '../constants/messages/index.js';
-import type { StatusResult, WorktreeDetailedStatus } from '../types/index.js';
+import type { StatusResult, WorktreeDetailedStatus, MainWorktreeStatus } from '../types/index.js';
 import { formatRelativeTime, groupWorktreesByDate, formatRelativeDate } from './index.js';
 
 /** 面板行类型 */
@@ -73,6 +78,9 @@ export function buildPanelFrame(
   // 标题行
   lines.push(PANEL_TITLE(statusResult.main.projectName));
 
+  // 配置分支信息行
+  lines.push(renderConfiguredBranchLine(statusResult.main));
+
   // 快照摘要行
   lines.push(renderSnapshotSummary(statusResult.snapshots.total, statusResult.snapshots.orphaned));
 
@@ -283,6 +291,24 @@ function formatChangeStatusLabel(status: WorktreeDetailedStatus['changeStatus'])
   }
 }
 
+/**
+ * 渲染配置的主工作分支信息行（面板模式）
+ * @param {MainWorktreeStatus} main - 主 worktree 状态
+ * @returns {string} 格式化的配置分支信息
+ */
+function renderConfiguredBranchLine(main: MainWorktreeStatus): string {
+  if (main.configuredMainBranch === null) {
+    return PANEL_NOT_INITIALIZED;
+  }
+  if (main.configuredBranchExists === false) {
+    return PANEL_CONFIGURED_BRANCH_DELETED(main.configuredMainBranch);
+  }
+  if (main.branch !== main.configuredMainBranch && !main.branch.startsWith(VALIDATE_BRANCH_PREFIX)) {
+    return PANEL_CONFIGURED_BRANCH_MISMATCH(main.configuredMainBranch);
+  }
+  return PANEL_CONFIGURED_BRANCH(main.configuredMainBranch);
+}
+
 /**
  * 渲染快照摘要行
  * @param {number} total - 快照总数
@@ -309,7 +335,7 @@ export function renderFooter(countdown: number): string {
  * @returns {number} 滚动区域总行数
  */
 export function calculateVisibleRows(terminalRows: number): number {
-  // 固定行：标题(1) + 快照摘要 + 顶部分隔线 + 底部分隔线 + 底栏（后四项 = PANEL_FIXED_ROWS）
+  // 固定行：标题(1) + 配置分支信息 + 快照摘要 + 顶部分隔线 + 底部分隔线 + 底栏（后五项 = PANEL_FIXED_ROWS）
   const fixedRows = PANEL_FIXED_ROWS + 1;
   return Math.max(terminalRows - fixedRows, 3);
 }

package/src/utils/project-config.ts

@@ -1,10 +1,11 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { PROJECTS_CONFIG_DIR, MESSAGES } from '../constants/index.js';
+import { PROJECTS_CONFIG_DIR, MESSAGES, VALIDATE_BRANCH_PREFIX } from '../constants/index.js';
 import { ClawtError } from '../errors/index.js';
 import { logger } from '../logger/index.js';
-import { getProjectName } from './git.js';
+import { getProjectName, checkBranchExists, getCurrentBranch } from './git.js';
 import { ensureDir } from './fs.js';
+import { printWarning, confirmAction } from './formatter.js';
 import type { ProjectConfig } from '../types/index.js';
 
 /**
@@ -76,6 +77,42 @@ export function getMainWorkBranch(): string {
   return config.clawtMainWorkBranch;
 }
 
+/**
+ * 守卫检测：仅验证配置中的主工作分支是否存在
+ * 分支不存在 → 抛出 ClawtError（致命错误）
+ * 适用于不需要分支一致性检测的场景（如 home 命令）
+ * @param {string} [cwd] - 工作目录
+ */
+export function guardMainWorkBranchExists(cwd?: string): void {
+  const config = requireProjectConfig();
+  const mainBranch = config.clawtMainWorkBranch;
+
+  if (!checkBranchExists(mainBranch, cwd)) {
+    throw new ClawtError(MESSAGES.GUARD_BRANCH_NOT_EXISTS(mainBranch));
+  }
+}
+
+/**
+ * 守卫检测：验证配置中的主工作分支是否有效
+ * 分支不存在 → 抛出 ClawtError（致命错误）
+ * 当前分支与配置分支不一致且非验证分支 → 警告并交互确认是否继续
+ * @param {string} [cwd] - 工作目录
+ */
+export async function guardMainWorkBranch(cwd?: string): Promise<void> {
+  guardMainWorkBranchExists(cwd);
+
+  const config = requireProjectConfig();
+  const mainBranch = config.clawtMainWorkBranch;
+  const currentBranch = getCurrentBranch(cwd);
+  if (currentBranch !== mainBranch && !currentBranch.startsWith(VALIDATE_BRANCH_PREFIX)) {
+    printWarning(MESSAGES.GUARD_BRANCH_MISMATCH(mainBranch, currentBranch));
+    const confirmed = await confirmAction('是否继续执行？');
+    if (!confirmed) {
+      throw new ClawtError(MESSAGES.DESTRUCTIVE_OP_CANCELLED);
+    }
+  }
+}
+
 /**
  * 从项目配置中获取 validate 成功后自动执行的命令
  * @returns {string | undefined} 配置的命令字符串，未配置时返回 undefined

package/src/utils/validation.ts

@@ -2,6 +2,19 @@ import { MESSAGES } from '../constants/index.js';
 import { ClawtError } from '../errors/index.js';
 import { execCommand } from './shell.js';
 import { getGitCommonDir } from './git.js';
+import { requireProjectConfig, guardMainWorkBranchExists } from './project-config.js';
+
+/** 统一前置校验选项 */
+interface PreCheckOptions {
+  /** 校验是否在主 worktree 根目录 */
+  mainWorktree?: boolean;
+  /** 校验 HEAD 是否存在（仓库有至少一次 commit） */
+  headExists?: boolean;
+  /** 校验项目是否已初始化（配置文件存在） */
+  projectConfig?: boolean;
+  /** 校验配置的主工作分支是否存在 */
+  branchExists?: boolean;
+}
 
 /**
  * 校验当前目录是否为主 worktree 的根目录
@@ -46,3 +59,40 @@ export function validateClaudeCodeInstalled(): void {
     throw new ClawtError(MESSAGES.CLAUDE_NOT_INSTALLED);
   }
 }
+
+/**
+ * 校验 HEAD 是否存在（仓库是否有至少一次 commit）
+ * git init 后未做任何 commit 时，HEAD 不指向有效引用
+ * @throws {ClawtError} HEAD 不存在时抛出
+ */
+export function validateHeadExists(): void {
+  try {
+    execCommand('git rev-parse --verify HEAD');
+  } catch {
+    throw new ClawtError(MESSAGES.HEAD_NOT_FOUND);
+  }
+}
+
+/**
+ * 统一前置校验入口，按需执行各项校验
+ * @param {PreCheckOptions} options - 校验选项
+ * @param {boolean} [options.mainWorktree] - 校验是否在主 worktree 根目录
+ * @param {boolean} [options.headExists] - 校验 HEAD 是否存在
+ * @param {boolean} [options.projectConfig] - 校验项目是否已初始化
+ * @param {boolean} [options.branchExists] - 校验配置的主工作分支是否存在
+ * @throws {ClawtError} 任一校验未通过时抛出
+ */
+export function runPreChecks(options: PreCheckOptions): void {
+  if (options.mainWorktree) {
+    validateMainWorktree();
+  }
+  if (options.headExists) {
+    validateHeadExists();
+  }
+  if (options.projectConfig) {
+    requireProjectConfig();
+  }
+  if (options.branchExists) {
+    guardMainWorkBranchExists();
+  }
+}

package/tests/unit/commands/cover-validate.test.ts

@@ -29,7 +29,7 @@ vi.mock('../../../src/constants/index.js', () => ({
 }));
 
 vi.mock('../../../src/utils/index.js', () => ({
-  validateMainWorktree: vi.fn(),
+  runPreChecks: vi.fn(),
   requireProjectConfig: vi.fn(),
   getProjectName: vi.fn().mockReturnValue('test-project'),
   getGitTopLevel: vi.fn().mockReturnValue('/repo'),
@@ -48,6 +48,8 @@ vi.mock('../../../src/utils/index.js', () => ({
   printInfo: vi.fn(),
   isWorkingDirClean: vi.fn().mockReturnValue(false),
   confirmAction: vi.fn().mockResolvedValue(true),
+  guardMainWorkBranch: vi.fn().mockResolvedValue(undefined),
+  guardMainWorkBranchExists: vi.fn(),
 }));
 
 import { registerCoverValidateCommand, extractTargetBranchName, findTargetWorktreePath, computeIncrementalPatch } from '../../../src/commands/cover-validate.js';

package/tests/unit/commands/create.test.ts

@@ -24,7 +24,7 @@ vi.mock('../../../src/constants/index.js', () => ({
 }));
 
 vi.mock('../../../src/utils/index.js', () => ({
-  validateMainWorktree: vi.fn(),
+  runPreChecks: vi.fn(),
   createWorktrees: vi.fn(),
   getConfigValue: vi.fn().mockReturnValue(true),
   requireProjectConfig: vi.fn().mockReturnValue({ clawtMainWorkBranch: 'main' }),
@@ -33,17 +33,19 @@ vi.mock('../../../src/utils/index.js', () => ({
   printSuccess: vi.fn(),
   printInfo: vi.fn(),
   printSeparator: vi.fn(),
+  guardMainWorkBranch: vi.fn().mockResolvedValue(undefined),
+  guardMainWorkBranchExists: vi.fn(),
 }));
 
 import { registerCreateCommand } from '../../../src/commands/create.js';
-import { validateMainWorktree, createWorktrees, printSuccess } from '../../../src/utils/index.js';
+import { runPreChecks, createWorktrees, printSuccess } from '../../../src/utils/index.js';
 
-const mockedValidateMainWorktree = vi.mocked(validateMainWorktree);
+const mockedRunPreChecks = vi.mocked(runPreChecks);
 const mockedCreateWorktrees = vi.mocked(createWorktrees);
 const mockedPrintSuccess = vi.mocked(printSuccess);
 
 beforeEach(() => {
-  mockedValidateMainWorktree.mockReset();
+  mockedRunPreChecks.mockReset();
   mockedCreateWorktrees.mockReset();
   mockedPrintSuccess.mockReset();
 });
@@ -68,7 +70,7 @@ describe('handleCreate', () => {
     registerCreateCommand(program);
     await program.parseAsync(['create', '-b', 'feature'], { from: 'user' });
 
-    expect(mockedValidateMainWorktree).toHaveBeenCalled();
+    expect(mockedRunPreChecks).toHaveBeenCalled();
     expect(mockedCreateWorktrees).toHaveBeenCalledWith('feature', 1);
     expect(mockedPrintSuccess).toHaveBeenCalled();
   });

package/tests/unit/commands/init.test.ts

@@ -22,7 +22,8 @@ vi.mock('../../../src/constants/index.js', () => ({
 }));
 
 vi.mock('../../../src/utils/index.js', () => ({
-  validateMainWorktree: vi.fn(),
+  runPreChecks: vi.fn(),
+  validateHeadExists: vi.fn(),
   getCurrentBranch: vi.fn().mockReturnValue('main'),
   loadProjectConfig: vi.fn(),
   saveProjectConfig: vi.fn(),
@@ -31,6 +32,8 @@ vi.mock('../../../src/utils/index.js', () => ({
   printInfo: vi.fn(),
   safeStringify: vi.fn((value: unknown, indent: number = 2) => JSON.stringify(value, null, indent)),
   interactiveConfigEditor: vi.fn(),
+  guardMainWorkBranch: vi.fn().mockResolvedValue(undefined),
+  guardMainWorkBranchExists: vi.fn(),
 }));
 
 import { registerInitCommand } from '../../../src/commands/init.js';