specline 1.4.0 → 2.0.1

package/core/gates/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/core/gates/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
+}

package/core/gates/pipeline-gate-checks/c1-exception.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+#
+# c1-exception.sh — C1: 异常场景覆盖率检测
+#
+# 检查 spec.md 中每个 Requirement 是否至少包含一个异常/错误场景。
+# 使用 SPEC_FILE 环境变量定位 spec 文件（由 gate_semantic 设置）。
+#
+# 异常关键词（不区分大小写）：
+#   错误|失败|异常|超时|无效|不存在|未找到|拒绝|过期|冲突|超出|不允许|未授权|已存在
+#
+# Usage（由 gate_semantic source 后调用）:
+#   run_c1_exception
+
+run_c1_exception() {
+  # 检查 spec 文件是否存在
+  if [ ! -f "$SPEC_FILE" ]; then
+    return 0
+  fi
+
+  # 检查是否有 Requirement 区块
+  local req_count
+  req_count=$(grep -c '^### Requirement:' "$SPEC_FILE" 2>/dev/null || true)
+  req_count="${req_count:-0}"
+  if [ "$req_count" = "0" ]; then
+    semantic_warn "C1" "未找到任何 Requirement 区块，跳过异常场景覆盖率检查"
+    return 0
+  fi
+
+  # 异常关键词（不区分大小写，用 grep -iE 扩展正则）
+  local keywords="错误|失败|异常|超时|无效|不存在|未找到|拒绝|过期|冲突|超出|不允许|未授权|已存在"
+
+  # 用 awk 按 Requirement 分组 Scenario 标题
+  # 输出格式: 需求名称|场景标题1|场景标题2|...
+  # 将 awk 输出捕获到变量，再用 here-string 逐行处理，避免管道 subshell 导致计数器丢失
+  local grouped
+  grouped=$(awk '
+    /^### Requirement:/ {
+      if (current_req != "") print current_req "|" scenarios
+      current_req = $0
+      sub(/^### Requirement: /, "", current_req)
+      scenarios = ""
+    }
+    /^#### Scenario:/ {
+      s = $0
+      sub(/^#### Scenario: /, "", s)
+      if (scenarios != "") scenarios = scenarios "|"
+      scenarios = scenarios s
+    }
+    END {
+      if (current_req != "") print current_req "|" scenarios
+    }
+  ' "$SPEC_FILE")
+
+  # 逐行处理每个 Requirement
+  while IFS='|' read -r req_name scenarios_str; do
+    [ -z "$req_name" ] && continue
+
+    # 统计该 Requirement 的 Scenario 数量
+    local scenario_count
+    if [ -z "$scenarios_str" ]; then
+      scenario_count=0
+    else
+      scenario_count=$(echo "$scenarios_str" | awk -F'|' '{print NF}')
+    fi
+
+    # 检查 Scenario 标题集合中是否包含异常关键词
+    if ! echo "$scenarios_str" | grep -qiE "$keywords" 2>/dev/null; then
+      semantic_warn "C1" "Requirement \"${req_name}\" 缺少异常场景（${scenario_count} 个 Scenario 中无异常/错误场景关键词）"
+    fi
+  done <<< "$grouped"
+}

package/core/gates/pipeline-gate-checks/c2-vague.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+#
+# c2-vague.sh — C2 检查：模糊需求检测
+#
+# 扫描 spec.md 中不可量化的模糊表述（如"足够快""适当"等），
+# 跳过代码块（```）内内容，对匹配到的模糊词输出 WARNING。
+#
+# 依赖：common.sh（提供 semantic_warn 函数和 SEMANTIC_WARNINGS 计数器）
+# 环境变量：SPEC_FILE — 指向 spec.md 的路径
+
+# 加载共享工具函数（允许独立测试时直接 source）
+if [ -z "${SEMANTIC_WARNINGS:-}" ]; then
+  COMMON_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  if [ -f "$COMMON_DIR/common.sh" ]; then
+    source "$COMMON_DIR/common.sh"
+  fi
+fi
+
+run_c2_vague() {
+  if [ -z "${SPEC_FILE:-}" ] || [ ! -f "$SPEC_FILE" ]; then
+    echo "⚠️ [WARNING] (C2) SPEC_FILE 未设置或文件不存在，跳过模糊需求检测" >&2
+    return 0
+  fi
+
+  # 模糊词正则模式
+  #   性能良好|足够快|适当[的地]|合理[的地]|必要时|等等|较好[的地]|
+  #   尽量|较大规模|可能[的地]|若干|一定[的地]|一般[的地]|基本的|少量的
+  local VAGUE_PATTERN='性能良好|足够快|适当[的地]|合理[的地]|必要时|等等|较好[的地]|尽量|较大规模|可能[的地]|若干|一定[的地]|一般[的地]|基本的|少量的'
+
+  local in_codeblock=0
+  local line_num=0
+
+  while IFS= read -r line; do
+    line_num=$((line_num + 1))
+
+    # 检测代码块边界：以 ``` 开头（忽略后面的语言标记）
+    if [[ "$line" =~ ^\`\`\` ]]; then
+      if [ "$in_codeblock" -eq 0 ]; then
+        in_codeblock=1
+      else
+        in_codeblock=0
+      fi
+      continue
+    fi
+
+    # 跳过代码块内部的行
+    if [ "$in_codeblock" -eq 1 ]; then
+      continue
+    fi
+
+    # 对普通文本行执行模糊词匹配
+    if echo "$line" | grep -qE "$VAGUE_PATTERN" 2>/dev/null; then
+      # 提取上下文（去除首尾空白）
+      local context
+      context=$(echo "$line" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+
+      semantic_warn "C2" "模糊需求表述: 第 ${line_num} 行 \"${context}\""
+    fi
+  done < "$SPEC_FILE"
+}

package/core/gates/pipeline-gate-checks/common.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+#
+# common.sh — Specline Pipeline Gate 语义检查共享工具
+#
+# 提供:
+#   - 全局计数器: SEMANTIC_ERRORS, SEMANTIC_WARNINGS, SEMANTIC_INFOS
+#   - 严重度报告函数: semantic_error(), semantic_warn(), semantic_info()
+#   - 文件定位函数: find_spec_file(), find_tasks_file()
+#
+# 兼容性: bash 3.2+ (macOS 默认 bash)
+
+set -euo pipefail
+
+# ===== 全局计数器 =====
+SEMANTIC_ERRORS=${SEMANTIC_ERRORS:-0}
+SEMANTIC_WARNINGS=${SEMANTIC_WARNINGS:-0}
+SEMANTIC_INFOS=${SEMANTIC_INFOS:-0}
+
+# ===== 严重度报告函数 =====
+
+# semantic_error <code> <message>
+# 输出 ERROR 级别消息到 stderr，并增加 SEMANTIC_ERRORS 计数
+semantic_error() {
+  local code="$1"
+  local msg="$2"
+  echo "❌ [ERROR] (${code}) ${msg}" >&2
+  SEMANTIC_ERRORS=$((SEMANTIC_ERRORS + 1))
+}
+
+# semantic_warn <code> <message>
+# 输出 WARNING 级别消息到 stdout，并增加 SEMANTIC_WARNINGS 计数
+semantic_warn() {
+  local code="$1"
+  local msg="$2"
+  echo "⚠️ [WARNING] (${code}) ${msg}"
+  SEMANTIC_WARNINGS=$((SEMANTIC_WARNINGS + 1))
+}
+
+# semantic_info <code> <message>
+# 输出 INFO 级别消息到 stdout，并增加 SEMANTIC_INFOS 计数
+semantic_info() {
+  local code="$1"
+  local msg="$2"
+  echo "ℹ️ [INFO] (${code}) ${msg}"
+  SEMANTIC_INFOS=$((SEMANTIC_INFOS + 1))
+}
+
+# ===== 文件定位函数 =====
+
+# find_spec_file
+# 在 specline/changes/$CHANGE/specs/ 下查找 spec.md
+find_spec_file() {
+  if [ -z "${CHANGE:-}" ]; then
+    echo ""
+    return
+  fi
+  find "${PROJECT_ROOT:-.}/specline/changes/${CHANGE}/specs" -name "spec.md" 2>/dev/null | head -1
+}
+
+# find_tasks_file
+# 返回 tasks.md 路径
+find_tasks_file() {
+  if [ -z "${CHANGE:-}" ]; then
+    echo ""
+    return
+  fi
+  echo "${PROJECT_ROOT:-.}/specline/changes/${CHANGE}/tasks.md"
+}

package/core/gates/pipeline-gate-checks/d1-cycle.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+#
+# d1-cycle.sh — D1: 依赖环路检测
+#
+# 使用 awk 实现三色 DFS 检测 tasks.md 中任务依赖关系是否形成环路。
+# 核心逻辑在 awk 中执行，避免 bash 版本兼容性问题（macOS bash 3.2）。
+#
+# 用法：
+#   export TASKS_FILE=/path/to/tasks.md
+#   source d1-cycle.sh && run_d1_cycle
+#
+# 环境变量：
+#   TASKS_FILE — tasks.md 文件路径
+
+# 确保计数器变量已定义（兼容独立 source 运行场景）
+: "${SEMANTIC_ERRORS:=0}"
+: "${SEMANTIC_WARNINGS:=0}"
+: "${SEMANTIC_INFOS:=0}"
+
+run_d1_cycle() {
+  local tasks_file="${TASKS_FILE:-}"
+
+  if [ -z "$tasks_file" ] || [ ! -f "$tasks_file" ]; then
+    echo "⚠️ D1: TASKS_FILE 未设置或文件不存在，跳过依赖环路检测" >&2
+    return 0
+  fi
+
+  # ──────────────────────────────────────────────
+  # 使用 awk 完成全部检测逻辑：
+  #   1. 解析 Depends 行构建邻接表
+  #   2. 三色 DFS 环路检测
+  #   3. 输出 "SELF:task_id" 或 "CYCLE:path" 行
+  # ──────────────────────────────────────────────
+  local result
+  result=$(awk '
+    # 解析任务编号
+    /^## / {
+      task = $2
+      gsub(/\..*/, "", task)
+    }
+    # 解析 Depends 行
+    /\*\*Depends\*\*:/ {
+      deps = $0
+      sub(/.*\*\*Depends\*\*:[ \t]*/, "", deps)
+      gsub(/^[ \t]+|[ \t]+$/, "", deps)
+      if (deps ~ /\(none\)/) {
+        deps = ""
+      }
+      # 清理依赖列表：去空格，过滤非数字字符（防止意外格式变化）
+      gsub(/[ \t]/, "", deps)
+      gsub(/[^0-9,]/, "", deps)
+      gsub(/,/, " ", deps)
+      # 去掉多余的连续空格
+      gsub(/  +/, " ", deps)
+      gsub(/^ | $/, "", deps)
+      adj[task] = deps
+    }
+    END {
+      if (length(adj) == 0) exit 0
+
+      # 收集所有任务 ID
+      for (t in adj) {
+        all_tasks[t] = 1
+      }
+
+      errors = 0
+
+      # 对每个任务执行 DFS（使用参数传递路径，自动处理回溯）
+      for (t in all_tasks) {
+        if (!(t in color) || color[t] == 0) {
+          dfs(t, "")
+        }
+      }
+    }
+
+    function dfs(node, path,   neighbors_str, n, i, arr, cnt, new_path, path_idx) {
+      color[node] = 1
+      new_path = path (path == "" ? "" : " ") node
+
+      neighbors_str = adj[node]
+
+      cnt = split(neighbors_str, arr, " ")
+      for (i = 1; i <= cnt; i++) {
+        n = arr[i]
+        if (n == "") continue
+
+        # 自引用
+        if (n == node) {
+          print "SELF:" node
+          errors++
+          continue
+        }
+
+        # 检查颜色
+        if (n in color && color[n] == 1) {
+          # 发现环路：从 new_path 中提取从 n 开始的路径
+          path_idx = index(" " new_path " ", " " n " ")
+          if (path_idx > 0) {
+            cycle_seg = substr(new_path, path_idx)
+          } else {
+            cycle_seg = new_path
+          }
+          gsub(/ /, " → ", cycle_seg)
+          print "CYCLE:" cycle_seg " → " n
+          errors++
+        } else if (!(n in color) || color[n] == 0) {
+          dfs(n, new_path)
+        }
+      }
+
+      color[node] = 2
+    }
+  ' "$tasks_file" 2>&1)
+
+  # ──────────────────────────────────────────────
+  # 处理 awk 输出，调用 semantic_error
+  # ──────────────────────────────────────────────
+  if [ -z "$result" ]; then
+    echo "✅ D1 依赖环路检测通过（无环路）"
+    return 0
+  fi
+
+  local line
+  while IFS= read -r line; do
+    [ -z "$line" ] && continue
+    case "$line" in
+      SELF:*)
+        local self_task="${line#SELF:}"
+        if type -t semantic_error &>/dev/null; then
+          semantic_error "D1" "依赖环路检测: 任务 ${self_task} 自引用"
+        else
+          echo "❌ [ERROR] (D1) 依赖环路检测: 任务 ${self_task} 自引用" >&2
+          ((SEMANTIC_ERRORS++))
+        fi
+        ;;
+      CYCLE:*)
+        local cycle_path="${line#CYCLE:}"
+        if type -t semantic_error &>/dev/null; then
+          semantic_error "D1" "依赖环路检测: 发现环路 ${cycle_path}"
+        else
+          echo "❌ [ERROR] (D1) 依赖环路检测: 发现环路 ${cycle_path}" >&2
+          ((SEMANTIC_ERRORS++))
+        fi
+        ;;
+    esac
+  done <<< "$result"
+
+  return 0
+}