specline 2.0.0 → 2.0.2

package/templates/.cursor/agents/specline-test-writer.md

@@ -1,170 +0,0 @@
----
-name: specline-test-writer
-description: 黑盒测试工程师——只能基于 Spec 文档编写测试，不能读取任何实现源代码。语言无关，自动检测项目测试框架。确保测试用例完全从需求而非实现角度设计。
----
-
-你是**黑盒测试工程师**。你的工作原则是语言无关的，适配任何技术栈。
-
-## 语言与框架检测（写测试前必须先做）
-
-在编写任何测试代码之前，先检测项目的技术栈和测试框架：
-
-### 1. 读取项目配置文件，确定语言和框架
-
-| 配置文件 | 推断语言 | 测试框架 | 测试目录 |
-|---------|---------|---------|---------|
-| `package.json` 含 jest | TypeScript/JavaScript | **Jest** | `__tests__/`, `*.test.ts` |
-| `package.json` 含 vitest | TypeScript/JavaScript | **Vitest** | `__tests__/`, `*.test.ts` |
-| `package.json` 含 mocha | TypeScript/JavaScript | **Mocha + Chai** | `test/` |
-| `pyproject.toml` / `setup.cfg` | Python | **pytest** | `tests/` |
-| `go.mod` | Go | **go test** | `*_test.go` |
-| `Cargo.toml` | Rust | **cargo test** | `tests/`, `#[cfg(test)]` |
-| `pom.xml` / `build.gradle` | Java/Kotlin | **JUnit 5** | `src/test/` |
-| `Gemfile` | Ruby | **RSpec** | `spec/` |
-| `mix.exs` | Elixir | **ExUnit** | `test/` |
-
-### 2. 确定测试文件路径和命名规范
-
-根据检测到的框架，确定：
-- 测试文件放在哪个目录
-- 测试文件/函数的命名规范
-- 断言库/方法
-
-### 3. 如无法检测到任何测试框架，默认使用最简方案
-
-按语言默认映射：
-- JS/TS → Jest
-- Python → pytest
-- Go → go test
-- Rust → cargo test
-
-写入状态时记录检测结果：`"test_framework": "jest"`
-
-## 核心约束（必须严格遵守）
-
-1. **不能读取实现源代码**：禁止读取任何业务逻辑、组件实现、API handler 等源码文件
-2. **只能基于以下输入**：
-   - Spec 文档（需求规格，获取行为验收标准 WHEN/THEN）
-   - `design.md` 的「对外接口契约」章节（获取 CLI 命令、HTTP 端点、模块导出的技术签名——如果章节不存在则跳过）
-   - `tasks.md`（Covers 追溯链）
-   - 项目的 `package.json`/`pyproject.toml` 等**配置文件**（用于确定框架，不是实现代码）
-3. **只能通过 CLI 执行或 HTTP 调用来验证行为**，不可直接 import 内部模块或组件
-
-## 工作方式
-
-1. 检测项目技术栈，确定测试框架
-2. 仔细阅读 Spec 中的每个 Scenario，理解验收标准（WHEN/THEN）
-3. **读取 `design.md` 的「对外接口契约」章节**，获取 CLI 命令格式、HTTP 端点、模块导出签名
-   - 如果 design.md 无此章节 → 此 change 无黑盒测试任务需求，技能级自检：确认 tasks.md 末尾「测试文件归属」表格中是否确实无 specline-test-writer 负责的测试任务
-4. 对照 `tasks.md` 中的 `Covers` 追溯链，确保每个 Scenario 都有测试覆盖
-5. 每个 Scenario 至少生成 1 个对应的测试函数
-6. 测试函数命名遵循对应框架的约定
-7. 测试函数必须包含描述性注释/名称（对应 Spec 中的 Scenario 名称）
-
-## 合同驱动测试 (Contract-Driven Testing)
-
-当 design.md 包含「对外接口契约」章节时，按以下规则编写测试：
-
-### CLI 命令测试
-
-从契约的 CLI 命令表格获取命令格式和参数：
-```python
-# 契约: | quickfix | `specline quickfix <description>` | description: string | stdout: summary, exit 0/1 |
-def test_quickfix_success():
-    result = subprocess.run(["specline", "quickfix", "修复按钮"], capture_output=True, text=True)
-    assert result.returncode == 0
-    assert "summary" in result.stdout.lower()
-```
-
-### HTTP 端点测试
-
-从契约的 HTTP 端点表格获取路径和方法：
-```python
-# 契约: | POST | /api/users | `{ name: string, email: string }` | 201 + `{ id: string }` | 409 `{ "error": "duplicate" }` |
-def test_create_user_success():
-    resp = requests.post(f"{BASE_URL}/api/users", json={"name": "张三", "email": "test@example.com"})
-    assert resp.status_code == 201
-    assert "id" in resp.json()
-
-def test_create_user_duplicate():
-    # 先创建一个用户
-    requests.post(f"{BASE_URL}/api/users", json={"name": "张三", "email": "dup@example.com"})
-    # 重复创建
-    resp = requests.post(f"{BASE_URL}/api/users", json={"name": "李四", "email": "dup@example.com"})
-    assert resp.status_code == 409
-    assert resp.json()["error"] == "duplicate"
-```
-
-### 模块导出测试
-
-从契约的模块导出表格获取函数签名，但**只通过 CLI/HTTP 间接调用**，不直接 import：
-```python
-# 契约: | src/services/auth.py | createSession | `(userId: string) => Promise<Session>` |
-# ❌ 不能: from src.services.auth import createSession
-# ✅ 改为: 通过 HTTP API 间接测试
-def test_create_session_via_api():
-    resp = requests.post(f"{BASE_URL}/api/sessions", json={"userId": "user-123"})
-    assert resp.status_code == 201
-    assert "sessionToken" in resp.json()
-```
-
-**重要**：模块导出契约主要用于 Code Review 阶段校验实现一致性。test-writer 仍然只通过外部接口（CLI/HTTP）测试行为。
-
-## 测试映射规则（语言无关）
-
-```
-Spec Scenario                         →  Test Function
-────────────────────────────────────    ──────────────────────────────────
-#### Scenario: Successful login        test("Successful login", () => {     (Jest)
-  - **WHEN** user submits valid          // WHEN 条件 → Arrange/Act
-    credentials                          const result = await login(...)
-  - **THEN** system returns JWT token   // THEN 断言 → Assert
-                                         expect(result.token).toBeDefined()
-
-
-#### Scenario: Invalid file             def test_invalid_task_file():         (pytest)
-  - **WHEN** user runs CLI with          # WHEN 条件 → Act
-    invalid task file                    result = run_cli("task run --file bad.json")
-  - **THEN** system exits with code 1   # THEN 断言 → Assert
-                                         assert result.returncode == 1
-
-
-#### Scenario: Data persistence          func TestDataPersistence(t *testing.T) {  (go test)
-  - **WHEN** server restarts             // WHEN 条件 → Act
-  - **THEN** previously stored data       // THEN 断言 → Assert
-    is still accessible
-```
-
-核心原则：**每个 Scenario 的 WHEN 转为准备/执行步骤，THEN 转为断言。**
-
-## 禁止事项
-
-- ❌ 直接 import 或 require 项目内部模块/组件
-- ❌ 读取 `agent/`、`server/`、`src/`、`lib/` 等包含业务逻辑的目录下的源代码文件
-- ❌ 直接调用内部函数、类、或数据库操作方法
-- ❌ 绕过公开接口（CLI/HTTP API）直接访问内部状态
-
-## 允许事项
-
-- ✅ 读取项目配置文件（`package.json`、`pyproject.toml`、`go.mod` 等）
-- ✅ 使用对应语言的 subprocess/shell 调用 CLI 命令
-- ✅ 使用对应语言的 HTTP 客户端调用 API
-- ✅ 创建临时文件和测试 fixture 数据
-- ✅ 读取 Spec、Design、Tasks 等规划文档
-
-## 产出报告
-
-完成后输出 JSON 到 `specline/changes/<change>/.tmp/test-code-result.json`：
-
-```json
-{
-  "status": "completed",
-  "test_framework": "jest",
-  "language": "typescript",
-  "test_dir": "__tests__",
-  "files_created": ["__tests__/login.test.ts", "__tests__/api.test.ts"],
-  "scenarios_covered": 12,
-  "scenarios_total": 14,
-  "uncovered_scenarios": ["Scenario: 边缘情况X", "Scenario: 异常路径Y"]
-}
-```

package/templates/.cursor/hooks/specline-agent-guard.sh

@@ -1,131 +0,0 @@
-#!/usr/bin/env bash
-# specline-agent-guard.sh — subagentStart Hook（增强版）
-# 白名单校验 + 流水线阶段匹配校验
-#
-# Input (stdin JSON):
-#   { "subagent_type": "...", "subagent_id": "...", "task": "...", ... }
-#
-# Output (stdout JSON):
-#   { "permission": "allow" } 或 { "permission": "deny", "user_message": "..." }
-
-set -euo pipefail
-
-input=$(cat)
-subagent_type=$(echo "$input" | jq -r '.subagent_type // empty')
-SESSION_ID=$(echo "$input" | jq -r '.session_id // empty')
-
-# 非 specline agent → 放行（不受 Specline 管控）
-if ! echo "$subagent_type" | grep -qE "^specline-"; then
-  echo '{"permission": "allow"}'
-  exit 0
-fi
-
-# ===== 1. 白名单校验 =====
-ALLOWED_AGENTS="specline-spec-creator|specline-spec-reviewer|specline-frontend-dev|specline-backend-dev|specline-config-dev|specline-code-reviewer|specline-config-reviewer|specline-test-writer|specline-test-runner"
-
-if ! echo "$subagent_type" | grep -qE "^($ALLOWED_AGENTS)$"; then
-  echo "{\"permission\": \"deny\", \"user_message\": \"子Agent类型 '$subagent_type' 不在 Specline 允许列表中。允许的类型: spec-creator, spec-reviewer, frontend-dev, backend-dev, config-dev, code-reviewer, config-reviewer, test-writer, test-runner\"}"
-  exit 0
-fi
-
-# ===== 2. 流水线阶段匹配校验 =====
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
-CHANGES_DIR="$PROJECT_ROOT/specline/changes"
-
-# 通过 session_id 解析绑定的 pipeline
-resolve_pipeline_for_session() {
-  local session_id="$1"
-  local bindings_file="$PROJECT_ROOT/specline/.pipeline-sessions.json"
-
-  if [ ! -f "$bindings_file" ]; then
-    return 1
-  fi
-
-  local change_name
-  change_name=$(jq -r --arg sid "$session_id" '.[$sid].change // empty' "$bindings_file" 2>/dev/null)
-
-  if [ -z "$change_name" ]; then
-    return 1
-  fi
-
-  local state_file="$CHANGES_DIR/$change_name/.pipeline-state.json"
-
-  if [ ! -f "$state_file" ]; then
-    # 脏数据：pipeline 已归档或不存在，清理绑定
-    jq --arg sid "$session_id" 'del(.[$sid])' "$bindings_file" > "${bindings_file}.tmp" && mv "${bindings_file}.tmp" "$bindings_file"
-    return 1
-  fi
-
-  STATE_FILE="$state_file"
-  return 0
-}
-
-STATE_FILE=""
-if ! resolve_pipeline_for_session "$SESSION_ID"; then
-  echo '{"permission": "allow"}'
-  exit 0
-fi
-
-phase=$(jq -r '.current_phase' "$STATE_FILE")
-change=$(jq -r '.change_name' "$STATE_FILE")
-
-# 判断 Agent 类型分类
-is_spec_agent=$(echo "$subagent_type" | grep -qE "specline-spec-creator|specline-spec-reviewer" && echo "true" || echo "false")
-is_coding_agent=$(echo "$subagent_type" | grep -qE "^(specline-frontend-dev|specline-backend-dev|specline-config-dev)$" && echo "true" || echo "false")
-is_review_agent=$(echo "$subagent_type" | grep -qE "^(specline-code-reviewer|specline-config-reviewer)$" && echo "true" || echo "false")
-is_test_agent=$(echo "$subagent_type" | grep -qE "specline-test-writer|specline-test-runner" && echo "true" || echo "false")
-
-case "$phase" in
-  spec)
-    if [ "$is_coding_agent" = "true" ]; then
-      echo "{\"permission\": \"deny\", \"user_message\": \"🚫 SPEC 阶段不能启动编码 Agent: $subagent_type。变更: $change。请先完成 SPEC → CODING 阶段切换。\"}"
-      exit 0
-    fi
-    if [ "$is_test_agent" = "true" ]; then
-      echo "{\"permission\": \"deny\", \"user_message\": \"🚫 SPEC 阶段不能启动测试 Agent: $subagent_type。变更: $change。\"}"
-      exit 0
-    fi
-    if [ "$is_review_agent" = "true" ]; then
-      echo "{\"permission\": \"deny\", \"user_message\": \"🚫 SPEC 阶段不能启动代码审查 Agent: $subagent_type。变更: $change。请使用 specline-spec-reviewer。\"}"
-      exit 0
-    fi
-    # spec-creator, spec-reviewer → 放行
-    ;;
-
-  coding)
-    if [ "$is_spec_agent" = "true" ]; then
-      echo "{\"permission\": \"deny\", \"user_message\": \"🚫 CODING 阶段不能启动 Spec Agent: $subagent_type。变更: $change。如需修改 Spec，请手动编辑文件。\"}"
-      exit 0
-    fi
-    # 编码/测试/审查 agent → 放行
-    ;;
-
-  code_review)
-    if [ "$is_spec_agent" = "true" ]; then
-      echo "{\"permission\": \"deny\", \"user_message\": \"🚫 CODE REVIEW 阶段不能启动 Spec Agent: $subagent_type。变更: $change。\"}"
-      exit 0
-    fi
-    if [ "$is_test_agent" = "true" ] && [ "$subagent_type" != "specline-test-writer" ]; then
-      echo "{\"permission\": \"deny\", \"user_message\": \"🚫 CODE REVIEW 阶段不能启动测试运行 Agent。变更: $change。Test 在下一阶段。\"}"
-      exit 0
-    fi
-    ;;
-
-  test)
-    if [ "$is_spec_agent" = "true" ]; then
-      echo "{\"permission\": \"deny\", \"user_message\": \"🚫 TEST 阶段不能启动 Spec Agent: $subagent_type。变更: $change。\"}"
-      exit 0
-    fi
-    # 编码/测试/审查 agent → 放行（测试阶段可能需要编码修复）
-    ;;
-
-  archive)
-    echo "{\"permission\": \"deny\", \"user_message\": \"🚫 变更 $change 已归档，不能启动任何子 Agent。\"}"
-    exit 0
-    ;;
-esac
-
-# 阶段匹配 + 白名单都通过
-echo '{"permission": "allow"}'
-exit 0

package/templates/.cursor/hooks/specline-auto-format.sh

@@ -1,12 +0,0 @@
-#!/usr/bin/env bash
-# auto-format.sh — afterFileEdit Hook: 自动格式化
-input=$(cat)
-filepath=$(echo "$input" | jq -r '.file // empty')
-if [ -z "$filepath" ]; then exit 0; fi
-if echo "$filepath" | grep -qE "\.py$"; then
-  command -v ruff &>/dev/null && ruff format "$filepath" 2>/dev/null || true
-fi
-if echo "$filepath" | grep -qE "\.(ts|tsx|js)$"; then
-  command -v npx &>/dev/null && npx prettier --write "$filepath" 2>/dev/null || true
-fi
-exit 0

package/templates/.cursor/hooks/specline-phase-guard.sh

@@ -1,201 +0,0 @@
-#!/usr/bin/env bash
-# specline-phase-guard.sh — preToolUse Hook
-# 操作前按流水线阶段校验并拦截违规行为
-#
-# Input (stdin JSON):
-#   { "tool_name": "Write"|"Task"|"Shell"|"Delete"|..., "tool_input": {...}, ... }
-#
-# Output (stdout JSON):
-#   { "permission": "allow" }  或  { "permission": "deny", "user_message": "...", "agent_message": "..." }
-
-set -euo pipefail
-
-input=$(cat)
-SESSION_ID=$(echo "$input" | jq -r '.session_id // empty')
-tool_name=$(echo "$input" | jq -r '.tool_name // empty')
-tool_input=$(echo "$input" | jq -r '.tool_input // "{}"')
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
-CHANGES_DIR="$PROJECT_ROOT/specline/changes"
-
-BINDINGS_FILE="$PROJECT_ROOT/specline/.pipeline-sessions.json"
-[ ! -f "$BINDINGS_FILE" ] && echo '{}' > "$BINDINGS_FILE"
-
-resolve_pipeline_for_session() {
-  local session_id="$1"
-  local change_name
-  change_name=$(jq -r --arg sid "$session_id" '.[$sid].change // empty' "$BINDINGS_FILE" 2>/dev/null)
-  if [ -z "$change_name" ]; then
-    return 1
-  fi
-  local sf="$PROJECT_ROOT/specline/changes/$change_name/.pipeline-state.json"
-  if [ ! -f "$sf" ]; then
-    jq --arg sid "$session_id" 'del(.[$sid])' "$BINDINGS_FILE" > "${BINDINGS_FILE}.tmp" && mv "${BINDINGS_FILE}.tmp" "$BINDINGS_FILE"
-    return 1
-  fi
-  STATE_FILE="$sf"
-  return 0
-}
-
-# ===== 辅助函数 =====
-
-deny() {
-  local user_msg="$1"
-  local agent_msg="$2"
-  # JSON 转义
-  user_msg=$(echo "$user_msg" | jq -Rs '.')
-  agent_msg=$(echo "$agent_msg" | jq -Rs '.')
-  cat << EOF
-{
-  "permission": "deny",
-  "user_message": ${user_msg},
-  "agent_message": ${agent_msg}
-}
-EOF
-}
-
-allow() {
-  echo '{"permission": "allow"}'
-}
-
-# ===== 主逻辑 =====
-
-STATE_FILE=""
-if ! resolve_pipeline_for_session "$SESSION_ID"; then
-  allow   # 无绑定 → 透明放行
-  exit 0
-fi
-
-phase=$(jq -r '.current_phase' "$STATE_FILE")
-change=$(jq -r '.change_name' "$STATE_FILE")
-tasks_file="$CHANGES_DIR/$change/tasks.md"
-
-# ---- Write / StrReplace / EditNotebook ----
-case "$tool_name" in
-  Write|StrReplace|EditNotebook)
-    # SPEC 阶段：禁止编辑非 specline 的源代码文件
-    if [ "$phase" = "spec" ]; then
-      file_path=$(echo "$tool_input" | jq -r '.path // .file_path // empty')
-
-      if [ -n "$file_path" ]; then
-        # 允许 specline 规划文件
-        if echo "$file_path" | grep -q "specline/"; then
-          allow
-          exit 0
-        fi
-
-        # 允许 hook/config 文件（流水线基础设施）
-        if echo "$file_path" | grep -qE "(\.cursor/|hooks\.json|package\.json)"; then
-          allow
-          exit 0
-        fi
-
-        # 代码文件 → 拦截
-        if echo "$file_path" | grep -qE '\.(ts|tsx|js|jsx|py|go|rs|java|rb|php|css|html|vue|svelte)$'; then
-          deny \
-            "🚫 SPEC 阶段不能编辑代码文件: $(basename "$file_path")" \
-            "当前处于 SPEC 阶段（变更：$change）。不能直接编辑应用代码文件。只有在进入 CODING 阶段后才能修改代码。如需修改规划文件，只能编辑 specline/changes/ 下的内容。"
-          exit 0
-        fi
-      fi
-    fi
-
-    # ARCHIVE 阶段：禁止任何编辑
-    if [ "$phase" = "archive" ]; then
-      deny \
-        "🚫 变更 $change 已归档，不能修改文件" \
-        "变更 $change 已归档。不能修改任何文件。如需继续工作，请创建新的变更。"
-      exit 0
-    fi
-
-    # CODING/CODE_REVIEW/TEST 阶段：放行
-    # (子 Agent 需要编辑代码文件，Orchestrator 的行为靠 SKILL + sessionStart 上下文约束)
-    allow
-    ;;
-
-  # ---- Task (子Agent) ----
-  Task)
-    subagent_type=$(echo "$tool_input" | jq -r '.subagent_type // empty')
-
-    # 不是 specline agent → 放行
-    if ! echo "$subagent_type" | grep -qE "^specline-"; then
-      allow
-      exit 0
-    fi
-
-    is_coding_agent=$(echo "$subagent_type" | grep -qE "^(specline-frontend-dev|specline-backend-dev|specline-config-dev)$" && echo "true" || echo "false")
-    is_spec_agent=$(echo "$subagent_type" | grep -qE "^(specline-spec-creator|specline-spec-reviewer)$" && echo "true" || echo "false")
-    is_test_agent=$(echo "$subagent_type" | grep -qE "^(specline-test-writer|specline-test-runner)$" && echo "true" || echo "false")
-    is_review_agent=$(echo "$subagent_type" | grep -qE "^(specline-code-reviewer|specline-config-reviewer)$" && echo "true" || echo "false")
-
-    case "$phase" in
-      spec)
-        if [ "$is_coding_agent" = "true" ]; then
-          deny \
-            "🚫 SPEC 阶段不能启动编码 Agent ($subagent_type)" \
-            "当前在 SPEC 阶段（变更：$change）。编码 Agent（$subagent_type）只能在 CODING 阶段启动。如需编码，请先完成 Spec Gate 和人工确认。"
-          exit 0
-        fi
-        if [ "$is_test_agent" = "true" ]; then
-          deny \
-            "🚫 SPEC 阶段不能启动测试 Agent ($subagent_type)" \
-            "当前在 SPEC 阶段（变更：$change）。测试 Agent 只能在 CODING 或 TEST 阶段启动。"
-          exit 0
-        fi
-        # spec-creator / spec-reviewer → 放行
-        ;;
-
-      coding)
-        if [ "$is_spec_agent" = "true" ]; then
-          deny \
-            "🚫 CODING 阶段不能启动 Spec Agent ($subagent_type)" \
-            "当前在 CODING 阶段（变更：$change）。Spec Agent 只能在 SPEC 阶段启动。如需修改 Spec 文档，请手动编辑 specline/changes/ 下的文件后恢复流水线。"
-          exit 0
-        fi
-        # 编码/测试/审查 agent → 放行
-        ;;
-
-      code_review)
-        if [ "$is_spec_agent" = "true" ]; then
-          deny \
-            "🚫 CODE REVIEW 阶段不能启动 Spec Agent ($subagent_type)" \
-            "当前在 CODE REVIEW 阶段（变更：$change）。Spec Agent 只能在 SPEC 阶段启动。"
-          exit 0
-        fi
-        ;;
-
-      test)
-        if [ "$is_spec_agent" = "true" ]; then
-          deny \
-            "🚫 TEST 阶段不能启动 Spec Agent ($subagent_type)" \
-            "当前在 TEST 阶段（变更：$change）。Spec Agent 只能在 SPEC 阶段启动。"
-          exit 0
-        fi
-        ;;
-    esac
-
-    allow
-    ;;
-
-  # ---- Delete ----
-  Delete)
-    # SPEC 阶段禁止删除代码文件
-    if [ "$phase" = "spec" ]; then
-      file_path=$(echo "$tool_input" | jq -r '.path // empty')
-      if [ -n "$file_path" ] && ! echo "$file_path" | grep -q "specline/"; then
-        deny \
-          "🚫 SPEC 阶段不能删除代码文件" \
-          "当前在 SPEC 阶段，不能删除应用代码文件。"
-        exit 0
-      fi
-    fi
-    allow
-    ;;
-
-  *)
-    allow
-    ;;
-esac
-
-exit 0

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

@@ -1,125 +0,0 @@
-#!/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"
-}