specline 1.2.2 → 1.3.1

package/README.md

@@ -43,7 +43,7 @@
 - **确定性门禁**：每个阶段用 Shell 脚本的退出码判定是否通过，不做模糊判断
 - **黑盒测试**：测试 Agent 只看 Spec 文档，不能读取任何实现源码
 - **断点续跑**：随时中断，下次从最后一个可信门禁自动恢复（tasks.md 的 `[x]`/`[ ]` 标记进度）
-- **人机协作**：3 个人工检查点——Spec 确认、Review 可选复核、归档确认
+- **人机协作**：3 个人工检查点——Spec 确认、Review 可选复核、归档确认，支持 `full`/`minimal`/`none` 三级自动化策略配置（`specline/config.yaml` 中 `pipeline.human_gate_policy`）
 - **Hook 约束体系**：sessionStart 注入 pipeline 上下文 → preToolUse 违规拦截 → postToolUse 操作后提醒，确保长对话中 Agent 不偏离流水线逻辑
 - **安全 Hook**：自动拦截危险 Shell 命令（如 `rm -rf`、`curl|bash`）+ 代码变更后自动格式化
 - **零外部依赖**：不依赖 OpenSpec CLI，全部功能自包含
@@ -77,10 +77,14 @@ my-project/
 │   ├── agents/          ← 9 个 Specline Agent 定义
 │   ├── commands/        ← 3 个 Slash 命令入口
 │   ├── skills/          ← 6 个 Skill 指令
+│   │   └── specline-pipeline/
+│   │       ├── SKILL.md         ← 核心编排指令（~500 行）
+│   │       ├── templates/       ← 子 Agent prompt 模板
+│   │       └── references/      ← Schema / 事件日志 / 约束参考文档
 │   ├── hooks/           ← 7 个 Gate/Hook 脚本
 │   └── hooks.json       ← Cursor Hook 配置
 ├── specline/            ← 运行时目录
-│   ├── config.yaml
+│   ├── config.yaml      ← 项目配置（含 pipeline 人机门禁策略）
 │   ├── changes/         ← 变更目录
 │   │   └── archive/     ← 归档目录
 │   └── specs/           ← 主规格目录
@@ -132,8 +136,8 @@ PHASE 1: SPEC（规格）
     ├── design.md      — 技术设计（架构/数据流/决策）
     └── tasks.md       — 任务清单（Type/Depends/Covers/Testable/Files + [ ] 进度标记）
   → specline-spec-reviewer 审核
-  → Gate: grep + jq 格式校验
-  → 🟡 人工确认 Spec 和任务规划
+  → Gate: grep + jq 格式校验 + semantic 语义检查（Covers 引用悬空 / 依赖环路 / 异常场景缺失 / 模糊需求检测）
+  → 🟡 人工确认 Spec 和任务规划（策略可配：`full` 需确认 / `minimal` `none` 自动通过）
 
 PHASE 2: CODING（编码）
   解析 tasks.md → 按依赖 DAG 分层 → 同批次前后端/config Agent 并发
@@ -152,7 +156,7 @@ PHASE 4: TEST（测试）
   → 自动重试最多 2 次
 
 PHASE 5: ARCHIVE（归档）
-  → 🟡 人工确认归档
+  → 🟡 人工确认归档（策略可配：`full` `minimal` 需确认 / `none` 自动归档）
   → delta specs 合并到主规格目录
   → 按日期归档到 specline/changes/archive/
   ✅ 完成
@@ -205,6 +209,10 @@ PHASE 5: ARCHIVE（归档）
     ▼                                                  ▼
 specline-pipeline SKILL  ← 编排层                 编排者直接执行（无子 Agent）
     │                                               Read → Write → ReadLints → Shell → 归档
+    ├── SKILL.md           核心编排指令（~500 行）
+    ├── templates/         subagent-prompts.md（3 套 prompt 模板）
+    └── references/        Schema / 事件日志 / 约束参考文档
+    │
 ┌───┼──────────────────┬──────────────────────┐
 ▼   ▼                  ▼                      ▼
 9 个子 Agent      specline-pipeline-     Cursor Hooks
@@ -218,7 +226,7 @@ specline-pipeline SKILL  ← 编排层                 编排者直接执行（
 |------|------|
 | `specline init [path]` | 在指定路径（默认当前目录）初始化 Specline 项目，复制模板文件并生成锁文件 |
 | `specline update` | 检查 CLI 是否有新版本可用（npm registry），输出更新提示 |
-| `specline sync [--dry-run] [path]` | 将上游最新模板文件同步到项目，基于 Lock File 智能识别安全更新/冲突/仅本地修改。`--dry-run` 预览变更不实际写入 |
+| `specline sync [--dry-run] [path]` | 将上游最新模板文件同步到项目，基于 Lock File 智能识别安全更新/冲突/仅本地修改。hooks.json 语义合并（保留用户自定义 hook）、config.yaml 注释级更新（保留用户配置值）、CONFLICT 覆盖前自动创建 `.orig` 备份。`--dry-run` 预览变更不实际写入 |
 | `specline --version` | 显示当前 CLI 版本号 |
 | `specline --help` | 显示帮助信息 |
 
@@ -242,7 +250,7 @@ specline-pipeline SKILL  ← 编排层                 编排者直接执行（
 
 | 门禁 | 检查内容 |
 |------|---------|
-| Spec | `grep` 检查 Purpose/Requirements/Scenarios 章节完整性、WHEN/THEN 配对、Testable 字段格式与一致性 |
+| Spec | 结构性检查（`grep` 检查章节完整性、WHEN/THEN 配对、字段格式）+ 语义检查（`semantic` 子命令：Covers 引用悬空、依赖环路、异常场景缺失、模糊需求、反向覆盖、Type-文件一致性，分 ERROR/WARNING/INFO 三级严重度） |
 | Build | `tsc --noEmit` / `python -m compileall` 编译检查 + Testable 任务单元测试文件存在性与语法检查 |
 | Lint | `ruff` / `eslint` 退出码 + code-review.json 中 error 数量 |
 | Test | 测试框架退出码 + 覆盖率阈值 |

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';
@@ -88,11 +88,13 @@ function writeLockFile(projectDir, lockData) {
 }
 
 /**
- * 遍历 TEMPLATES_DIR 所有文件，构建锁数据结构
+ * 遍历指定目录所有文件，构建锁数据结构
+ * rootDir: 要遍历的根目录（必须是目标项目目录，这样 init 后锁哈希与实际文件一致）
  * 返回 { version, synced_at, files: Map<string, string> }
  */
-function buildLockData(projectDir) {
+function buildLockData(projectDir, rootDir) {
   const files = new Map();
+  const walkRoot = rootDir || TEMPLATES_DIR;
 
   function walk(dir, base) {
     const entries = readdirSync(dir, { withFileTypes: true });
@@ -107,7 +109,7 @@ function buildLockData(projectDir) {
     }
   }
 
-  walk(TEMPLATES_DIR, '');
+  walk(walkRoot, '');
 
   return {
     version: VERSION,
@@ -193,6 +195,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 || '.');
@@ -280,7 +425,7 @@ initialized_at: "${new Date().toISOString()}"
   if (existsSync(lockPath) && !forceMode) {
     warn('锁文件已存在，跳过');
   } else {
-    const lockData = buildLockData(target);
+    const lockData = buildLockData(target, target);
     writeLockFile(target, lockData);
     success('已生成锁文件');
   }
@@ -378,20 +523,14 @@ function cmd_sync({ dryRun, targetPath }) {
   const lockData = readLockFile(target);
 
   // 4. 版本校验
-  if (lockData) {
-    if (lockData.version === VERSION) {
-      success('项目模板已与 CLI 版本同步 (v' + VERSION + ')');
-      process.exit(0);
-    }
-    if (compareVersions(lockData.version, VERSION) > 0) {
-      warn('锁文件版本 (v' + lockData.version + ') 高于 CLI 版本 (v' + VERSION + ')，继续同步可能导致问题');
-      if (!process.stdin.isTTY) {
-        error('非交互式环境，已跳过同步');
-        process.exit(1);
-      }
-      error('锁文件版本高于 CLI，请先更新 CLI');
+  if (lockData && compareVersions(lockData.version, VERSION) > 0) {
+    warn('锁文件版本 (v' + lockData.version + ') 高于 CLI 版本 (v' + VERSION + ')，继续同步可能导致问题');
+    if (!process.stdin.isTTY) {
+      error('非交互式环境，已跳过同步');
       process.exit(1);
     }
+    error('锁文件版本高于 CLI，请先更新 CLI');
+    process.exit(1);
   }
 
   // 5. 收集所有需要分类的路径
@@ -406,6 +545,10 @@ function cmd_sync({ dryRun, targetPath }) {
   // 6. 分类
   const results = [];
   for (const path of allPaths) {
+    if (path === '.specline-config.yaml') {
+      // 项目标识文件，由 specline init 生成（含时间戳），sync 不覆盖
+      continue;
+    }
     const templateHash = upstreamFiles.get(path) || null;
     const lockEntry = lockData ? (lockData.files.get(path) || null) : null;
     const projectPath = join(target, path);
@@ -430,12 +573,56 @@ 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) {
+    if (stats.newCount === 0 && stats.updated === 0 && stats.conflicted === 0
+        && stats.skippedModified === 0 && stats.upstreamRemoved === 0) {
       log('所有模板文件已是最新，无需同步');
     } else {
       log('\n以上为预览，未实际执行。去掉 --dry-run 以执行同步。');
@@ -445,6 +632,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 +650,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 +658,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;
+      }
 
-      if (r.type === 'CONFLICT') {
-        warn('已覆盖（冲突）: ' + r.path);
-      } else if (r.type === 'NO_LOCK_CONFLICT') {
-        warn('已覆盖（无锁文件记录）: ' + r.path);
+      // 特殊文件：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;
+      }
+
+      // 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,8 +719,10 @@ function cmd_sync({ dryRun, targetPath }) {
   });
 
   // 11. 输出摘要
-  if (stats.newCount === 0 && stats.updated === 0 && stats.conflicted === 0 && stats.upstreamRemoved === 0) {
-    log('所有模板文件已是最新，无需同步');
+  if (stats.newCount === 0 && stats.updated === 0 && stats.conflicted === 0
+      && stats.skippedModified === 0 && stats.upstreamRemoved === 0
+      && !mergeStats.hooksMerged && !mergeStats.configUpdated) {
+    success('项目模板已是最新，无需同步 (v' + VERSION + ')');
   } else {
     log('📊 同步摘要：');
     log('   总模板文件: ' + allPaths.size);
@@ -503,6 +731,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.1",
   "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"
+}