spectra-cli 4.1.1 → 4.3.0

package/plugins/spec-driver/scripts/lib/init-project-output.sh

@@ -120,6 +120,34 @@ print_init_text_result() {
         echo -e "  ⚠️  ${YELLOW}.specify/templates 仍缺少模板: ${missing}${NC}"
       fi
       ;;
+    git_exclude)
+      if [[ "$value" == ready ]]; then
+        echo -e "  ✅ .git/info/exclude 已含 Spec Driver 忽略规则"
+      elif [[ "$value" == created:* ]]; then
+        echo -e "  ✅ 已创建 .git/info/exclude 并写入 Spec Driver 忽略规则（非 tracked，零 diff）"
+      elif [[ "$value" == injected:* ]]; then
+        local n="${value#injected:}"
+        echo -e "  ✅ 已向 .git/info/exclude 追加 ${n} 条 Spec Driver 忽略规则（非 tracked，零 diff）"
+      elif [[ "$value" == skipped ]]; then
+        echo -e "  ℹ️  非标准 git 目录（非 git / worktree / submodule），跳过 .git/info/exclude 注入（由 .gitignore 覆盖）"
+      elif [[ "$value" == skip_error ]]; then
+        echo -e "  ⚠️  ${YELLOW}.git/info/exclude 注入失败，已跳过（不影响初始化）${NC}"
+      fi
+      ;;
+    gitignore)
+      if [[ "$value" == ready ]]; then
+        echo -e "  ✅ .gitignore 已含 Spec Driver 忽略规则"
+      elif [[ "$value" == created:* ]]; then
+        echo -e "  ✅ 已创建 .gitignore 并写入 Spec Driver 忽略规则"
+      elif [[ "$value" == injected:* ]]; then
+        local n="${value#injected:}"
+        echo -e "  ✅ 已向 .gitignore 追加 ${n} 条 Spec Driver 忽略规则"
+      elif [[ "$value" == skip_error ]]; then
+        echo -e "  ⚠️  ${YELLOW}.gitignore 注入失败，已跳过（不影响初始化）${NC}"
+      elif [[ "$value" == lock_skipped ]]; then
+        echo -e "  ⏭️  ${YELLOW}.gitignore 注入被并发会话锁定，本次跳过（下次会话自动补齐）${NC}"
+      fi
+      ;;
   esac
 }
 

package/plugins/spec-driver/scripts/lib/load-zod.mjs

@@ -0,0 +1,62 @@
+/**
+ * load-zod.mjs -- 共享的同步 zod 加载 helper。
+ *
+ * 为什么需要：spec-driver 脚本原本在多个 schema 模块顶层 `import { z } from 'zod'`。
+ * ESM 顶层 import 在模块加载期静态解析，缺 zod（如插件缓存目录无 node_modules）时
+ * 会抛 ERR_MODULE_NOT_FOUND 硬崩，无法被运行时 try/catch 捕获。
+ *
+ * 本 helper 用 createRequire + require('zod') 同步加载（zod 自带 CJS 入口，可 require），
+ * 把"加载期硬崩"收敛为"可捕获的运行时缺失"：缺 zod 时返回 { available: false }
+ * 而非抛错，从而让调用方决定降级路径。保持全同步调用链，避免动态 import 的 async 涟漪。
+ */
+
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+// memoize：首次加载结果缓存，后续直接返回，避免重复 require / 重复求值
+let _cache = null;
+
+/**
+ * 同步加载 zod，永不抛错。
+ * @returns {{ z: object|null, available: boolean, error: Error|null }}
+ *   - z：可用时为 zod 命名空间（mod.z ?? mod），缺失时为 null
+ *   - available：zod 是否成功加载
+ *   - error：缺失时的捕获错误（用于诊断），可用时为 null
+ */
+export function loadZod() {
+  if (_cache) return _cache;
+
+  // 测试 seam：强制走缺失分支，使"缺 zod"路径可在有 node_modules 的仓库内被复现
+  if (
+    process.env.SPEC_DRIVER_FORCE_ZOD_MISSING === '1' ||
+    process.env.SPEC_DRIVER_FORCE_ZOD_MISSING === 'true'
+  ) {
+    _cache = {
+      z: null,
+      available: false,
+      error: new Error('zod 加载被 SPEC_DRIVER_FORCE_ZOD_MISSING 强制禁用'),
+    };
+    return _cache;
+  }
+
+  try {
+    const mod = require('zod');
+    // zod 的 CJS 模块上 `.z` 是命名空间；某些打包形态下退回 mod 本体
+    const z = mod.z ?? mod;
+    _cache = { z, available: true, error: null };
+  } catch (error) {
+    // require 缺失抛 MODULE_NOT_FOUND（可捕获），降级为运行时缺失而非加载期硬崩
+    _cache = { z: null, available: false, error };
+  }
+
+  return _cache;
+}
+
+/**
+ * 仅供测试使用：清空 memoize 缓存，使同进程内可在切换环境变量后重新求值。
+ * 注意：本函数只清 load-zod.mjs 内的 _cache，不影响已加载 schema 模块固化的 zodAvailable。
+ */
+export function __resetZodCacheForTest() {
+  _cache = null;
+}

package/plugins/spec-driver/scripts/lib/project-profile-resolver.mjs

@@ -6,6 +6,7 @@ import {
   EXCLUDED_EXECUTION_FIELDS,
   referenceEntrySchema,
   resolvedProjectProfileSchema,
+  zodAvailable,
 } from './project-profile-schema.mjs';
 
 function createDiagnostic(level, code, message) {
@@ -69,19 +70,51 @@ function normalizeReferenceEntry(entry, source, projectRoot, diagnostics) {
     return null;
   }
 
-  const parsed = referenceEntrySchema.safeParse(entry);
-  if (!parsed.success) {
-    diagnostics.push(
-      createDiagnostic(
-        'warning',
-        'project-context.invalid-reference',
-        `reference 条目无效：${parsed.error.issues.map((issue) => issue.message).join('; ')}`,
-      ),
-    );
-    return null;
+  let normalized;
+  if (zodAvailable) {
+    // zod 在场：保持原有 schema 校验逻辑逐字节不变
+    const parsed = referenceEntrySchema.safeParse(entry);
+    if (!parsed.success) {
+      diagnostics.push(
+        createDiagnostic(
+          'warning',
+          'project-context.invalid-reference',
+          `reference 条目无效：${parsed.error.issues.map((issue) => issue.message).join('; ')}`,
+        ),
+      );
+      return null;
+    }
+    normalized = { ...parsed.data, source };
+  } else {
+    // 缺 zod 降级：手写构造已知字段。必须复现 referenceEntrySchema 的 .trim() 语义，
+    // 否则 `path: " docs/a.md "` 在降级路径会带空格、与正常路径 shape 分叉（W1）。
+    // 不浅拷贝 entry（会绕过 trim），逐字段 trim；空串视为缺省（不带入）。
+    // 这 4 个字段在 zod schema 里均为 z.string()，非字符串值（如 simple-yaml 把
+    // `path: 123` 强转成 number）本就应被拒绝；故仅接受 string 且 trim 后非空，
+    // 不再原样带入非字符串值（否则后续 path.resolve 会因 number 抛 ERR_INVALID_ARG_TYPE）。
+    normalized = { source };
+    for (const key of ['label', 'path', 'url', 'purpose']) {
+      const raw = entry[key];
+      if (typeof raw === 'string') {
+        const trimmed = raw.trim();
+        if (trimmed) normalized[key] = trimmed;
+      }
+    }
+    if (typeof entry.required === 'boolean') {
+      normalized.required = entry.required;
+    }
+    // 有效性判定基于 trim 后的 path/url（与 referenceEntrySchema.refine 等价）
+    if (!normalized.path && !normalized.url) {
+      diagnostics.push(
+        createDiagnostic(
+          'warning',
+          'project-context.invalid-reference',
+          'reference 条目无效：reference entry requires either path or url',
+        ),
+      );
+      return null;
+    }
   }
-
-  const normalized = { ...parsed.data, source };
   if (normalized.path) {
     normalized.resolvedPath = path.resolve(projectRoot, normalized.path);
     normalized.exists = fs.existsSync(normalized.resolvedPath);
@@ -482,6 +515,8 @@ function normalizeLegacyMarkdown(content, projectRoot, diagnostics) {
         .map((line) => line.replace(/^[-*]\s*/, '').trim())
         .filter(Boolean),
     ),
+    // F191：legacy-md 不支持 knowledge_sources → 稳定默认形态（修 Codex W1）
+    knowledgeSources: defaultKnowledgeSources(),
   };
 }
 
@@ -521,6 +556,46 @@ function normalizeYamlInput(raw, projectRoot, diagnostics) {
     workflowPreferences: normalizeWorkflowPreferences(raw.workflow_preferences),
     forbiddenChanges: normalizeStringList(raw.forbidden_changes),
     notes: normalizeStringList(raw.notes),
+    // F191：scaffold-kb 预查注入配置（仅 yaml 路径设置；schema optional，其他路径省略合法）
+    knowledgeSources: normalizeKnowledgeSources(raw.knowledge_sources, projectRoot, diagnostics),
+  };
+}
+
+/**
+ * F191 — 归一化 knowledge_sources（scaffold-kb 预查注入配置）。
+ * 缺省/非对象 → 默认形态（enabled:false）；路径相对 projectRoot 解析为绝对路径（不校验存在性，
+ * 存在性降级交给 kb-prequery/query，FR-005）；非法 top_k/max_inject_chars → 回落默认 + diagnostics。
+ */
+/** F191 — knowledgeSources 稳定默认形态（4 条 resolver 路径共用，修 Codex W1） */
+function defaultKnowledgeSources() {
+  return { enabled: false, vendorKb: null, projectKb: null, topK: 3, maxInjectChars: 6000 };
+}
+
+function normalizeKnowledgeSources(raw, projectRoot, diagnostics) {
+  if (!raw || typeof raw !== 'object') return defaultKnowledgeSources();
+
+  const resolvePath = (p) =>
+    typeof p === 'string' && p.trim().length > 0 ? path.resolve(projectRoot, p.trim()) : null;
+
+  const posInt = (value, fallback, field) => {
+    if (value === undefined) return fallback;
+    if (Number.isInteger(value) && value > 0) return value;
+    diagnostics.push(
+      createDiagnostic(
+        'warning',
+        'project-context.knowledge-sources-invalid',
+        `knowledge_sources.${field} 必须为正整数，已回落默认 ${fallback}`,
+      ),
+    );
+    return fallback;
+  };
+
+  return {
+    enabled: raw.enabled === true,
+    vendorKb: resolvePath(raw.vendor_kb),
+    projectKb: resolvePath(raw.project_kb),
+    topK: posInt(raw.top_k, 3, 'top_k'),
+    maxInjectChars: posInt(raw.max_inject_chars, 6000, 'max_inject_chars'),
   };
 }
 
@@ -529,6 +604,16 @@ export function resolveProjectContext({ projectRoot }) {
   const yamlPath = path.join(specifyDir, 'project-context.yaml');
   const markdownPath = path.join(specifyDir, 'project-context.md');
   const diagnostics = [];
+  // 缺 zod 降级：仅在入口 push 一条 warning（避免 reference 多条目时重复）
+  if (!zodAvailable) {
+    diagnostics.push(
+      createDiagnostic(
+        'warning',
+        'project-context.zod-unavailable',
+        '未能加载 zod，已跳过 project-context schema 校验并使用手写归一化结果；如需完整校验请在已安装依赖的目录运行（npm i）或从仓内源路径运行 spec-driver 脚本',
+      ),
+    );
+  }
   const sourceLayers = [
     'user-input',
     'skill-contract',
@@ -565,6 +650,7 @@ export function resolveProjectContext({ projectRoot }) {
     },
     forbiddenChanges: [],
     notes: [],
+    knowledgeSources: defaultKnowledgeSources(),
   };
 
   if (yamlExists && markdownExists) {
@@ -610,45 +696,51 @@ export function resolveProjectContext({ projectRoot }) {
     );
   }
 
-  const parsedProfile = resolvedProjectProfileSchema.safeParse(normalized);
-  if (!parsedProfile.success) {
-    diagnostics.push(
-      createDiagnostic(
-        'warning',
-        'project-context.schema-fallback',
-        `project-context 解析结果存在结构问题，已回退到安全默认值：${parsedProfile.error.issues
-          .map((issue) => issue.message)
-          .join('; ')}`,
-      ),
-    );
-    normalized = resolvedProjectProfileSchema.parse({
-      product: null,
-      owner: null,
-      references: [],
-      architectureConstraints: [],
-      verificationPolicy: {
-        requireRealExecution: true,
-        requiredCommands: [],
-        notes: [],
-      },
-      researchPolicy: {
-        onlineRequired: false,
-        minPoints: 0,
-        maxPoints: 5,
-        preferredTools: [],
-        notes: [],
-      },
-      workflowPreferences: {
-        defaultMode: null,
-        preferredPreset: null,
+  if (zodAvailable) {
+    // zod 在场：保持原有 safeParse + schema-fallback 兜底逻辑逐字节不变
+    const parsedProfile = resolvedProjectProfileSchema.safeParse(normalized);
+    if (!parsedProfile.success) {
+      diagnostics.push(
+        createDiagnostic(
+          'warning',
+          'project-context.schema-fallback',
+          `project-context 解析结果存在结构问题，已回退到安全默认值：${parsedProfile.error.issues
+            .map((issue) => issue.message)
+            .join('; ')}`,
+        ),
+      );
+      normalized = resolvedProjectProfileSchema.parse({
+        product: null,
+        owner: null,
+        references: [],
+        architectureConstraints: [],
+        verificationPolicy: {
+          requireRealExecution: true,
+          requiredCommands: [],
+          notes: [],
+        },
+        researchPolicy: {
+          onlineRequired: false,
+          minPoints: 0,
+          maxPoints: 5,
+          preferredTools: [],
+          notes: [],
+        },
+        workflowPreferences: {
+          defaultMode: null,
+          preferredPreset: null,
+          notes: [],
+        },
+        forbiddenChanges: [],
         notes: [],
-      },
-      forbiddenChanges: [],
-      notes: [],
-    });
-  } else {
-    normalized = parsedProfile.data;
+        knowledgeSources: defaultKnowledgeSources(),
+      });
+    } else {
+      normalized = parsedProfile.data;
+    }
   }
+  // 缺 zod 降级：跳过 safeParse（normalized 由手写 normalizeYamlInput / normalizeLegacyMarkdown
+  // 构建，结构可信），直接沿用 normalized —— 等价于 zod 在场时 parse 成功分支的效果。
 
   const existingReferences = normalized.references.filter((entry) => entry.exists !== false || entry.url);
   const missingReferences = normalized.references.filter((entry) => entry.exists === false);

package/plugins/spec-driver/scripts/lib/project-profile-schema.mjs

@@ -1,4 +1,7 @@
-import { z } from 'zod';
+import { loadZod } from './load-zod.mjs';
+
+// 经共享 helper 同步加载 zod；缺失时 zodAvailable=false，模块加载不崩
+const { z, available: zodAvailable } = loadZod();
 
 export const EXCLUDED_EXECUTION_FIELDS = new Set([
   'phase_focus',
@@ -17,62 +20,93 @@ export const ALLOWED_TOP_LEVEL_FIELDS = new Set([
   'workflow_preferences',
   'forbidden_changes',
   'notes',
+  // F191：scaffold-kb 预查注入配置（加入白名单避免 unknown-field 警告）
+  'knowledge_sources',
 ]);
 
-export const referenceEntryObjectSchema = z.object({
-  label: z.string().trim().min(1).optional(),
-  path: z.string().trim().min(1).optional(),
-  url: z.string().trim().url().optional(),
-  required: z.boolean().optional(),
-  purpose: z.string().trim().min(1).optional(),
-});
+// schema 求值必须全部包进 zodAvailable 守卫：缺 zod 时模块体完全不触碰 z，
+// 否则会从 MODULE_NOT_FOUND 退化为 ReferenceError —— 等于没修。
+// ESM 语法限制 export const 不能进 if 块，故用 let 顶层声明 + 守卫内赋值 + 末尾统一 export。
+let referenceEntryObjectSchema = null;
+let referenceEntrySchema = null;
+let resolvedReferenceEntrySchema = null;
+let resolvedProjectProfileSchema = null;
 
-export const referenceEntrySchema = referenceEntryObjectSchema.refine(
-  (value) => Boolean(value.path || value.url),
-  {
-    message: 'reference entry requires either path or url',
-  },
-);
+if (zodAvailable) {
+  referenceEntryObjectSchema = z.object({
+    label: z.string().trim().min(1).optional(),
+    path: z.string().trim().min(1).optional(),
+    url: z.string().trim().url().optional(),
+    required: z.boolean().optional(),
+    purpose: z.string().trim().min(1).optional(),
+  });
 
-export const resolvedReferenceEntrySchema = referenceEntryObjectSchema.extend({
-  exists: z.boolean().optional(),
-  resolvedPath: z.string().trim().min(1).optional(),
-  source: z.enum(['yaml', 'markdown']).optional(),
-});
+  referenceEntrySchema = referenceEntryObjectSchema.refine(
+    (value) => Boolean(value.path || value.url),
+    {
+      message: 'reference entry requires either path or url',
+    },
+  );
 
-export const resolvedProjectProfileSchema = z.object({
-  product: z
-    .object({
-      name: z.string().trim().min(1).optional(),
-      summary: z.string().trim().min(1).optional(),
-    })
-    .nullable(),
-  owner: z
-    .object({
-      name: z.string().trim().min(1).optional(),
-      team: z.string().trim().min(1).optional(),
-      email: z.string().trim().email().optional(),
-    })
-    .nullable(),
-  references: z.array(resolvedReferenceEntrySchema),
-  architectureConstraints: z.array(z.string().trim().min(1)),
-  verificationPolicy: z.object({
-    requireRealExecution: z.boolean(),
-    requiredCommands: z.array(z.string().trim().min(1)),
-    notes: z.array(z.string().trim().min(1)),
-  }),
-  researchPolicy: z.object({
-    onlineRequired: z.boolean(),
-    minPoints: z.number().int().min(0),
-    maxPoints: z.number().int().min(0),
-    preferredTools: z.array(z.string().trim().min(1)),
-    notes: z.array(z.string().trim().min(1)),
-  }),
-  workflowPreferences: z.object({
-    defaultMode: z.string().trim().min(1).nullable(),
-    preferredPreset: z.string().trim().min(1).nullable(),
+  resolvedReferenceEntrySchema = referenceEntryObjectSchema.extend({
+    exists: z.boolean().optional(),
+    resolvedPath: z.string().trim().min(1).optional(),
+    source: z.enum(['yaml', 'markdown']).optional(),
+  });
+
+  resolvedProjectProfileSchema = z.object({
+    product: z
+      .object({
+        name: z.string().trim().min(1).optional(),
+        summary: z.string().trim().min(1).optional(),
+      })
+      .nullable(),
+    owner: z
+      .object({
+        name: z.string().trim().min(1).optional(),
+        team: z.string().trim().min(1).optional(),
+        email: z.string().trim().email().optional(),
+      })
+      .nullable(),
+    references: z.array(resolvedReferenceEntrySchema),
+    architectureConstraints: z.array(z.string().trim().min(1)),
+    verificationPolicy: z.object({
+      requireRealExecution: z.boolean(),
+      requiredCommands: z.array(z.string().trim().min(1)),
+      notes: z.array(z.string().trim().min(1)),
+    }),
+    researchPolicy: z.object({
+      onlineRequired: z.boolean(),
+      minPoints: z.number().int().min(0),
+      maxPoints: z.number().int().min(0),
+      preferredTools: z.array(z.string().trim().min(1)),
+      notes: z.array(z.string().trim().min(1)),
+    }),
+    workflowPreferences: z.object({
+      defaultMode: z.string().trim().min(1).nullable(),
+      preferredPreset: z.string().trim().min(1).nullable(),
+      notes: z.array(z.string().trim().min(1)),
+    }),
+    forbiddenChanges: z.array(z.string().trim().min(1)),
     notes: z.array(z.string().trim().min(1)),
-  }),
-  forbiddenChanges: z.array(z.string().trim().min(1)),
-  notes: z.array(z.string().trim().min(1)),
-});
+    // F191：scaffold-kb 预查注入配置。OPTIONAL —— 仅 yaml 路径设置；md/fallback 路径省略仍合法，
+    // 避免新增 required 字段触发 safeParse 失败 → whole-profile fallback 清空旧字段（Codex 零回归关注点）
+    knowledgeSources: z
+      .object({
+        enabled: z.boolean(),
+        vendorKb: z.string().nullable(),
+        projectKb: z.string().nullable(),
+        topK: z.number().int().positive(),
+        maxInjectChars: z.number().int().positive(),
+      })
+      .optional(),
+  });
+}
+
+export {
+  zodAvailable,
+  referenceEntryObjectSchema,
+  referenceEntrySchema,
+  resolvedReferenceEntrySchema,
+  resolvedProjectProfileSchema,
+};

package/plugins/spec-driver/scripts/postinstall.sh

@@ -14,7 +14,7 @@ BOLD='\033[1m'
 
 # Plugin 信息
 PLUGIN_NAME="Spec Driver"
-PLUGIN_VERSION="4.0.0"
+PLUGIN_VERSION="4.3.0"
 MIN_CLAUDE_VERSION="1.0.0"
 
 # 推算插件根目录
@@ -42,6 +42,18 @@ write_plugin_path() {
   # 幂等写入路径文件
   if [[ -d "$PROJECT_DIR/.specify" ]]; then
     echo -n "$PLUGIN_DIR" > "$PROJECT_DIR/.specify/.spec-driver-path"
+
+    # 确保 ignore 规则就位，避免绝对路径泄漏进用户 git diff（Feature 207）。
+    # SessionStart hook 只写 .git/info/exclude（非 tracked，零 diff）——伦理面：hook 不应
+    # 静默修改用户 tracked 的 .gitignore；.gitignore 注入交由 init-project.sh（显式初始化）。
+    # 非 git repo 时 exclude 注入自动 skip（无 .git 目录）；但注意上方 .spec-driver-path 落盘
+    # 是路径发现机制的本职行为（7 个 SKILL 依赖此文件定位插件），不在 ignore 注入范围——
+    # 非 git 场景无 git diff 概念，该文件的 ignore 保护要等用户后续 git init + 跑 init-project 才补上。
+    # postinstall 先于 init 触发，须静默执行；全程 || true 防御 set -euo pipefail 下的连锁失败
+    if [[ -f "$SCRIPT_DIR/lib/ensure-gitignore.sh" ]]; then
+      source "$SCRIPT_DIR/lib/ensure-gitignore.sh"
+      ensure_spec_driver_git_exclude "$PROJECT_DIR" >/dev/null 2>&1 || true
+    fi
   else
     echo "[警告] 无法创建 $PROJECT_DIR/.specify/ 目录，跳过路径写入" >&2
   fi

package/plugins/spec-driver/scripts/record-workflow-run.mjs

@@ -25,6 +25,14 @@ function parseArgs(argv) {
     artifacts: [],
     warnings: [],
     json: false,
+    complianceVerdict: null,
+  };
+
+  // FR-014：仅当出现任意 --compliance-* flag 时才实例化 complianceVerdict 对象，
+  // 未传参时保持 null → 事件对象不含该键（向后兼容，字节级不变）。
+  const ensureComplianceVerdict = () => {
+    if (!args.complianceVerdict) args.complianceVerdict = {};
+    return args.complianceVerdict;
   };
 
   for (let index = 0; index < argv.length; index += 1) {
@@ -89,6 +97,26 @@ function parseArgs(argv) {
         args.warnings.push(...splitList(argv[index + 1]));
         index += 1;
         break;
+      case '--compliance-closure-form':
+        ensureComplianceVerdict().closureForm = argv[index + 1] ?? null;
+        index += 1;
+        break;
+      case '--compliance-compliant':
+        ensureComplianceVerdict().compliant = parseBooleanFlag(argv[index + 1]);
+        index += 1;
+        break;
+      case '--compliance-missing':
+        ensureComplianceVerdict().missing = splitList(argv[index + 1]);
+        index += 1;
+        break;
+      case '--compliance-degraded':
+        ensureComplianceVerdict().degraded = parseBooleanFlag(argv[index + 1]);
+        index += 1;
+        break;
+      case '--compliance-block-count':
+        ensureComplianceVerdict().blockCount = parseOptionalNumber(argv[index + 1]);
+        index += 1;
+        break;
       case '--json':
         args.json = true;
         break;
@@ -147,6 +175,12 @@ export function recordWorkflowRun(options = {}) {
     warnings,
   };
 
+  // FR-014：仅当调用方显式提供 complianceVerdict 时才追加该键（未提供 → 事件字节级不变）。
+  const complianceVerdict = normalizeComplianceVerdict(options.complianceVerdict);
+  if (complianceVerdict) {
+    event.complianceVerdict = complianceVerdict;
+  }
+
   const runsDir = path.join(projectRoot, '.specify', 'runs');
   fs.mkdirSync(runsDir, { recursive: true });
   const targetFile = path.join(runsDir, `${finishedAt.slice(0, 7)}.jsonl`);
@@ -182,6 +216,47 @@ function resolveDurationMs(durationMs, startedAt, finishedAt) {
   return Number.isFinite(delta) && delta >= 0 ? delta : null;
 }
 
+function parseBooleanFlag(rawValue) {
+  const value = normalizeString(rawValue);
+  if (value === null) {
+    return null;
+  }
+  if (value.toLowerCase() === 'true') {
+    return true;
+  }
+  if (value.toLowerCase() === 'false') {
+    return false;
+  }
+  return null;
+}
+
+/**
+ * 归一化 complianceVerdict（FR-014）。传入 null/undefined/非对象 → 返回 null（不追加事件键）。
+ * 仅保留契约字段（closureForm/compliant/missing/degraded/blockCount），忽略未知字段。
+ */
+function normalizeComplianceVerdict(raw) {
+  if (!raw || typeof raw !== 'object') {
+    return null;
+  }
+  const verdict = {};
+  if (typeof raw.closureForm === 'string') {
+    verdict.closureForm = raw.closureForm;
+  }
+  if (typeof raw.compliant === 'boolean') {
+    verdict.compliant = raw.compliant;
+  }
+  if (Array.isArray(raw.missing)) {
+    verdict.missing = raw.missing.map((entry) => normalizeString(entry)).filter(Boolean);
+  }
+  if (typeof raw.degraded === 'boolean') {
+    verdict.degraded = raw.degraded;
+  }
+  if (typeof raw.blockCount === 'number' && Number.isFinite(raw.blockCount)) {
+    verdict.blockCount = raw.blockCount;
+  }
+  return Object.keys(verdict).length > 0 ? verdict : null;
+}
+
 function parseOptionalNumber(rawValue) {
   if (rawValue === undefined || rawValue === null) {
     return null;