spectra-cli 4.1.1 → 4.3.0

package/plugins/spec-driver/scripts/lib/config-schema.mjs

@@ -11,101 +11,156 @@
  *   - resolveEffectiveConfig() effective config 合并
  */
 
-import { z } from 'zod';
+import { loadZod } from './load-zod.mjs';
 
-// ────────────────────────────────────────
-// 子 Schema
-// ────────────────────────────────────────
-
-const modelNameSchema = z.enum(['opus', 'sonnet', 'haiku'])
-  .or(z.string().min(1));
-
-const agentOverrideSchema = z.object({
-  model: modelNameSchema.optional(),
-}).strict();
-
-const agentsSchema = z.record(
-  z.string(),
-  agentOverrideSchema,
-).optional();
-
-const aliasMapSchema = z.record(z.string(), z.string());
-
-const modelCompatSchema = z.object({
-  runtime: z.enum(['auto', 'claude', 'codex']).default('auto'),
-  aliases: z.object({
-    codex: aliasMapSchema.optional(),
-    claude: aliasMapSchema.optional(),
-  }).optional(),
-  defaults: z.object({
-    codex: z.string().optional(),
-    claude: z.string().optional(),
-  }).optional(),
-}).optional();
-
-const codexSchema = z.object({
-  service_tier: z.enum(['fast', 'standard', 'flex']).default('fast'),
-}).optional();
-
-const codexThinkingSchema = z.object({
-  default_level: z.enum(['low', 'medium', 'high', 'xhigh']).default('xhigh'),
-  level_map: z.record(z.string(), z.enum(['low', 'medium', 'high', 'xhigh'])).optional(),
-}).optional();
-
-const researchSchema = z.object({
-  default_mode: z.enum([
-    'auto', 'full', 'tech-only', 'product-only',
-    'codebase-scan', 'skip', 'custom',
-  ]).default('auto'),
-  custom_steps: z.array(z.string()).default([]),
-}).optional();
-
-const verificationSchema = z.object({
-  commands: z.record(z.string(), z.record(z.string(), z.string())).default({}),
-  monorepo: z.object({
-    enabled: z.boolean().default(true),
-  }).optional(),
-  timeout: z.number().int().positive().optional().default(300),
-}).optional();
-
-const gatePauseSchema = z.object({
-  pause: z.enum(['always', 'auto', 'on_failure']),
-});
-
-const gatesSchema = z.record(z.string(), gatePauseSchema).optional();
-
-const qualityGatesSchema = z.object({
-  auto_continue_on_warning: z.boolean().default(true),
-  pause_on_critical: z.boolean().default(true),
-}).optional();
-
-const retrySchema = z.object({
-  max_attempts: z.number().int().min(0).max(10).default(2),
-}).optional();
-
-const progressSchema = z.object({
-  show_stage_progress: z.boolean().default(true),
-  show_stage_summary: z.boolean().default(true),
-}).optional();
+// 经共享 helper 同步加载 zod；缺失时 zodAvailable=false，模块加载不崩
+const { z, available: zodAvailable } = loadZod();
 
 // ────────────────────────────────────────
-// 顶层 Schema
+// 子 Schema + 顶层 Schema
 // ────────────────────────────────────────
+//
+// 全部 schema 求值必须包进 zodAvailable 守卫：缺 zod 时模块体完全不触碰 z，
+// 否则会从 MODULE_NOT_FOUND 退化为 ReferenceError —— 等于没修。
+// ESM 语法限制 export const 不能进 if 块，故 specDriverConfigSchema 用 let + 末尾 export。
+
+let specDriverConfigSchema = null;
+
+if (zodAvailable) {
+  const modelNameSchema = z.enum(['opus', 'sonnet', 'haiku'])
+    .or(z.string().min(1));
+
+  const agentOverrideSchema = z.object({
+    model: modelNameSchema.optional(),
+  }).strict();
+
+  const agentsSchema = z.record(
+    z.string(),
+    agentOverrideSchema,
+  ).optional();
+
+  const aliasMapSchema = z.record(z.string(), z.string());
+
+  const modelCompatSchema = z.object({
+    runtime: z.enum(['auto', 'claude', 'codex']).default('auto'),
+    aliases: z.object({
+      codex: aliasMapSchema.optional(),
+      claude: aliasMapSchema.optional(),
+    }).optional(),
+    defaults: z.object({
+      codex: z.string().optional(),
+      claude: z.string().optional(),
+    }).optional(),
+  }).optional();
+
+  const codexSchema = z.object({
+    service_tier: z.enum(['fast', 'standard', 'flex']).default('fast'),
+  }).optional();
+
+  const codexThinkingSchema = z.object({
+    default_level: z.enum(['low', 'medium', 'high', 'xhigh']).default('xhigh'),
+    level_map: z.record(z.string(), z.enum(['low', 'medium', 'high', 'xhigh'])).optional(),
+  }).optional();
+
+  const researchSchema = z.object({
+    default_mode: z.enum([
+      'auto', 'full', 'tech-only', 'product-only',
+      'codebase-scan', 'skip', 'custom',
+    ]).default('auto'),
+    custom_steps: z.array(z.string()).default([]),
+  }).optional();
+
+  const verificationSchema = z.object({
+    commands: z.record(z.string(), z.record(z.string(), z.string())).default({}),
+    monorepo: z.object({
+      enabled: z.boolean().default(true),
+    }).optional(),
+    timeout: z.number().int().positive().optional().default(300),
+  }).optional();
+
+  const gatePauseSchema = z.object({
+    pause: z.enum(['always', 'auto', 'on_failure']),
+  });
+
+  const gatesSchema = z.record(z.string(), gatePauseSchema).optional();
+
+  const qualityGatesSchema = z.object({
+    auto_continue_on_warning: z.boolean().default(true),
+    pause_on_critical: z.boolean().default(true),
+  }).optional();
+
+  const retrySchema = z.object({
+    max_attempts: z.number().int().min(0).max(10).default(2),
+  }).optional();
+
+  const progressSchema = z.object({
+    show_stage_progress: z.boolean().default(true),
+    show_stage_summary: z.boolean().default(true),
+  }).optional();
+
+  // goal_loop 段（Feature 201）：feature mode goal_loop agent_mode 的预算/迭代配置。
+  // 用 .default({}) 而非 .optional()：省略该段时 z.object 会用四项各自 default 填全，
+  // 使 validateConfig 输出始终含 goal_loop.* 全默认值（W2 修复——避免运行时读到 undefined 而非 5）。
+  // 四项均带 default —— 不破坏现有 config 校验（未声明该段的现有 config 仍通过，只是补默认）。
+  // 仅在 .specify/orchestration-overrides.yaml 启用 goal_loop 时被编排器读取（FR-005/006/007）。
+  const goalLoopSchema = z.object({
+    // 最大迭代轮数上限（FR-005），到顶且未达标则停止进 GATE_VERIFY
+    max_iterations: z.number().int().min(1).default(5),
+    // 连续无进展（五维 delta 全 0）轮数触发早停（FR-006）
+    no_progress_max_rounds: z.number().int().min(1).default(2),
+    // 单轮 verify 墙钟上限（秒，FR-007）——timeout 强制、可机器校验，主预算
+    max_verify_seconds: z.number().positive().default(300),
+    // 单轮编排器可见委派/调用数上限（FR-007）——best-effort 粗粒度安全网，辅助上限
+    max_tool_invocations: z.number().int().min(1).default(50),
+    // 命令集完整性校验（F204）：full 报告必须包含这些 kind 类别的 PASS 命令才能 REACHED_GOAL。
+    // 默认 []（跳过校验，保向后兼容）；项目级 opt-in：['build','test','lint','check']。
+    full_required_kinds: z.array(z.enum(['build', 'test', 'lint', 'check'])).default([]),
+  }).default({});
+
+  // Spectra batch 并发配置（Feature 146）。concurrency 的接受集与运行时
+  // src/config/spec-driver-config.ts:readBatchConcurrency 对齐：有限 number 或可解析为
+  // 有限数字的字符串（如 quoted "3"）。整数化与越界裁剪交由运行时 normalizeConcurrency
+  // 统一处理，故此处不加 int()/positive()，避免 validate gate 与运行时对同一配置判定相反。
+  const concurrencySchema = z.union([
+    z.number().finite(),
+    z.string().refine(
+      (s) => { const t = s.trim(); return t.length > 0 && Number.isFinite(Number(t)); },
+      { message: '必须是可解析为有限数字的字符串（如 "3"）' },
+    ),
+  ]);
+  const batchSchema = z.object({
+    concurrency: concurrencySchema.optional(),
+  }).strict().optional();
+
+  // fix_compliance 段（Feature 208，FR-015）：fix 模式流程依从性强制程度。
+  // 用 .default({}) 而非 .optional()：省略该段时 enforcement 被 default 填为 'block'，
+  // 使 validateConfig 输出始终含 fix_compliance.enforcement（与 goal_loop 同惯例）。
+  // 注意：Stop hook 判定路径刻意不 import 本模块（走 simple-yaml 非抛出式读取，见
+  // contracts/fix-compliance-config-field.md）；本 schema 只服务 validate-config 声明式校验。
+  const fixComplianceSchema = z.object({
+    enforcement: z.enum(['block', 'warn', 'off']).default('block'),
+  }).default({});
+
+  specDriverConfigSchema = z.object({
+    preset: z.enum(['balanced', 'quality-first', 'cost-efficient']).default('balanced'),
+    batch: batchSchema,
+    agents: agentsSchema,
+    model_compat: modelCompatSchema,
+    codex: codexSchema,
+    codex_thinking: codexThinkingSchema,
+    research: researchSchema,
+    verification: verificationSchema,
+    quality_gates: qualityGatesSchema,
+    gate_policy: z.enum(['strict', 'balanced', 'autonomous']).default('balanced'),
+    gates: gatesSchema,
+    retry: retrySchema,
+    progress: progressSchema,
+    goal_loop: goalLoopSchema,
+    fix_compliance: fixComplianceSchema,
+  }).strict();
+}
 
-export const specDriverConfigSchema = z.object({
-  preset: z.enum(['balanced', 'quality-first', 'cost-efficient']).default('balanced'),
-  agents: agentsSchema,
-  model_compat: modelCompatSchema,
-  codex: codexSchema,
-  codex_thinking: codexThinkingSchema,
-  research: researchSchema,
-  verification: verificationSchema,
-  quality_gates: qualityGatesSchema,
-  gate_policy: z.enum(['strict', 'balanced', 'autonomous']).default('balanced'),
-  gates: gatesSchema,
-  retry: retrySchema,
-  progress: progressSchema,
-}).strict();
+export { specDriverConfigSchema, zodAvailable };
 
 // ────────────────────────────────────────
 // 常量
@@ -127,6 +182,16 @@ export const BUILTIN_DEFAULTS = {
   'model_compat.runtime': 'auto',
   'codex.service_tier': 'fast',
   'codex_thinking.default_level': 'xhigh',
+  // goal_loop 默认值（Feature 201，W2 修复）——与 goalLoopSchema 各项 default 一致，
+  // 使 resolveEffectiveConfig 在 config 省略 goal_loop 段时也 surface 默认值。
+  'goal_loop.max_iterations': 5,
+  'goal_loop.no_progress_max_rounds': 2,
+  'goal_loop.max_verify_seconds': 300,
+  'goal_loop.max_tool_invocations': 50,
+  // F204：full 轮必需命令 kind 类别，默认 []（跳过校验，保向后兼容）。
+  'goal_loop.full_required_kinds': [],
+  // fix_compliance 默认值（Feature 208，FR-015）——block 为缺省强制程度。
+  'fix_compliance.enforcement': 'block',
 };
 
 /** preset 默认值表 */
@@ -231,9 +296,9 @@ export function suggestField(unknown, knownFields) {
 
 /** 顶层 Schema 合法字段名列表 */
 const KNOWN_TOP_LEVEL_FIELDS = [
-  'preset', 'agents', 'model_compat', 'codex', 'codex_thinking',
+  'preset', 'batch', 'agents', 'model_compat', 'codex', 'codex_thinking',
   'research', 'verification', 'quality_gates', 'gate_policy',
-  'gates', 'retry', 'progress',
+  'gates', 'retry', 'progress', 'goal_loop', 'fix_compliance',
 ];
 
 /**
@@ -249,6 +314,21 @@ export function validateConfig(parsedYaml) {
     return { success: true, data: {}, diagnostics };
   }
 
+  // 缺 zod 降级：无法做 schema 校验，best-effort 接受原样配置并标 degraded。
+  // success=true 保证 validate-config.mjs 不误判为校验失败退非 0（其退出码只看 error 级诊断）。
+  if (!zodAvailable) {
+    return {
+      success: true,
+      data: (parsedYaml && typeof parsedYaml === 'object') ? parsedYaml : {},
+      degraded: true,
+      diagnostics: [{
+        level: 'warning',
+        code: 'config.zod-unavailable',
+        message: '未能加载 zod，已跳过 spec-driver.config.yaml schema 校验并 best-effort 接受配置；如需完整校验请在已安装依赖的目录运行（npm i）或从仓内源路径运行',
+      }],
+    };
+  }
+
   const result = specDriverConfigSchema.safeParse(parsedYaml);
 
   if (result.success) {
@@ -302,11 +382,13 @@ export function validateConfig(parsedYaml) {
         path,
       });
     } else if (issue.code === 'too_small' && issue.type === 'number') {
-      // 正整数校验（如 timeout）
+      // 数值下界校验（如 timeout / goal_loop.* 预算项）。
+      // 部分字段允许小数（如 goal_loop.max_verify_seconds 用 z.number().positive()），
+      // 故文案统一用"正数"而非"正整数"，避免误导（W3 修复）。
       diagnostics.push({
         level: 'error',
         code: 'config.invalid-positive-int',
-        message: `\`${path}\` 必须为正整数，当前值: ${issue.minimum !== undefined ? `< ${issue.minimum}` : '非法'}`,
+        message: `\`${path}\` 必须为正数，当前值: ${issue.minimum !== undefined ? `< ${issue.minimum}` : '非法'}`,
         path,
       });
     } else {
@@ -389,6 +471,12 @@ export function resolveEffectiveConfig(options) {
     'model_compat.runtime',
     'codex.service_tier',
     'codex_thinking.default_level',
+    'goal_loop.max_iterations',
+    'goal_loop.no_progress_max_rounds',
+    'goal_loop.max_verify_seconds',
+    'goal_loop.max_tool_invocations',
+    'goal_loop.full_required_kinds',
+    'fix_compliance.enforcement',
   ];
 
   for (const dotPath of nestedKeys) {
@@ -400,6 +488,24 @@ export function resolveEffectiveConfig(options) {
     }
   }
 
+  // Spectra batch 子系统旋钮（Feature 146）——刻意与上方编排器 nestedKeys 分开处理。
+  // why 单独成块、且只在用户显式配置时才展示：
+  //   1) batch.concurrency 虽落在同一份 spec-driver.config.yaml，却由 Spectra batch 运行时消费，
+  //      而非 spec-driver 编排器；标注子系统来源以免被误读成编排器并发旋钮
+  //      （编排器并发是 orchestration-overrides.yaml 的 parallel_scheduling.max_concurrent_tasks）。
+  //   2) 其默认值 3 的 canonical source 在 src/ 运行时侧（cli/commands/batch.ts:resolveBatchConcurrency
+  //      与 batch-orchestrator.ts 的 `?? 3`），不在本插件脚本；故刻意不进 BUILTIN_DEFAULTS——
+  //      在此 hardcode 3 会与运行时默认形成双源，一旦运行时漂移就显示过期值，比"不展示"更误导
+  //      （见 111423f Codex R1 WARNING 2 的取舍）。
+  const batchConcurrency = getNestedValue(configYaml, 'batch.concurrency');
+  if (batchConcurrency !== undefined) {
+    entries.push({
+      key: 'batch.concurrency',
+      value: batchConcurrency,
+      source: 'config.yaml (spectra batch)',
+    });
+  }
+
   // preset 默认值提供的 agent 模型配置
   const presetDefaults = PRESET_DEFAULTS[effectivePreset] || {};
   const agents = configYaml.agents || {};

package/plugins/spec-driver/scripts/lib/ensure-gitignore.sh

@@ -0,0 +1,277 @@
+#!/usr/bin/env bash
+# Spec Driver - ignore 自举共享库（Feature 207）
+# 由 init-project.sh 与 postinstall.sh 共同 source。
+# 职责：确保 Spec Driver 落盘产物的 4 条 ignore 规则就位，避免脚手架与本机绝对路径
+#       污染宿主 repo 的 git diff / 交付 patch。提供两个入口：
+#         - ensure_spec_driver_gitignore    → 写宿主 <project_root>/.gitignore（团队共享）
+#         - ensure_spec_driver_git_exclude  → 写 <project_root>/.git/info/exclude（非 tracked，零 diff）
+#       两者共享内部注入实现 _spec_driver_inject_entries，行为契约一致（幂等、CRLF/NUL/symlink/
+#       negation 防御、mkdir 原子锁保护并发）。
+#
+# 注意：本文件只定义函数，不含 set -e / 顶层执行逻辑，避免被 source 时影响调用方主流程。
+#       函数内所有写入均显式检查返回值，不依赖 trap EXIT（避免污染被 source 进
+#       set -euo pipefail 调用方的退出钩子）。
+
+# Spec Driver 落盘产物的固定 4 条 ignore 条目（与开发仓库 .gitignore 一致，顺序即注入顺序）：
+#   .specify/.spec-driver-path  — 机器绝对路径（隐私 / 可移植）
+#   .specify/runs/              — 本地运行态
+#   .specify/scorecards/        — 插件默认品复制，可再生
+#   .specify/templates/         — 插件默认品复制，可再生
+# 写死为字面量作为唯一事实来源，不从外部读取，避免引入新的路径依赖。
+SPEC_DRIVER_GITIGNORE_ENTRIES=(
+  ".specify/.spec-driver-path"
+  ".specify/runs/"
+  ".specify/scorecards/"
+  ".specify/templates/"
+)
+
+# ── 并发取舍说明（W1 修复，Codex 四轮）─────────────────────────────────────
+# 本库刻意**不做 stale 锁抢占**：曾有的 mtime 阈值 + rmdir 重试逻辑存在 ABA 竞态——
+# 预置过期锁 + 高并发时，多个进程会同判 stale、rmdir 互删对方刚建的新锁，导致多个进程
+# 同时进入临界区重复注入。故抢锁失败一律直接 skipped:0。
+# 残余风险：进程在临界区内被 SIGKILL → 孤儿锁使该 repo 永久 skip 注入。此风险经权衡接受：
+#   (1) 临界区为毫秒级窗口，命中概率极低；
+#   (2) 孤儿锁只造成静默跳过（主流程零影响，下次会话无法自愈但不报错），
+#       危害远小于 ABA 重复写入把用户 .gitignore 堆出重复行。
+# ─────────────────────────────────────────────────────────────────────────
+
+# _spec_driver_has_nul <file>
+# 检测文件是否含 NUL 字节（0x00）。含 NUL 的文件不是合法文本，装载为 shell 变量会截断，
+# 无法可靠做整行匹配 → 一律拒写。跨平台实现：比较原始字节数与去除 NUL 后的字节数。
+# 返回 0（真）表示含 NUL，返回 1（假）表示不含或读取失败。
+_spec_driver_has_nul() {
+  local file="$1"
+  local raw stripped
+  raw="$(wc -c < "$file" 2>/dev/null)" || return 1
+  # LC_ALL=C 确保 tr 按字节而非多字节字符处理；去掉所有 NUL 后再计字节数
+  stripped="$(LC_ALL=C tr -d '\000' < "$file" 2>/dev/null | wc -c)" || return 1
+  # 归一化空白（wc 输出可能带前导空格）
+  raw="${raw//[[:space:]]/}"
+  stripped="${stripped//[[:space:]]/}"
+  [[ "$raw" != "$stripped" ]]
+}
+
+# _spec_driver_inject_entries <target_file> <with_header>
+#
+# 向 <target_file> 注入 SPEC_DRIVER_GITIGNORE_ENTRIES 中缺失的条目（幂等）。
+# 调用方须在持锁状态下调用；本函数不负责加锁/解锁（由入口函数统一管理）。
+#
+# 参数：
+#   target_file  - 目标 ignore 文件绝对路径（.gitignore 或 .git/info/exclude）
+#   with_header  - "1" 表示新建文件时写注释头；"0" 表示不写（exclude 场景不带头）
+#
+# 行为契约：
+#   - target_file 为 symlink（含 dangling）→ 一律不写，stdout: failed:0
+#     （-L 检测必须先于 -f 分支：dangling symlink 时 [[ ! -f ]] 为真会走创建分支，
+#      `>` 重定向会跟随 symlink 在 symlink 指向的外部路径创建文件——安全隐患）
+#   - target_file 含 NUL 字节 → 拒写，stdout: failed:0（文件不被改动）
+#   - target_file 不存在 → 创建（with_header=1 时带注释头 + 4 行条目），stdout: created:N
+#   - target_file 存在但缺条目 → 精确整行匹配缺失项追加到末尾，stdout: appended:N
+#   - target_file 存在且 4 条全就位 → 不写文件（mtime 不变），stdout: ready:0
+#   - negation 尊重：归一化视图中若存在以 '!' 开头、去掉 '!' 后等于该条目或以该条目为
+#     前缀的行（如 !.specify/templates/ 或 !.specify/templates/**），该条目跳过不追加
+#     （尊重用户显式 un-ignore 意图），跳过条目不计入 appended:N
+#   - 匹配采用 CRLF 归一化视图（tr -d '\r'）：CRLF 行尾文件不被误判为缺失而重复追加；
+#     但不改写原文件行尾
+#   - 写入失败（只读 FS 等）→ stdout: failed:0
+#   - 始终 return 0
+_spec_driver_inject_entries() {
+  local target_file="$1"
+  local with_header="$2"
+
+  # symlink 防御（含 dangling）：必须先于 -f 分支判断
+  if [[ -L "$target_file" ]]; then
+    printf 'failed:0\n'
+    return 0
+  fi
+
+  # NUL 防御：仅对已存在的普通文件检测（不存在时无从检测，创建分支会写纯文本）
+  if [[ -f "$target_file" ]] && _spec_driver_has_nul "$target_file"; then
+    printf 'failed:0\n'
+    return 0
+  fi
+
+  # 场景 1：文件不存在 → 创建新文件，stdout: created:N
+  if [[ ! -f "$target_file" ]]; then
+    # 关键 bash 地雷（W-A 修复）：绝不用「复合命令组 { …; } > file」形式写入。
+    #   1. 命令组的重定向失败退出码在 `if ! { …; } > file` 形式下会被吞掉——
+    #      直接跑 rc=1，但 `if !` 包裹时不进 then 分支 → failed 分支永不触发 →
+    #      落到 created:N 误报（.git/info 被普通文件占用时 `> exclude` 必然失败）。
+    #   2. `> file 2>/dev/null` 中 stdout 重定向失败发生在 `2>/dev/null` 生效之前 →
+    #      "Not a directory" 等 stderr 泄漏。
+    # 正解：内容先攒进变量，再用「简单命令」写入，且把 `2>/dev/null` 置于 `>` 之前
+    # 先吞 stderr。简单命令的 `if !` 重定向失败已实测能被捕获（bash 3.2 与 5.x 一致）。
+    local content=""
+    if [[ "$with_header" == "1" ]]; then
+      content="# Spec Driver 本地缓存与运行态（自动注入，可手动调整顺序）"$'\n'
+    fi
+    local entry
+    for entry in "${SPEC_DRIVER_GITIGNORE_ENTRIES[@]}"; do
+      content+="${entry}"$'\n'
+    done
+    if ! printf '%s' "$content" 2>/dev/null > "$target_file"; then
+      printf 'failed:0\n'
+      return 0
+    fi
+    printf 'created:%d\n' "${#SPEC_DRIVER_GITIGNORE_ENTRIES[@]}"
+    return 0
+  fi
+
+  # 场景 2/3：文件已存在 → 逐条精确整行匹配（CRLF 归一化视图），收集缺失项
+  # tr -d '\r' 剥离视图内的 CR，使 CRLF 行尾文件不被误判为缺失；不改写原文件。
+  local normalized_view
+  normalized_view="$(tr -d '\r' < "$target_file" 2>/dev/null)" || normalized_view=""
+  local missing=()
+  local entry
+  for entry in "${SPEC_DRIVER_GITIGNORE_ENTRIES[@]}"; do
+    # -F 纯字符串、-x 整行匹配：避免 .specify/runs/ 被 .specify/runs/xxx 宽松误判为已存在
+    # 用 here-string 而非管道喂 grep：调用方多为 set -o pipefail，大文件（>64KB pipe buffer）
+    # 且目标条目在文件前部时，grep -q 匹配即退会令 printf 写端收 SIGPIPE，管道退出码 141
+    # 被 pipefail 放大成整体失败 → 已存在条目被误判缺失而重复追加。here-string 无管道，规避此问题。
+    if grep -qxF -- "$entry" <<< "$normalized_view"; then
+      continue
+    fi
+    # negation 冲突检测：用户显式 un-ignore（! 前缀）时尊重其意图，跳过该条目。
+    # 匹配 !<entry> 精确等，或 !<entry>* 前缀形式（如 !.specify/templates/**）。
+    if _spec_driver_has_negation "$normalized_view" "$entry"; then
+      continue
+    fi
+    missing+=("$entry")
+  done
+
+  # 全部就位（或被 negation 尊重跳过）→ 不触碰文件（幂等契约：mtime 不变），stdout: ready:0
+  if [[ ${#missing[@]} -eq 0 ]]; then
+    printf 'ready:0\n'
+    return 0
+  fi
+
+  # 部分缺失 → 追加缺失条目到文件末尾（不带注释头，追加场景保持幂等最简）
+  # 末尾无换行边界：若最后一个字节非换行符，先补一个 \n 再追加，避免与最后一行粘连
+  if [[ -s "$target_file" ]]; then
+    local last_char
+    last_char="$(tail -c 1 "$target_file" 2>/dev/null)"
+    if [[ -n "$last_char" ]]; then
+      # 2>/dev/null 置于 >> 之前先吞 stderr（同 W-A：避免重定向失败时 "Not a directory" 泄漏）
+      if ! printf '\n' 2>/dev/null >> "$target_file"; then
+        printf 'failed:0\n'
+        return 0
+      fi
+    fi
+  fi
+
+  for entry in "${missing[@]}"; do
+    # 同上：2>/dev/null 前置于 >>，消除 stderr 泄漏
+    if ! printf '%s\n' "$entry" 2>/dev/null >> "$target_file"; then
+      printf 'failed:0\n'
+      return 0
+    fi
+  done
+
+  printf 'appended:%d\n' "${#missing[@]}"
+  return 0
+}
+
+# _spec_driver_has_negation <normalized_view> <entry>
+# 判断归一化视图中是否存在尊重该条目的 negation 行（以 '!' 开头）。
+# 命中形式：!<entry>（精确）或 !<entry> 后接任意字符（前缀，如 !.specify/templates/**）。
+# 返回 0（真）表示存在 negation，返回 1（假）表示不存在。
+_spec_driver_has_negation() {
+  local view="$1"
+  local entry="$2"
+  local line stripped
+  while IFS= read -r line; do
+    [[ "$line" == '!'* ]] || continue
+    stripped="${line#!}"
+    # 精确等 或 以 entry 为前缀（覆盖 !<entry> / !<entry>** / !<entry>foo）
+    if [[ "$stripped" == "$entry" || "$stripped" == "$entry"* ]]; then
+      return 0
+    fi
+  done <<< "$view"
+  return 1
+}
+
+# _spec_driver_acquire_lock <lock_dir>
+# 尝试获取 mkdir 原子锁。成功返回 0；失败（已被占用）返回 1。
+# 不做 stale 抢占（见文件顶部并发取舍说明）。
+_spec_driver_acquire_lock() {
+  mkdir "$1" 2>/dev/null
+}
+
+# ensure_spec_driver_gitignore <project_root>
+#
+# 写宿主 <project_root>/.gitignore（团队共享的 ignore 配置）。
+# 行为契约见 plan.md §1.1：
+#   - 三态输出 created:N / appended:N / ready:0 / failed:0 / skipped:0
+#   - symlink / NUL / negation 防御见 _spec_driver_inject_entries
+#   - 非 git 目录也照常写入（用户后续 git init 即生效）
+#   - 并发：mkdir 原子锁保护临界区；抢锁失败 → skipped:0（不 stale 抢占）
+#   - 始终 return 0；仅 project_root 为空或非目录时 return 1
+ensure_spec_driver_gitignore() {
+  local project_root="$1"
+  if [[ -z "$project_root" || ! -d "$project_root" ]]; then
+    return 1
+  fi
+
+  local gitignore_file="${project_root}/.gitignore"
+  local lock_dir="${project_root}/.specify/.ensure-gitignore.lock"
+
+  # 锁父路径 .specify/ 兜底创建（.specify/ 是 Spec Driver 自身域，不越界）
+  mkdir -p "${project_root}/.specify" 2>/dev/null || true
+
+  if ! _spec_driver_acquire_lock "$lock_dir"; then
+    printf 'skipped:0\n'
+    return 0
+  fi
+
+  local result
+  result="$(_spec_driver_inject_entries "$gitignore_file" "1")"
+  rmdir "$lock_dir" 2>/dev/null || true
+  printf '%s\n' "$result"
+  return 0
+}
+
+# ensure_spec_driver_git_exclude <project_root>
+#
+# 写 <project_root>/.git/info/exclude（Git 原生的非 tracked 项目级 ignore）。
+# 动机：用户 repo 的 .gitignore 几乎都被 track，注入产生 `M .gitignore` 仍进 patch；
+#       写 .git/info/exclude 零 diff 污染。这是分层防线的主防线。
+# 行为契约：
+#   - 仅当 <project_root>/.git 是**目录**时执行；.git 为文件（worktree/submodule 的
+#     gitdir 指针）→ skipped:0（gitdir 解析复杂且 exclude 共享主仓库，.gitignore 路径覆盖）
+#   - 非 git repo（无 .git）→ skipped:0
+#   - .git/info/ 不存在则 mkdir -p 创建
+#   - 三态输出与防御同 _spec_driver_inject_entries（不带注释头）
+#   - 复用同一把锁（与 gitignore 各自独立拿/放锁，无死锁）
+#   - 始终 return 0；仅 project_root 为空或非目录时 return 1
+ensure_spec_driver_git_exclude() {
+  local project_root="$1"
+  if [[ -z "$project_root" || ! -d "$project_root" ]]; then
+    return 1
+  fi
+
+  local git_dir="${project_root}/.git"
+  # .git 必须是目录：非 git repo 或 worktree/submodule（.git 为文件）→ 跳过
+  if [[ ! -d "$git_dir" ]]; then
+    printf 'skipped:0\n'
+    return 0
+  fi
+
+  local exclude_file="${git_dir}/info/exclude"
+  local lock_dir="${project_root}/.specify/.ensure-gitignore.lock"
+
+  # info/ 目录兜底创建（标准 git repo 一般已有，但防御缺失）
+  mkdir -p "${git_dir}/info" 2>/dev/null || true
+  # 锁父路径 .specify/ 兜底创建
+  mkdir -p "${project_root}/.specify" 2>/dev/null || true
+
+  if ! _spec_driver_acquire_lock "$lock_dir"; then
+    printf 'skipped:0\n'
+    return 0
+  fi
+
+  local result
+  result="$(_spec_driver_inject_entries "$exclude_file" "0")"
+  rmdir "$lock_dir" 2>/dev/null || true
+  printf '%s\n' "$result"
+  return 0
+}