specline 1.2.2 → 1.3.0

package/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { existsSync, mkdirSync, readdirSync, copyFileSync, writeFileSync, readFileSync } from 'fs';
-import { join, dirname, resolve, relative } from 'path';
+import { join, dirname, resolve, relative, basename } from 'path';
 import { fileURLToPath } from 'url';
 import { createHash } from 'crypto';
 import { get } from 'https';
@@ -193,6 +193,149 @@ function copyDirRecursive(src, dest) {
   }
 }
 
+// ============================================================
+// 智能合并函数 — hooks.json / config.yaml / CONFLICT 备份
+// ============================================================
+
+/**
+ * hooks.json 语义合并：清理所有 specline-* 条目，注入模板最新官方 hook
+ */
+function mergeHooksJson(existingContent, templateContent) {
+  let existingObj, templateObj;
+  try {
+    existingObj = JSON.parse(existingContent);
+  } catch {
+    warn('hooks.json 解析失败，将使用模板完整替换');
+    return templateContent;
+  }
+  try {
+    templateObj = JSON.parse(templateContent);
+  } catch {
+    warn('模板 hooks.json 解析失败，保留现有文件');
+    return existingContent;
+  }
+
+  for (const eventName of Object.keys(templateObj.hooks || {})) {
+    if (!existingObj.hooks) {
+      existingObj.hooks = {};
+    }
+    if (!existingObj.hooks[eventName]) {
+      existingObj.hooks[eventName] = [];
+    }
+    existingObj.hooks[eventName] = existingObj.hooks[eventName].filter(
+      (entry) => !(entry.command || '').includes('specline-')
+    );
+    existingObj.hooks[eventName] = [
+      ...templateObj.hooks[eventName],
+      ...existingObj.hooks[eventName],
+    ];
+  }
+  return JSON.stringify(existingObj, null, 2) + '\n';
+}
+
+function countCustomHooks(hooksObj) {
+  let count = 0;
+  for (const eventName of Object.keys(hooksObj.hooks || {})) {
+    for (const entry of (hooksObj.hooks[eventName] || [])) {
+      if (!(entry.command || '').includes('specline-')) count++;
+    }
+  }
+  return count;
+}
+
+/**
+ * YAML 段落结构
+ */
+function parseYamlSections(content) {
+  const lines = content.split('\n');
+  const sections = [];
+  let currentComments = [];
+  let currentKey = null;
+  let currentBodyLines = [];
+  let inBody = false;
+
+  function flushSection() {
+    if (currentComments.length > 0 || currentBodyLines.length > 0 || currentKey) {
+      const bodyStr = currentBodyLines.join('\n');
+      // 判定 isEmpty：body 为空、纯注释、或仅声明 key 但无实际值
+      const bodyTrimmed = bodyStr.trim();
+      const onlyKeyDeclaration = currentKey !== null &&
+        currentBodyLines.length === 1 &&
+        bodyTrimmed.match(/^\w[\w_-]*\s*:\s*$/) !== null;
+      const isEmpty = bodyTrimmed === '' ||
+        bodyTrimmed.startsWith('#') ||
+        onlyKeyDeclaration;
+      sections.push({ key: currentKey, headerComments: [...currentComments], body: bodyStr, isEmpty });
+    }
+    currentComments = [];
+    currentKey = null;
+    currentBodyLines = [];
+    inBody = false;
+  }
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === '') { if (inBody) currentBodyLines.push(line); continue; }
+    if (trimmed.startsWith('#')) { if (inBody) currentBodyLines.push(line); else currentComments.push(line); continue; }
+    const topKeyMatch = line.match(/^(\w[\w_-]*)\s*:(.*)/);
+    if (topKeyMatch && !line.startsWith(' ') && !line.startsWith('\t')) {
+      flushSection();
+      currentKey = topKeyMatch[1];
+      currentBodyLines = [line];
+      inBody = true;
+      continue;
+    }
+    if (inBody) currentBodyLines.push(line);
+  }
+  flushSection();
+  return sections;
+}
+
+function findSection(sections, key) {
+  return sections.find((s) => s.key === key) || null;
+}
+
+function mergeConfigYaml(existingContent, templateContent) {
+  const existingSections = parseYamlSections(existingContent);
+  const templateSections = parseYamlSections(templateContent);
+  const resultLines = [];
+
+  for (const tmplSec of templateSections) {
+    const existSec = findSection(existingSections, tmplSec.key);
+    if (existSec) {
+      if (!existSec.isEmpty && existSec.body.trim() !== tmplSec.body.trim()) {
+        resultLines.push(...tmplSec.headerComments);
+        resultLines.push(existSec.body);
+      } else {
+        resultLines.push(...tmplSec.headerComments);
+        resultLines.push(tmplSec.body);
+      }
+      resultLines.push('');
+    } else if (tmplSec.key !== null) {
+      resultLines.push('# 🆕 新增配置段 (specline sync)');
+      resultLines.push(...tmplSec.headerComments);
+      resultLines.push(tmplSec.body);
+      resultLines.push('');
+    }
+  }
+
+  for (const existSec of existingSections) {
+    if (existSec.key === null) continue;
+    if (!findSection(templateSections, existSec.key)) {
+      resultLines.push(...existSec.headerComments);
+      resultLines.push(existSec.body);
+      resultLines.push('');
+    }
+  }
+  return resultLines.join('\n');
+}
+
+function backupBeforeOverwrite(destPath) {
+  const backupPath = destPath + '.orig';
+  copyFileSync(destPath, backupPath);
+  return backupPath;
+}
+
 function cmd_init(targetPath) {
   const cwd = process.cwd();
   const target = resolve(cwd, targetPath || '.');
@@ -430,9 +573,52 @@ function cmd_sync({ dryRun, targetPath }) {
 
   // 8. dryRun 模式只预览
   if (dryRun) {
+    const HOOKS_JSON = '.cursor/hooks.json';
+    const CONFIG_YAML = 'specline/config.yaml';
+    let hooksPlan = null;
+
     for (const r of results) {
-      if (r.type === 'UNCHANGED' || r.type === 'MODIFIED_ONLY') continue;
-      const labels = { NEW: '➕ 新增', WILL_UPDATE: '🔄 更新', CONFLICT: '⚠️  冲突', NO_LOCK_CONFLICT: '⚠️  无锁记录', UPSTREAM_REMOVED: '🗑️  上游移除' };
+      if (r.type === 'UNCHANGED' || r.type === 'MODIFIED_ONLY') {
+        if (r.path === HOOKS_JSON) {
+          const projPath = join(target, r.path);
+          if (existsSync(projPath)) {
+            try {
+              const existingObj = JSON.parse(readFileSync(projPath, 'utf-8'));
+              hooksPlan = { customCount: countCustomHooks(existingObj) };
+            } catch {}
+          }
+        }
+        if (r.path === CONFIG_YAML) {
+          log('💡 config.yaml: 用户已修改，保留现有配置不变');
+        }
+        continue;
+      }
+
+      if (r.path === HOOKS_JSON) {
+        hooksPlan = hooksPlan || { customCount: 0 };
+        // 读取用户现有 hooks.json，计算自定义 hook 数量
+        const projPath = join(target, r.path);
+        if (existsSync(projPath) && !hooksPlan.readFromUser) {
+          try {
+            const existingObj = JSON.parse(readFileSync(projPath, 'utf-8'));
+            hooksPlan = { customCount: countCustomHooks(existingObj), readFromUser: true };
+          } catch {}
+        }
+        let tplCount = 0;
+        try {
+          const tpl = JSON.parse(readFileSync(join(TEMPLATES_DIR, r.path), 'utf-8'));
+          for (const ev of Object.keys(tpl.hooks || {})) tplCount += (tpl.hooks[ev] || []).length;
+        } catch {}
+        log(`🔄 hooks.json 语义合并: 保留 ${hooksPlan.customCount >= 0 ? hooksPlan.customCount : '?'} 个自定义 hook, 更新 ${tplCount} 个官方 hook`);
+        continue;
+      }
+
+      if (r.path === CONFIG_YAML) {
+        log('💡 config.yaml: 保留用户配置不变，更新文档注释');
+        continue;
+      }
+
+      const labels = { NEW: '➕ 新增', WILL_UPDATE: '🔄 更新', CONFLICT: '⚠️  冲突（将备份后覆盖）', NO_LOCK_CONFLICT: '⚠️  无锁记录', UPSTREAM_REMOVED: '🗑️  上游移除' };
       log(labels[r.type] + '  ' + r.path);
     }
     if (stats.newCount === 0 && stats.updated === 0 && stats.conflicted === 0 && stats.upstreamRemoved === 0) {
@@ -445,6 +631,9 @@ function cmd_sync({ dryRun, targetPath }) {
 
   // 9. 执行写入
   const newFiles = new Map();
+  const HOOKS_JSON = '.cursor/hooks.json';
+  const CONFIG_YAML = 'specline/config.yaml';
+  const mergeStats = { hooksMerged: false, configUpdated: false, backupsCreated: 0 };
 
   for (const r of results) {
     if (r.type === 'UNCHANGED' || r.type === 'MODIFIED_ONLY') {
@@ -460,7 +649,6 @@ function cmd_sync({ dryRun, targetPath }) {
       continue;
     }
 
-    // NEW/WILL_UPDATE/CONFLICT/NO_LOCK_CONFLICT: 复制模板文件
     const srcPath = join(TEMPLATES_DIR, r.path);
     const destPath = join(target, r.path);
     const destDir = dirname(destPath);
@@ -469,13 +657,50 @@ function cmd_sync({ dryRun, targetPath }) {
     }
 
     try {
-      copyFileSync(srcPath, destPath);
-      newFiles.set(r.path, computeFileHash(destPath));
+      // 特殊文件：hooks.json 语义合并
+      if (r.path === HOOKS_JSON) {
+        const existingContent = existsSync(destPath) ? readFileSync(destPath, 'utf-8') : '{}';
+        const templateContent = readFileSync(srcPath, 'utf-8');
+        try {
+          const merged = mergeHooksJson(existingContent, templateContent);
+          writeFileSync(destPath, merged, 'utf-8');
+          newFiles.set(r.path, sha256(merged));
+          mergeStats.hooksMerged = true;
+        } catch {
+          warn('hooks.json 合并失败，将保留现有文件');
+          newFiles.set(r.path, computeFileHash(destPath));
+        }
+        continue;
+      }
+
+      // 特殊文件：config.yaml 注释合并
+      if (r.path === CONFIG_YAML) {
+        const existingContent = existsSync(destPath) ? readFileSync(destPath, 'utf-8') : '';
+        const templateContent = readFileSync(srcPath, 'utf-8');
+        try {
+          const merged = mergeConfigYaml(existingContent, templateContent);
+          writeFileSync(destPath, merged, 'utf-8');
+          newFiles.set(r.path, sha256(merged));
+          mergeStats.configUpdated = true;
+        } catch {
+          warn('config.yaml 合并失败，将保留现有文件');
+          newFiles.set(r.path, computeFileHash(destPath));
+        }
+        continue;
+      }
 
-      if (r.type === 'CONFLICT') {
-        warn('已覆盖（冲突）: ' + r.path);
-      } else if (r.type === 'NO_LOCK_CONFLICT') {
-        warn('已覆盖（无锁文件记录）: ' + r.path);
+      // CONFLICT：备份后覆盖
+      if (r.type === 'CONFLICT' || r.type === 'NO_LOCK_CONFLICT') {
+        if (existsSync(destPath)) {
+          const backupPath = backupBeforeOverwrite(destPath);
+          mergeStats.backupsCreated++;
+          warn('已覆盖（冲突，备份: ' + basename(backupPath) + '）: ' + r.path);
+        }
+        copyFileSync(srcPath, destPath);
+        newFiles.set(r.path, computeFileHash(destPath));
+      } else {
+        copyFileSync(srcPath, destPath);
+        newFiles.set(r.path, computeFileHash(destPath));
       }
     } catch (err) {
       warn(r.path + ' 写入失败：' + err.message);
@@ -493,7 +718,8 @@ function cmd_sync({ dryRun, targetPath }) {
   });
 
   // 11. 输出摘要
-  if (stats.newCount === 0 && stats.updated === 0 && stats.conflicted === 0 && stats.upstreamRemoved === 0) {
+  if (stats.newCount === 0 && stats.updated === 0 && stats.conflicted === 0 && stats.upstreamRemoved === 0
+      && !mergeStats.hooksMerged && !mergeStats.configUpdated) {
     log('所有模板文件已是最新，无需同步');
   } else {
     log('📊 同步摘要：');
@@ -503,6 +729,9 @@ function cmd_sync({ dryRun, targetPath }) {
     log('   ⚠️  已覆盖（冲突）: ' + stats.conflicted);
     log('   ⏭️  已跳过（本地修改）: ' + stats.skippedModified);
     log('   🗑️  上游已移除: ' + stats.upstreamRemoved);
+    if (mergeStats.hooksMerged) log('   🔧 hooks.json: 语义合并完成');
+    if (mergeStats.configUpdated) log('   📝 config.yaml: 注释已更新');
+    if (mergeStats.backupsCreated > 0) log('   💾 创建备份: ' + mergeStats.backupsCreated + ' 个 .orig 文件');
     log('   ✨ 锁文件已更新至 v' + VERSION);
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specline",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "Spec-driven AI coding pipeline with deterministic quality gates for Cursor IDE",
   "bin": {
     "specline": "./cli.mjs"

package/templates/.cursor/agents/specline-spec-creator.md

@@ -19,6 +19,7 @@ description: >-
 - 功能名称 → kebab-case change name（如 "添加用户登录" → `add-user-login`）
 - 核心功能点列表
 - 技术栈上下文（如果有）
+- 语言上下文（由编排者从项目检测结果注入，用于确定测试路径约定）
 
 #### Step 2: 创建目录结构
 
@@ -211,16 +212,33 @@ specline-pipeline-gate.sh new --change "<change-name>"
 ````markdown
 ### 测试文件归属
 
+根据编排者注入的项目语言上下文选择对应的测试路径约定：
+
+| 语言 | 单元测试路径 | 集成/E2E 测试路径 | 命名约定 |
+|------|------------|-----------------|---------|
+| Go | `<package>/<name>_test.go`（与源码同目录） | `tests/integration/` 或内联 | `TestXxx` 函数 |
+| Python | `tests/unit/<module>/test_<name>.py` | `tests/integration/test_<cap>.py` | `test_xxx` 函数 |
+| TypeScript/JavaScript | `__tests__/<name>.test.ts` 或 `<name>.spec.ts` | `tests/integration/<cap>.test.ts` | `describe/it` 块 |
+| Rust | `src/<mod>/tests.rs` 或 `#[cfg(test)]` 模块 | `tests/<name>.rs` | `#[test] fn xxx()` |
+
+**生成规则**：
+- 如果语言上下文为 Go：单元测试路径使用模块相对路径 + `_test.go` 后缀，不生成 `tests/unit/` 引用
+- 如果语言上下文为 Python：保持原有 `tests/unit/<module>/` 约定
+- 如果语言上下文为 TypeScript：使用 `__tests__/` 或与源码同级的 `.test.ts`
+- 如果无语言上下文（向后兼容）：使用 Python 约定作为默认
+
 | 测试文件（目录） | 测试类型 | 负责者 |
 |-----------------|---------|-------|
-| tests/unit/<module>/ | 单元测试 | Coding Agent (Task N) |
-| tests/integration/test_<capability>.py | 集成测试 | specline-test-writer |
-| tests/e2e/test_<capability>_flow.py | E2E 测试 | specline-test-writer |
+| [根据语言约定的单元测试路径] | 单元测试 | Coding Agent (Task N) |
+| [根据语言约定的集成测试路径] | 集成测试 | specline-test-writer |
+| [根据语言约定的 E2E 测试路径] | E2E 测试 | specline-test-writer |
 ````
 
 **生成规则**：
-- 对每个 `Testable: true` 的任务，从其任务描述和 Files 字段推导模块名，生成单元测试目录行（`tests/unit/<module>/` 或 `tests/models/<module>/`），负责者标注为「Coding Agent (Task N)」
-- 对 `specs/` 下每个 capability 目录，生成集成测试文件行（`tests/integration/test_<capability>.py`）和 E2E 测试文件行（`tests/e2e/test_<capability>_flow.py`），负责者标注为「specline-test-writer」
+- 根据编排者注入的语言上下文，从上方语言映射表选择对应的测试路径约定（无语言上下文时默认 Python）
+- 对每个 `Testable: true` 的任务，从其任务描述和 Files 字段推导模块名，按语言约定生成单元测试路径行，负责者标注为「Coding Agent (Task N)」
+- 对 `specs/` 下每个 capability 目录，按语言约定生成集成测试和 E2E 测试路径行，负责者标注为「specline-test-writer」
+- Go 项目禁止生成 `tests/unit/` 引用；单元测试路径使用 `_test.go` 后缀与源码同目录
 - 表格按 capability 分组，单元测试行在前、集成/E2E 测试行在后
 - 如果无 Testable: true 的任务，跳过 Coding Agent 的单元测试行，仅保留集成/E2E 行
 - **测试文件归属** 节放在所有 `## N. [ ]` 任务节之后、tasks.md 文件末尾

package/templates/.cursor/hooks/specline-pipeline-gate-checks/a1-covers-ref.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+#
+# a1-covers-ref.sh — A1: Covers 引用存在性验证
+#
+# 验证 tasks.md 中每个任务的 Covers 字段引用的 Requirement 名称和 Scenario
+# 名称在 spec.md 中实际存在。
+#
+# 兼容 bash 3.2+（macOS 默认版本），不使用关联数组（declare -A）。
+#
+# 依赖 common.sh 中定义的：
+#   - semantic_error(code, msg)
+#   - semantic_warn(code, msg)
+#   - semantic_info(code, msg)
+#   - SEMANTIC_ERRORS / SEMANTIC_WARNINGS / SEMANTIC_INFOS 全局计数器
+#
+# 环境变量：
+#   SPEC_FILE  — spec.md 的路径
+#   TASKS_FILE — tasks.md 的路径
+
+# 确保正确处理多字节 UTF-8 字符（中文 Scenario/Requirement 名称）
+export LC_ALL="${LC_ALL:-zh_CN.UTF-8}"
+
+run_a1_covers_ref() {
+  # ==== 输入校验 ====
+  if [ ! -f "${SPEC_FILE:-}" ]; then
+    semantic_error "A1" "spec.md 不存在: ${SPEC_FILE:-未设置}"
+    return
+  fi
+
+  if [ ! -f "${TASKS_FILE:-}" ]; then
+    semantic_error "A1" "tasks.md 不存在: ${TASKS_FILE:-未设置}"
+    return
+  fi
+
+  # ==== 临时文件（存储 Requirement 和 Scenario 名称集合） ====
+  # 兼容 bash 3.2，不使用 declare -A 关联数组
+  local _req_file _scen_file
+  _req_file=$(mktemp) || { semantic_error "A1" "无法创建临时文件"; return; }
+  _scen_file=$(mktemp) || { rm -f "$_req_file"; semantic_error "A1" "无法创建临时文件"; return; }
+
+  # ==== 1. 从 spec.md 提取 Requirement 和 Scenario 名称 ====
+  local current_req="" scen_name=""
+
+  while IFS= read -r line; do
+    if [[ "$line" =~ ^###[[:space:]]+Requirement:[[:space:]]+(.+)$ ]]; then
+      current_req="${BASH_REMATCH[1]}"
+      current_req=$(echo "$current_req" | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')
+      echo "$current_req" >> "$_req_file"
+    elif [[ "$line" =~ ^####[[:space:]]+Scenario:[[:space:]]+(.+)$ ]]; then
+      scen_name="${BASH_REMATCH[1]}"
+      scen_name=$(echo "$scen_name" | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')
+      if [ -n "$current_req" ]; then
+        echo "${current_req}|${scen_name}" >> "$_scen_file"
+      fi
+    fi
+  done < "$SPEC_FILE"
+
+  # ==== 2. 从 tasks.md 解析 Covers 引用 ====
+  local task_num=0
+  local covers_content req_name scenarios_str split_list
+  covers_content=""; req_name=""; scenarios_str=""; split_list=""
+
+  while IFS= read -r line; do
+    # 追踪任务编号（从 "## N." 标题行）
+    if [[ "$line" =~ ^##[[:space:]]+([0-9]+)\. ]]; then
+      task_num="${BASH_REMATCH[1]}"
+      continue
+    fi
+
+    # 跳过非 Covers 行
+    if [[ "$line" != *"**Covers**:"* ]]; then
+      continue
+    fi
+
+    # 提取 Covers 内容
+    covers_content=$(echo "$line" \
+      | sed 's/.*\*\*Covers\*\*:[[:space:]]*//' \
+      | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')
+
+    # 格式检查：必须有 "Requirement:" 前缀
+    if [[ ! "$covers_content" =~ Requirement: ]]; then
+      semantic_warn "A1" "任务 $task_num 的 Covers 行格式不规范，跳过该任务的引用验证"
+      continue
+    fi
+
+    # 提取 Requirement 名称（Requirement: 之后到第一个分隔符之前）
+    req_name=$(echo "$covers_content" \
+      | sed -n 's/.*Requirement:[[:space:]]*//p' \
+      | sed 's/[[:space:]]*[,，、].*//' \
+      | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')
+
+    if [ -z "$req_name" ]; then
+      semantic_warn "A1" "任务 $task_num 的 Covers 行缺少 Requirement 名称，跳过该任务的引用验证"
+      continue
+    fi
+
+    # 校验 Requirement 存在性
+    if ! grep -qxF "$req_name" "$_req_file" 2>/dev/null; then
+      semantic_error "A1" "Covers 引用不存在: 任务 $task_num 引用了不存在的 Requirement \"$req_name\""
+    fi
+
+    # 提取并校验 Scenario 名称列表
+    if [[ "$covers_content" =~ Scenario:[[:space:]]*(.+)$ ]]; then
+      scenarios_str="${BASH_REMATCH[1]}"
+      scenarios_str=$(echo "$scenarios_str" | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')
+
+      # 拆分 Scenario 名称（分隔符：、 ， ,）
+      split_list=$(echo "$scenarios_str" \
+        | sed 's/[、，]/\'$'\n''/g' \
+        | sed 's/,[[:space:]]*/\'$'\n''/g')
+
+      while IFS= read -r scen_name; do
+        scen_name=$(echo "$scen_name" | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')
+        [ -z "$scen_name" ] && continue
+
+        if ! grep -qxF "${req_name}|${scen_name}" "$_scen_file" 2>/dev/null; then
+          semantic_error "A1" "Covers 引用不存在: 任务 $task_num 引用了不存在的 Scenario \"$scen_name\"（在 Requirement \"$req_name\" 下）"
+        fi
+      done <<< "$split_list"
+    fi
+  done < "$TASKS_FILE"
+
+  # ==== 清理临时文件 ====
+  rm -f "$_req_file" "$_scen_file"
+}

package/templates/.cursor/hooks/specline-pipeline-gate-checks/a2-a3-reverse.sh

@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+#
+# a2-a3-reverse.sh — A2/A3 反向覆盖验证
+#
+# 从 spec.md 提取所有 Requirement 和 Scenario 名称，
+# 与 tasks.md 中 Covers 字段引用的名称做交叉比对，
+# 输出未被任何任务覆盖的 Requirement 和 Scenario（INFO 级别）。
+#
+# 依赖环境变量:
+#   SPEC_FILE  — spec.md 文件路径
+#   TASKS_FILE — tasks.md 文件路径
+#   SPEC_REVIEW_FILE — 可选，spec-review.json 路径（交叉验证）
+#
+# 使用方式:
+#   source a2-a3-reverse.sh
+#   SPEC_FILE=... TASKS_FILE=... run_a2_a3_reverse
+
+run_a2_a3_reverse() {
+  local spec_file="${SPEC_FILE:-}"
+  local tasks_file="${TASKS_FILE:-}"
+  local review_file="${SPEC_REVIEW_FILE:-}"
+
+  # 验证输入文件
+  if [ -z "$spec_file" ] || [ ! -f "$spec_file" ]; then
+    echo "ERROR: spec.md 文件不存在或未通过 SPEC_FILE 指定: ${spec_file:-未设置}" >&2
+    return 1
+  fi
+  if [ -z "$tasks_file" ] || [ ! -f "$tasks_file" ]; then
+    echo "ERROR: tasks.md 文件不存在或未通过 TASKS_FILE 指定: ${tasks_file:-未设置}" >&2
+    return 1
+  fi
+
+  # =========================================
+  # Step 1: 从 spec.md 提取所有 Requirement 和 Scenario 名称
+  # =========================================
+
+  local tmp_spec_reqs
+  tmp_spec_reqs=$(mktemp) || return 1
+  local tmp_spec_scens
+  tmp_spec_scens=$(mktemp) || return 1
+  local tmp_tasks_reqs
+  tmp_tasks_reqs=$(mktemp) || return 1
+  local tmp_tasks_scens
+  tmp_tasks_scens=$(mktemp) || return 1
+
+  _a2a3_cleanup() {
+    rm -f "$tmp_spec_reqs" "$tmp_spec_scens" "$tmp_tasks_reqs" "$tmp_tasks_scens"
+  }
+  trap _a2a3_cleanup RETURN
+
+  # 从 spec.md 解析 Requirement 和 Scenario
+  local current_req=""
+  while IFS= read -r line; do
+    if [[ "$line" =~ ^###[[:space:]]+Requirement:[[:space:]]+(.+)$ ]]; then
+      current_req="${BASH_REMATCH[1]}"
+      current_req="${current_req%"${current_req##*[![:space:]]}"}"
+      echo "$current_req" >> "$tmp_spec_reqs"
+    elif [[ "$line" =~ ^####[[:space:]]+Scenario:[[:space:]]+(.+)$ ]]; then
+      local scen="${BASH_REMATCH[1]}"
+      scen="${scen%"${scen##*[![:space:]]}"}"
+      if [ -n "$current_req" ]; then
+        printf '%s\t%s\n' "$current_req" "$scen" >> "$tmp_spec_scens"
+      fi
+    fi
+  done < "$spec_file"
+
+  # =========================================
+  # Step 2: 从 tasks.md 提取 Covers 引用的 Requirement 和 Scenario
+  # =========================================
+
+  while IFS= read -r line; do
+    if [[ "$line" =~ \*\*Covers\*\*[[:space:]]*:[[:space:]]*(.+) ]]; then
+      local covers_content="${BASH_REMATCH[1]}"
+
+      # 提取 Requirement 名称
+      if [[ "$covers_content" =~ Requirement:[[:space:]]*([^,，]+) ]]; then
+        local task_req="${BASH_REMATCH[1]}"
+        task_req="${task_req%"${task_req##*[![:space:]]}"}"
+        echo "$task_req" >> "$tmp_tasks_reqs"
+      fi
+
+      # 提取 Scenario 名称
+      if [[ "$covers_content" =~ Scenario:[[:space:]]*(.+)$ ]]; then
+        local scenarios_str="${BASH_REMATCH[1]}"
+        scenarios_str="${scenarios_str%"${scenarios_str##*[![:space:]]}"}"
+
+        # 用 、或 , 或 ，分割 Scenario 名称
+        local cleaned="${scenarios_str//、/ }"
+        cleaned="${cleaned//，/,}"
+        cleaned="${cleaned//,/ }"
+        cleaned="${cleaned//\// }"
+
+        for item in $cleaned; do
+          item="${item#"${item%%[![:space:]]*}"}"
+          item="${item%"${item##*[![:space:]]}"}"
+          if [ -n "$item" ]; then
+            echo "$item" >> "$tmp_tasks_scens"
+          fi
+        done
+      fi
+    fi
+  done < "$tasks_file"
+
+  # =========================================
+  # Step 3: 计算差集 — 未被覆盖的 Requirement 和 Scenario
+  # =========================================
+
+  sort -u "$tmp_spec_reqs" -o "$tmp_spec_reqs" 2>/dev/null || true
+  sort -u "$tmp_spec_scens" -o "$tmp_spec_scens" 2>/dev/null || true
+  sort -u "$tmp_tasks_reqs" -o "$tmp_tasks_reqs" 2>/dev/null || true
+  sort -u "$tmp_tasks_scens" -o "$tmp_tasks_scens" 2>/dev/null || true
+
+  local uncovered_req_count=0
+  local uncovered_scen_count=0
+
+  # 查找未被覆盖的 Requirement
+  if [ -s "$tmp_spec_reqs" ]; then
+    while IFS= read -r req; do
+      if ! grep -qxF "$req" "$tmp_tasks_reqs" 2>/dev/null; then
+        semantic_info "A2/A3" "Requirement \"${req}\" 不被任何任务覆盖"
+        uncovered_req_count=$((uncovered_req_count + 1))
+      fi
+    done < "$tmp_spec_reqs"
+  fi
+
+  # 查找未被覆盖的 Scenario
+  if [ -s "$tmp_spec_scens" ]; then
+    while IFS=$'\t' read -r req scen; do
+      if ! grep -qxF "$scen" "$tmp_tasks_scens" 2>/dev/null; then
+        semantic_info "A2/A3" "Scenario \"${scen}\"（Requirement: \"${req}\"）不被任何任务覆盖"
+        uncovered_scen_count=$((uncovered_scen_count + 1))
+      fi
+    done < "$tmp_spec_scens"
+  fi
+
+  # =========================================
+  # Step 4: 全部覆盖时的汇总信息
+  # =========================================
+  if [ "$uncovered_req_count" -eq 0 ] && [ "$uncovered_scen_count" -eq 0 ]; then
+    semantic_info "A2/A3" "所有 Requirement 和 Scenario 均被 Covers 覆盖"
+  fi
+
+  # =========================================
+  # Step 5: 与 spec-review.json 交叉验证（如果存在）
+  # =========================================
+  if [ -z "$review_file" ]; then
+    local spec_dir
+    spec_dir=$(dirname "$spec_file")
+    if [ -f "${spec_dir}/spec-review.json" ]; then
+      review_file="${spec_dir}/spec-review.json"
+    fi
+  fi
+
+  if [ -n "$review_file" ] && [ -f "$review_file" ]; then
+    local review_reqs_covered
+    local review_reqs_total
+    review_reqs_covered=$(jq -r '.coverage.requirements_covered // "N/A"' "$review_file" 2>/dev/null || echo "N/A")
+    review_reqs_total=$(jq -r '.coverage.requirements_total // "N/A"' "$review_file" 2>/dev/null || echo "N/A")
+
+    if [ "$review_reqs_covered" != "N/A" ] && [ "$review_reqs_total" != "N/A" ]; then
+      local spec_total_reqs
+      local spec_covered_reqs
+      spec_total_reqs=$(wc -l < "$tmp_spec_reqs" | tr -d '[:space:]')
+      spec_covered_reqs=$((spec_total_reqs - uncovered_req_count))
+
+      if [ "$spec_covered_reqs" -ne "$review_reqs_covered" ] || [ "$spec_total_reqs" -ne "$review_reqs_total" ]; then
+        semantic_info "A2/A3" "与 spec-review.json 差异: A2 发现 ${spec_total_reqs} 个 Requirement（${spec_covered_reqs} 被覆盖），spec-review.json 报告 ${review_reqs_total} 个（${review_reqs_covered} 被覆盖）"
+      fi
+    fi
+  fi
+}