harveyz-skill 0.7.0 → 0.9.0

package/lib/installer.js

@@ -53,20 +53,60 @@ export async function installTools(tools, targetDir, force = false) {
 
     const destExists = await fs.pathExists(destPath)
     if (destExists && !force) {
+      // Version-aware upgrade logic (mirrors skill behavior)
+      const home          = os.homedir()
+      const dataDir       = path.join(home, '.local', 'share', 'hskill', 'tools')
+      const installedMeta = path.join(dataDir, `${toolName}.json`)
+      const sourceMeta    = path.join(srcPath, 'tool.json')
+
+      let installedVersion = '—'
+      let sourceVersion    = '—'
+      try { installedVersion = (await fs.readJson(installedMeta)).version ?? '—' } catch { /* missing */ }
+      try { sourceVersion    = (await fs.readJson(sourceMeta)).version    ?? '—' } catch { /* missing */ }
+
+      const isUpToDate = installedVersion !== '—' && sourceVersion !== '—' && installedVersion === sourceVersion
+
+      if (isUpToDate) {
+        skipped.push({ name: toolName, reason: 'up-to-date', version: installedVersion })
+        console.error(chalk.dim(`  · Skipped ${toolName} (up-to-date ${installedVersion})`))
+        continue
+      }
+
+      // Outdated: prompt in TTY, skip in non-TTY
       if (!process.stdout.isTTY) {
-        skipped.push({ name: toolName, reason: 'already_exists' })
-        console.error(chalk.dim(`  · Skipped ${toolName} (already exists — use --force to overwrite)`))
+        skipped.push({ name: toolName, reason: 'outdated', installed: installedVersion, available: sourceVersion })
+        console.error(chalk.dim(`  · Skipped ${toolName} (outdated ${installedVersion} → ${sourceVersion}, use --force to overwrite)`))
         continue
       }
-      const ok = await confirm({ message: `${destPath} already exists. Overwrite?`, default: true })
+
+      const ok = await confirm({
+        message: `${toolName} ${installedVersion} → ${sourceVersion}. Overwrite?`,
+        default: true,
+      })
       if (!ok) {
-        skipped.push({ name: toolName, reason: 'already_exists' })
+        skipped.push({ name: toolName, reason: 'outdated', installed: installedVersion, available: sourceVersion })
         console.error(chalk.dim(`  · Skipped ${toolName}`))
         continue
       }
     }
 
     try {
+      // Clean up uninstallPaths declared in tool.json (e.g. venv) before overwriting
+      try {
+        const meta = await fs.readJson(path.join(srcPath, 'tool.json'))
+        const home = os.homedir()
+        for (const p of (meta.uninstallPaths ?? [])) {
+          const resolved = p.replace(/^~/, home)
+          if (await fs.pathExists(resolved)) {
+            await fs.remove(resolved)
+            console.error(chalk.green(`  ✓ Removed ${p}`))
+          }
+        }
+        if ((meta.uninstallPaths ?? []).length > 0) {
+          console.error(chalk.dim(`  · venv will be recreated on next launch`))
+        }
+      } catch { /* tool.json missing or no uninstallPaths — skip silently */ }
+
       const varDefs = await loadVarDefs(srcPath)
       let varsMap = {}
       if (varDefs.length > 0) {
@@ -90,13 +130,22 @@ export async function installTools(tools, targetDir, force = false) {
       const content = await fs.readFile(scriptSrc, 'utf-8')
       await fs.writeFile(destPath, substituteVars(content, varsMap), { encoding: 'utf-8', mode: 0o755 })
 
+      const dataDir = path.join(os.homedir(), '.local', 'share', 'hskill', 'tools')
+
       const toolJsonSrc = path.join(srcPath, 'tool.json')
       if (await fs.pathExists(toolJsonSrc)) {
-        const dataDir = path.join(os.homedir(), '.local', 'share', 'hskill', 'tools')
         await fs.ensureDir(dataDir)
         await fs.copy(toolJsonSrc, path.join(dataDir, `${toolName}.json`))
       }
 
+      // Copy companion Python module (e.g. p_launch.py) when present
+      const pyModSrc = path.join(srcPath, `${toolName.replace('-', '_')}.py`)
+      if (await fs.pathExists(pyModSrc)) {
+        await fs.ensureDir(dataDir)
+        await fs.copy(pyModSrc, path.join(dataDir, `${toolName}.py`))
+        console.error(chalk.dim(`  · Installed ${toolName}.py`))
+      }
+
       installed.push(toolName)
       await _patchZshrc(srcPath, toolName)
     } catch (err) {
@@ -255,6 +304,53 @@ function _hookCommand(hookName, scope) {
     : `bash "$(git rev-parse --show-toplevel 2>/dev/null || echo .)/.claude/hooks/${hookName}.sh"`
 }
 
+function _codexHooksDir(scope, projectDir) {
+  return scope === 'user'
+    ? path.join(os.homedir(), '.codex', 'hooks')
+    : path.join(projectDir, '.codex', 'hooks')
+}
+
+function _codexHooksJsonPath(scope, projectDir) {
+  return scope === 'user'
+    ? path.join(os.homedir(), '.codex', 'hooks.json')
+    : path.join(projectDir, '.codex', 'hooks.json')
+}
+
+async function _patchCodexHooks(hooksJsonPath, hook, resolvedCommand, force) {
+  let data = { hooks: {} }
+  try {
+    data = JSON.parse(await fs.readFile(hooksJsonPath, 'utf-8'))
+  } catch { /* file doesn't exist yet */ }
+
+  if (!data.hooks) data.hooks = {}
+  if (!data.hooks[hook.event]) data.hooks[hook.event] = []
+
+  const alreadyRegistered = data.hooks[hook.event].some(entry =>
+    Array.isArray(entry.hooks) && entry.hooks.some(h => h.command === resolvedCommand)
+  )
+
+  if (alreadyRegistered && !force) return false
+  if (alreadyRegistered && force) {
+    data.hooks[hook.event] = data.hooks[hook.event].filter(entry =>
+      !Array.isArray(entry.hooks) || !entry.hooks.some(h => h.command === resolvedCommand)
+    )
+  }
+
+  // Codex format: no "type" field, absolute path
+  const hookEntry = { command: resolvedCommand }
+  if (hook.timeout)       hookEntry.timeout       = hook.timeout
+  if (hook.statusMessage) hookEntry.statusMessage = hook.statusMessage
+
+  data.hooks[hook.event].push({
+    matcher: hook.matcher ?? '',
+    hooks: [hookEntry],
+  })
+
+  await fs.ensureDir(path.dirname(hooksJsonPath))
+  await fs.writeFile(hooksJsonPath, JSON.stringify(data, null, 2) + '\n', 'utf-8')
+  return true
+}
+
 async function _patchSettings(settingsPath, hook, scope, force) {
   let settings = {}
   try {
@@ -361,6 +457,198 @@ export async function installHooks(hooks, scope, projectDir, force = false) {
   return { installed, skipped, failed }
 }
 
+// Install hooks for a specific target ('claude' or 'codex').
+// Returns { installed, skipped, failed } — same shape as installHooks.
+export async function installHooksForTarget(hooks, target, scope, projectDir, force = false) {
+  if (target === 'claude') {
+    return installHooks(hooks, scope, projectDir, force)
+  }
+
+  // target === 'codex'
+  const hooksDir      = _codexHooksDir(scope, projectDir)
+  const hooksJsonPath = _codexHooksJsonPath(scope, projectDir)
+
+  await fs.ensureDir(hooksDir)
+
+  const installed = []
+  const skipped   = []
+  const failed    = []
+
+  for (const hook of hooks) {
+    const destScript   = path.join(hooksDir, `${hook.name}.sh`)
+    const scriptExists = await fs.pathExists(destScript)
+
+    if (scriptExists && !force) {
+      const installedVersion = readHookVersion(destScript)
+      const availableVersion = hook.version
+
+      if (availableVersion && installedVersion === availableVersion) {
+        skipped.push({ name: hook.name, reason: 'up-to-date', version: installedVersion })
+        console.error(chalk.dim(`  · Skipped ${hook.name} (up-to-date ${installedVersion})`))
+        continue
+      }
+
+      if (!process.stdout.isTTY) {
+        skipped.push({ name: hook.name, reason: 'outdated', installed: installedVersion, available: availableVersion ?? '—' })
+        console.error(chalk.dim(`  · Skipped ${hook.name} (outdated ${installedVersion} → ${availableVersion}, use --force)`))
+        continue
+      }
+
+      const ok = await confirm({ message: `${hook.name} ${installedVersion} → ${availableVersion}. Overwrite?`, default: false })
+      if (!ok) {
+        skipped.push({ name: hook.name, reason: 'outdated', installed: installedVersion, available: availableVersion ?? '—' })
+        console.error(chalk.dim(`  · Skipped ${hook.name}`))
+        continue
+      }
+    }
+
+    try {
+      if (!await fs.pathExists(hook.srcPath)) {
+        failed.push({ name: hook.name, reason: 'source_not_found' })
+        console.error(chalk.red(`  ✗ Source not found: ${hook.srcPath}`))
+        continue
+      }
+
+      await fs.copy(hook.srcPath, destScript, { overwrite: true })
+      await fs.chmod(destScript, 0o755)
+
+      const resolvedCommand = destScript  // absolute path for Codex
+      await _patchCodexHooks(hooksJsonPath, hook, resolvedCommand, force)
+
+      installed.push(hook.name)
+      console.error(chalk.green(`  ✓ ${hook.name} → ${destScript}`))
+    } catch (err) {
+      failed.push({ name: hook.name, reason: 'copy_failed', detail: err.message })
+      console.error(chalk.red(`  ✗ Failed to install ${hook.name}: ${err.message}`))
+    }
+  }
+
+  return { installed, skipped, failed }
+}
+
+// ── Tool uninstall ────────────────────────────────────────────────────────────
+
+/**
+ * Uninstall a shell tool and clean up all associated files.
+ * @param {string} toolName
+ * @param {{ yes?: boolean }} opts  - yes: skip configPaths confirmation
+ */
+export async function uninstallTool(toolName, opts = {}) {
+  const { yes = false } = opts
+  const home     = os.homedir()
+  const binPath  = path.join(home, '.local', 'bin', toolName)
+  const dataDir  = path.join(home, '.local', 'share', 'hskill', 'tools')
+  const jsonPath = path.join(dataDir, `${toolName}.json`)
+  const pyPath   = path.join(dataDir, `${toolName}.py`)
+
+  // Check if installed
+  if (!await fs.pathExists(binPath) && !await fs.pathExists(jsonPath)) {
+    console.error(chalk.dim(`  · ${toolName} is not installed`))
+    return { removed: [], skipped: [], failed: [] }
+  }
+
+  const removed  = []
+  const skipped  = []
+  const failed   = []
+
+  // Read tool.json for extended paths (before removing it)
+  let uninstallPaths = []
+  let configPaths    = []
+  try {
+    const meta = JSON.parse(await fs.readFile(jsonPath, 'utf-8'))
+    uninstallPaths = (meta.uninstallPaths ?? []).map(p => p.replace(/^~/, home))
+    configPaths    = (meta.configPaths    ?? []).map(p => p.replace(/^~/, home))
+  } catch { /* tool.json missing or unreadable — proceed with standard paths only */ }
+
+  // Helper: remove a path (file or dir)
+  async function removePath(p) {
+    if (!await fs.pathExists(p)) return
+    try {
+      await fs.remove(p)
+      console.error(chalk.green(`  ✓ Removed ${p.replace(home, '~')}`))
+      removed.push(p)
+    } catch (err) {
+      console.error(chalk.red(`  ✗ Failed to remove ${p.replace(home, '~')}: ${err.message}`))
+      failed.push(p)
+    }
+  }
+
+  // 1. Standard paths
+  await removePath(binPath)
+  await removePath(pyPath)
+  await removePath(jsonPath)
+
+  // 2. uninstallPaths (always remove)
+  for (const p of uninstallPaths) await removePath(p)
+
+  // 3. configPaths (ask or skip)
+  for (const p of configPaths) {
+    if (!await fs.pathExists(p)) continue
+    if (yes) {
+      await removePath(p)
+    } else if (process.stdout.isTTY) {
+      const ok = await confirm({
+        message: `Remove ${p.replace(home, '~')}? (user config)`,
+        default: false,
+      })
+      if (ok) {
+        await removePath(p)
+      } else {
+        skipped.push(p)
+        console.error(chalk.dim(`  · Kept ${p.replace(home, '~')}`))
+      }
+    } else {
+      skipped.push(p)
+      console.error(chalk.dim(`  · Kept ${p.replace(home, '~')} (remove manually if needed)`))
+    }
+  }
+
+  // 4. Remove zshrc snippet
+  const zshrcPath = path.join(home, '.zshrc')
+  const startMarker = `# >>> ${toolName}`
+  const endMarker   = `# <<< ${toolName}`
+  try {
+    const content = await fs.readFile(zshrcPath, 'utf-8')
+    const startIdx = content.indexOf(startMarker)
+    const endIdx   = content.indexOf(endMarker)
+    if (startIdx !== -1 && endIdx !== -1) {
+      const cleaned = content.slice(0, startIdx) + content.slice(endIdx + endMarker.length + 1)
+      await fs.writeFile(zshrcPath, cleaned, 'utf-8')
+      console.error(chalk.green(`  ✓ Removed snippet from ~/.zshrc`))
+      removed.push('~/.zshrc snippet')
+    }
+  } catch { /* .zshrc doesn't exist or not readable */ }
+
+  return { removed, skipped, failed }
+}
+
+/**
+ * Uninstall a skill from a specific target directory.
+ * @param {string} skillName
+ * @param {string} targetDir  - full path to target skills dir (e.g. ~/.claude/skills)
+ */
+export async function uninstallSkill(skillName, targetDir) {
+  const skillPath = path.join(targetDir, skillName)
+  const removed = [], skipped = [], failed = []
+
+  if (!await fs.pathExists(skillPath)) {
+    console.error(chalk.dim(`  · ${skillName} not installed in ${targetDir.replace(os.homedir(), '~')}`))
+    skipped.push(skillName)
+    return { removed, skipped, failed }
+  }
+
+  try {
+    await fs.remove(skillPath)
+    console.error(chalk.green(`  ✓ Removed ${skillPath.replace(os.homedir(), '~')}`))
+    removed.push(skillName)
+  } catch (err) {
+    console.error(chalk.red(`  ✗ Failed to remove ${skillPath.replace(os.homedir(), '~')}: ${err.message}`))
+    failed.push(skillName)
+  }
+
+  return { removed, skipped, failed }
+}
+
 export async function uninstallHook(hookName, scope, projectDir) {
   const hooksDir     = _hooksDir(scope, projectDir)
   const settingsPath = _settingsPath(scope, projectDir)

package/lib/targets.js

@@ -42,3 +42,12 @@ export function resolveTargets(selected, scope = 'user') {
     return { name, dir: skillDir(name, scope) }
   })
 }
+
+export const HOOK_TARGETS = ['claude', 'codex']
+
+export function buildHookTargetChoices() {
+  return [
+    { name: `${'claude'.padEnd(8)} (~/.claude/hooks/)`, value: 'claude' },
+    { name: `${'codex'.padEnd(8)} (~/.codex/hooks/)`, value: 'codex' },
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harveyz-skill",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Skill manager for Claude Code, Cursor, and Codex",
   "type": "module",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "prepack": "node scripts/generate-npmignore.js",
-    "test": "bats tests/ tools/p-launch/tests/ && bash scripts/run-skill-tests.sh"
+    "test": "bats tests/ && cd tools/p-launch && python3 -m pytest tests/test_p_launch.py -v && cd ../.. && bash scripts/run-skill-tests.sh"
   },
   "files": [
     "bin/",
@@ -31,6 +31,7 @@
     "skills/writing/mermaid-diagram/",
     "skills/design/sync-design-html/",
     "skills/analysis/git-cleanup/",
+    "skills/meta/contribute-skill/",
     "tools/p-launch/",
     "hooks/check-similar-branch/"
   ],

package/skills/harness/git-workflow-init/SKILL.md

@@ -2,7 +2,7 @@
 name: git-workflow-init
 description: 初始化或更新 git 分支管理规范：读取项目的 workflow-config.yml，审核配置，差量生成并部署 git hooks（pre-commit、commit-msg、pre-push、post-checkout），生成工作流文档，可选写入 AI 配置文件引用。支持差量更新、MANAGED 块 hash 校验（检测用户手改）、lock 文件 diff（检测配置变更）、conflict scanner（检测用户代码与新配置的交叉冲突）。触发时机：初始化新 git 仓库、新项目首次配置 git、用户要求设置/更新分支保护或分支规范、安装或重新部署 git hooks、skill 或模板更新后需要同步、或问到分支命名规范。只要项目需要配置或更新 git 工作流，就应使用此 skill。
 user_invocable: true
-version: "4.0.0"
+version: "4.1.0"
 ---
 
 # Git 工作流初始化
@@ -66,114 +66,33 @@ echo "" | grep -E "<pattern>" > /dev/null 2>&1; echo $?
 
 **首次安装时跳过此步骤，直接进入 Step 5。**
 
-此步骤目标：在写入任何文件之前，全面了解当前状态，收集所有需要用户决策的冲突，在 Step 5 一次性呈现。
+目标：写入任何文件之前，全面收集需要用户决策的冲突，在 Step 5 一次性呈现。实现细节见 `references/conflict-analysis.md`。
 
-#### 4a. Lock 文件 diff — 配置发生了什么变化
+#### 4a. Lock 文件 diff
+读取 `.githooks/.workflow-config.lock.yml`（不存在则视为全量新增，跳过）。对比上次配置与当前配置，生成 +/~/- 变更摘要。**提取 YAML 分支名时必须用 python3 精确解析，不得用 `grep "name:"`**（见 reference 中的脚本）。
 
-读取 `.githooks/.workflow-config.lock.yml`（若不存在则视为全量新增，跳过 diff）。
+#### 4b. MANAGED 块 hash 校验
+读取每个 hook 的 `BEGIN MANAGED`/`END MANAGED` 块，重新计算 hash，与块头标记对比。不一致 → 用户手改，记录为类型 C 冲突（附 diff）。
 
-将 lock 文件中记录的上一次配置与当前配置对比，生成变更摘要：
+#### 4c. 外部代码扫描
+提取每个 hook 中 MANAGED 块外的用户手写代码，识别其中引用的分支名、提交类型、pattern、外部脚本调用。
 
-```
-配置变更摘要：
-+ branches.protected 新增: develop（merge_from: feature/*）
-~ commit_message.conventional.types 修改: 新增 wip，移除 perf
-- tags.allowed_patterns 删除: ^v[0-9]+\.[0-9]+\.[0-9]+-rc\.[0-9]+$
-```
-
-**YAML 分支名提取规则（重要）：**
-
-不要用宽泛的 `grep "name:"` 提取分支名——YAML 多个层级都可能含有 `name:` 字段，会导致误匹配。用 `python3` 精确解析，进入 `protected:` 块后再匹配 `- name:`，遇到非缩进行则停止：
-
-```bash
-# FILE 传入要解析的文件路径（workflow-config.yml 或 lock 文件均适用）
-python3 -c "
-import re, sys
-content = open(sys.argv[1]).read()
-in_protected = False
-for line in content.splitlines():
-    if 'protected:' in line:
-        in_protected = True; continue
-    if in_protected:
-        m = re.match(r'\s+- name:\s+(\S+)', line)
-        if m: print(m.group(1))
-        elif line.strip() and not line.startswith(' '): break
-" "$FILE"
-```
-
-这份摘要用于后续冲突检测的输入。
-
-#### 4b. MANAGED 块 hash 校验 — 用户是否手改了生成的代码
-
-读取每个 hook 文件，提取所有 `BEGIN MANAGED` / `END MANAGED` 块。
-
-MANAGED 块格式：
-```sh
-# --- BEGIN MANAGED: <block-id> (hash:<8位hex>) ---
-<generated content>
-# --- END MANAGED: <block-id> ---
-```
-
-对每个块：重新计算块内容（两行标记之间的部分，去首尾空白）的 hash：
-```bash
-actual_hash=$(printf '%s' "<block_content>" | git hash-object --stdin | cut -c1-8)
-```
-
-若 `actual_hash` 与标记里记录的 hash 不一致 → 用户手改了此块，记录为冲突：
-
-```
-[手改冲突] .githooks/pre-commit 的 MANAGED 块 branches.protected/main 被手动修改
-  原始生成内容 hash: a3f9c2b1
-  当前内容 hash:     d7e42f0c
-  差异：（展示 diff）
-```
-
-#### 4c. 外部代码扫描 — 用户在 MANAGED 块外添加了什么
-
-提取每个 hook 文件中 MANAGED 块之外的所有代码（即用户手写区）。
-
-从用户代码中提取可解析的引用：
-
-| 提取目标 | 扫描方式 |
-|---------|---------|
-| 分支名 | `"$BRANCH" = "name"`、`case "name"`、`branch = "name"` |
-| 提交类型 | `grep -qE "...(type\|...)"`、字符串字面量 `wip`、`hotfix` |
-| Tag/分支 pattern | `grep -qE "pattern"` |
-| 外部脚本调用 | `./`、`bash `、`sh `、`npm run`、`make ` 开头的行 |
-
-#### 4d. 冲突检测 — 用户代码 × 新配置的交叉分析
-
-综合 4a（配置变更）、4b（手改块）、4c（用户代码）的结果，识别以下冲突类型：
-
-**冲突类型 A：用户代码覆盖了与新配置相同的条件**
-- 用户代码处理了分支 X，新配置也将 X 加入 `branches.protected`
-- 两段代码同时执行，可能产生矛盾行为
-
-**冲突类型 B：用户代码引用了配置中已删除的内容**
-- 用户代码里有对类型 `wip` 的处理，新配置删除了 `wip`
-- 用户代码逻辑失去对应的配置支撑
-
-**冲突类型 C：MANAGED 块被手动修改**
-- 来自 4b 的结果
-- 重新生成会覆盖用户修改
-
-**冲突类型 D：用户代码引用了新配置新增的内容（信息提示，非阻断）**
-- 用户已手写了对 `develop` 的处理，新配置也打算生成同名 MANAGED 块
-- 不一定冲突，但值得用户确认
+#### 4d. 冲突检测
+综合 4a/4b/4c，识别四种冲突类型（A 条件重叠、B 引用断裂、C 手改冲突、D 新增重叠）。类型定义与选项见 `references/conflict-analysis.md`。
 
 ---
 
 ### Step 5 — 冲突解决（一次性汇总，用户逐条决策）
 
-将 Step 4 发现的所有冲突汇总后**一次性呈现**，每条冲突附带建议选项。
+将 Step 4 发现的所有冲突**一次性呈现**，每条附带类型标签和选项，用户逐条决策后进入 Step 6。无冲突则直接进入 Step 6。
 
-示例输出：
+呈现格式（以类型 C 手改冲突为例）：
 
 ```
-发现 3 处需要决策的冲突，请逐条确认：
+发现 N 处需要决策的冲突，请逐条确认：
 
 ─────────────────────────────────────────────────────────
-[1/3] 手改冲突（类型 C）
+[1/N] 手改冲突（类型 C）
 文件: .githooks/pre-commit，块: branches.protected/main
 用户对生成代码做了如下修改：
   - echo "❌ 禁止直接在 main 上提交。"
@@ -182,26 +101,9 @@ actual_hash=$(printf '%s' "<block_content>" | git hash-object --stdin | cut -c1-
   A) 保留用户修改（此块不重新生成）
   B) 用新配置覆盖（丢弃用户修改）
 ─────────────────────────────────────────────────────────
-[2/3] 条件重叠（类型 A）
-文件: .githooks/pre-commit，用户代码第 58 行
-用户手写了 develop 分支的保护逻辑
-新配置将 develop 加入 branches.protected，也会生成对应 MANAGED 块
-选项：
-  A) 保留用户代码，跳过生成 develop 的 MANAGED 块
-  B) 用新配置生成 MANAGED 块，删除用户手写的重复代码
-  C) 两者都保留（会重复执行，请确认逻辑不矛盾）
-─────────────────────────────────────────────────────────
-[3/3] 引用断裂（类型 B）
-文件: .githooks/commit-msg，用户代码第 34 行
-用户代码引用了 commit 类型 wip，但新配置已从类型列表中移除 wip
-选项：
-  A) 保留用户代码（wip 检查逻辑继续生效，但配置层不再管理）
-  B) 删除用户代码中对 wip 的引用
-─────────────────────────────────────────────────────────
 ```
 
-用户全部决策完成后，带着决策结果进入 Step 6。
-若无任何冲突，直接进入 Step 6。
+各冲突类型的完整选项定义见 `references/conflict-analysis.md`。
 
 ---
 
@@ -237,6 +139,19 @@ git config merge.ff false
 
 ---
 
+### Step 6.5 — 验收测试（可选）
+
+完成 hooks 部署后，询问用户：
+
+```
+✅ Hooks 已部署完毕。是否运行验收测试？（在当前 repo 中验证 hooks 实际拦截行为）[y/N]
+```
+
+- 用户选 **N** → 直接进入 Step 7。
+- 用户选 **Y** → 读取 `references/acceptance-test.md`，按其中说明逐 hook 执行验收场景，展示结果表格。全通过则继续 Step 7；有失败则展示详情并询问用户是否仍继续。
+
+---
+
 ### Step 7 — 从配置渲染并写入工作流文档（差量）
 
 每次运行都根据当前 `workflow-config.yml` 的最终状态重新渲染文档，确保文档与配置始终一致。
@@ -315,7 +230,9 @@ CLAUDE.md                          已有引用，跳过
 | 文件 | 说明 | 读取时机 |
 |------|------|---------|
 | `references/workflow-config.yml` | 配置文件模板 | Step 2：用户无配置时复制 |
+| `references/conflict-analysis.md` | 4a–4d 实现脚本、冲突类型 A/B/C/D 完整定义与选项、Step 5 呈现格式 | Step 4/5：执行分析前读取 |
 | `references/hook-templates.md` | 4 个 hook 的代码模板、块 ID 规范、hash 计算、多行写入技巧 | Step 6：生成 hooks 前 |
+| `references/acceptance-test.md` | 验收场景 bash 脚本、期望结果、结果表格格式 | Step 6.5：用户选 Y 时读取 |
 | `references/lock-file-format.md` | lock 文件 YAML 格式 | Step 9：写入 lock 文件前 |
 | `references/git-workflow-template.md` | 工作流文档模板（含占位符） | Step 7：由 render_docs.py 读取 |
 | `references/render_docs.py` | 文档渲染脚本 | Step 7：直接执行 |