@dommaker/harness 0.16.6 → 0.16.8

package/src/core/constraints/checker.ts

@@ -17,17 +17,14 @@ import {
   ConstraintViolationError,
 } from '../../types/constraint';
 import type { ExecutionTrace } from '../../types/trace';
-import { getTraceCollector } from '../../monitoring/traces';
 import { IRON_LAWS, GUIDELINES, TIPS } from './definitions';
-import type { MergedConstraintsConfig, DocFreshnessConfig, DocFreshnessCheck } from '../../types/project-config';
-import { FreshnessRunner, type FreshnessCheckResult } from './doc-freshness/runner';
+import type { MergedConstraintsConfig } from '../../types/project-config';
 import { normalizeTriggers } from '../../utils/exec';
 import { runCommand } from '../../utils/exec';
-import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
 import { join, relative } from 'path';
-import * as yaml from 'js-yaml';
 import { CheckCache } from './check-cache';
-import { detectSourceRoots } from '../../utils/detect-source-roots';
+import { findTsSourceFiles } from '../../utils/file-walk';
+import { getConstraintCheck, type CheckEnv } from './checkers';
 
 /**
  * 例外名称 → ConstraintContext 中布尔字段的映射
@@ -59,6 +56,18 @@ const EXCEPTION_FIELD_MAP: Record<string, keyof ConstraintContext> = {
   existing_design: 'isExistingDesign',
 };
 
+/**
+ * trace 记录器最小接口（工单 15：core→monitoring 循环消除）
+ *
+ * checker 不再值导入 monitoring/traces 的单例；生产调用方经
+ * setTraceRecorder 注入真实收集器，默认 no-op。
+ */
+export interface TraceRecorder {
+  record(trace: ExecutionTrace): void;
+}
+
+const NOOP_TRACE_RECORDER: TraceRecorder = { record: () => undefined };
+
 /**
  * 约束检查器
  */
@@ -68,11 +77,51 @@ export class ConstraintChecker {
   /** 自定义约束配置（项目级） */
   private customConfig: MergedConstraintsConfig | null = null;
 
-  /** 检查结果缓存（S7：减少重复 git diff / src scan I/O，TTL=1s 防跨测试污染） */
+  /** 检查结果缓存（S7：src 扫描等重复 I/O，TTL=1s 防跨测试污染） */
   private cache: CheckCache = new CheckCache({ ttlMs: 1000 });
 
+  /**
+   * run 级 memo（工单 18）：一次 checkConstraints/checkConstraintsSafe 内
+   * git diff 等命令只执行一次；run 外直接调用私有检查方法时不 memo（恒新鲜）。
+   */
+  private runCache: Map<string, Promise<string>> | null = null;
+
+  /** trace 记录器（注入式，默认 no-op；生产入口经 setTraceRecorder 接入真实收集器） */
+  private traceRecorder: TraceRecorder = NOOP_TRACE_RECORDER;
+
   private constructor() {}
 
+  /**
+   * run 内 memoize；无活动 run 时直接执行（工单 18）
+   */
+  private memoRun(key: string, fn: () => Promise<string>): Promise<string> {
+    if (!this.runCache) return fn();
+    let pending = this.runCache.get(key);
+    if (!pending) {
+      pending = fn();
+      this.runCache.set(key, pending);
+    }
+    return pending;
+  }
+
+  /**
+   * staged 全量 diff（同一次 run 内只执行一次 git 命令，工单 18）
+   */
+  private getStagedDiff(projectPath: string): Promise<string> {
+    return this.memoRun(`git_diff_staged:${projectPath}`, () =>
+      runCommand('git diff --cached', projectPath)
+    );
+  }
+
+  /**
+   * staged 变更文件名列表（同一次 run 内只执行一次 git 命令，工单 18）
+   */
+  private getStagedDiffNames(projectPath: string): Promise<string> {
+    return this.memoRun(`git_diff_staged_names:${projectPath}`, () =>
+      runCommand('git diff --cached --name-only', projectPath)
+    );
+  }
+
   /**
    * 获取单例实例
    */
@@ -83,6 +132,13 @@ export class ConstraintChecker {
     return ConstraintChecker.instance;
   }
 
+  /**
+   * 注入 trace 记录器（工单 15：解耦 core 对 monitoring 的值依赖）
+   */
+  setTraceRecorder(recorder: TraceRecorder): void {
+    this.traceRecorder = recorder;
+  }
+
   /**
    * 设置项目级约束配置
    *
@@ -191,7 +247,7 @@ export class ConstraintChecker {
    * 记录约束检查的 trace
    */
   private recordTrace(
-    collector: ReturnType<typeof getTraceCollector>,
+    collector: TraceRecorder,
     constraint: Constraint,
     checkResult: ConstraintResult,
     context: ConstraintContext
@@ -212,679 +268,32 @@ export class ConstraintChecker {
   }
 
   /**
-   * 检查约束前置条件
+   * 检查约束前置条件（工单 21：分发至 checkers/ 注册表）
+   *
+   * 未注册的约束默认通过（保持历史 default 分支语义）。
    */
   private async checkPrecondition(
     constraint: Constraint,
     context: ConstraintContext
   ): Promise<boolean> {
-    const projectPath = context.projectPath || process.cwd();
-
-    switch (constraint.id) {
-      // Iron Laws
-      case 'no_bypass_checkpoint':
-        // 检查代码中是否有 skip/bypass 关键词
-        return await this.checkNoBypassCheckpoint(context);
-
-      case 'no_self_approval':
-        // 检查是否有测试证据
-        return context.hasTest === true;
-
-      case 'no_completion_without_verification':
-        // 检查是否有验证证据
-        return context.hasVerificationEvidence === true;
-
-      case 'no_test_simplification':
-        // 检查是否删除了测试
-        return await this.checkNoTestSimplification(projectPath);
-
-      case 'incremental_progress':
-        // 检查是否一次做多个任务（需要 context 提供信息）
-        // undefined = 未验证 → Iron Law 必须显式确认
-        return context.hasSingleTask === true;
-
-      case 'verify_external_capability':
-        // 检查是否已验证外部能力
-        // undefined = 未验证 → Iron Law 必须显式确认
-        return context.hasExternalCapabilityVerification === true;
-
-      case 'no_implementation_without_requirement_review':
-        // 检查实现后是否对比需求验证
-        return context.hasRequirementReview === true;
-
-      case 'no_implementation_without_requirement':
-        // 检查是否有需求文档
-        return context.hasRequirement === true;
-
-      case 'prefer_worktree':
-        // 检查是否在 worktree 中执行
-        return context.hasWorktree === true;
-
-      case 'no_fuzzy_completion_claim':
-        // 检查完成声明是否包含模糊词（含"我记得""之前说""大部分"等无验证模式）
-        return this.checkNoFuzzyWords(context.completionClaimText || '');
-
-      case 'no_claim_without_evidence':
-        // 检查是否提供了验证证据（test output / file check / spec AC matrix）
-        return context.hasVerificationEvidence === true ||
-               (context.taskDescription || '').includes('test') ||
-               context.hasTest === true;
-
-      case 'no_delete_without_context':
-        // 检查删除前是否审查了设计文档
-        return context.hasRequirementReview === true ||
-               context.hasRequirement === true ||
-               context.isExistingDesign === true;
-
-      case 'no_performative_agreement':
-        // 检查是否有表演性同意（主要由 promptInjection 驱动，这里做辅助检查）
-        return this.checkNoPerformativePatterns(context.taskDescription || '');
-
-      case 'two_stage_review_required':
-        // 检查是否完成两阶段审查
-        return context.hasTwoStageReview === true;
-
-      // Guidelines
-      case 'no_fix_without_root_cause':
-        // 检查是否有根本原因调查
-        return context.hasRootCauseInvestigation === true;
-
-      case 'no_code_without_test':
-        // 检查是否有失败的测试
-        return context.hasFailingTest === true;
-
-      case 'no_any_type':
-        // 检查代码中是否有 any 类型
-        return await this.checkNoAnyType(projectPath, context.changedFiles);
-
-      case 'simplest_solution_first':
-        // 检查是否已检查本地数据源
-        return context.hasReuseCheck === true;
-
-      case 'no_creation_without_reuse_check':
-        // 检查是否已进行复用检查
-        return context.hasReuseCheck === true;
-
-      case 'capability_sync':
-        // 检查 CAPABILITIES.md 是否更新
-        return await this.checkCapabilitySync(projectPath);
-
-      case 'no_simplification_without_approval':
-        // 检查是否简化了逻辑
-        return await this.checkNoSimplificationWithoutApproval(projectPath);
-
-      case 'no_skill_without_test':
-        // 检查是否有测试
-        return context.hasTest === true;
-
-      case 'test_coverage_required':
-        // 检查测试覆盖率
-        return await this.checkTestCoverage(projectPath);
-
-      case 'context_doc_sync':
-        return await this.checkContextDocSync(projectPath);
-
-      case 'docs_freshness':
-        return await this.checkDocsFreshness(projectPath);
-
-      case 'no_excuse_patterns':
-        // 检查是否使用了借口模式
-        return this.checkNoExcusePatterns(context.completionClaimText || context.taskDescription || '');
-
-      case 'yagni_check':
-        // 检查是否有过度设计（主要由 promptInjection 驱动）
-        return this.checkYagni(projectPath, context.changedFiles);
-
-      // Mnilax guidelines + first-principles (injectPrompt=true, behavior-level, always pass — post-checked)
-      case 'surgical_changes_only':
-      case 'no_model_for_deterministic':
-      case 'no_conflict_blending':
-      case 'read_before_write':
-      case 'follow_conventions':
-      case 'first_principles_first':
-      case 'fix_the_problem_not_the_gate':
-      case 'diagnosis_to_fix_gate':
-        // Guideline: behavior constraints, enforced via promptInjection + post-check
-        return true;
-
-      // Tips - 总是返回 true（仅提示）
-      case 'readme_required':
-        return true;
-
-      case 'doc_required_for_public_api':
-        return true;
-
-      default:
-        // 未知约束，默认通过
-        return true;
-    }
-  }
-
-  /**
-   * 检查文本中是否包含模糊词
-   */
-  private checkNoFuzzyWords(text: string): boolean {
-    if (!text) return true; // 没有文本时默认通过（由其他检查覆盖）
-    const fuzzyPatterns = [
-      /应该没问题/,
-      /应该可以/,
-      /大概/,
-      /可能/,
-      /好像/,
-      /似乎/,
-      /差不多/,
-      /基本完成/,
-      /大部分/,
-      // audit-learned (2026-05-18): unverified completion claims
-      /我记得删[过掉]了/,
-      /之前说删了/,
-      /已删除.*但/,
-      /大部分实现/,
-      /大部分完成/,
-      /已修复.*但/,
-    ];
-    return !fuzzyPatterns.some(p => p.test(text));
-  }
-
-  /**
-   * 检查文本中是否包含表演性同意模式
-   */
-  private checkNoPerformativePatterns(text: string): boolean {
-    if (!text) return true;
-    // 检查是否只有"好的/明白了"等同意词，没有后续分析
-    const performativeStart = /^(好的[，,]*\s*我[来去]做|明白了[，,]*|没问题[，,]*|ok[，,]*\s*i.?ll)/i;
-    // 如果以表演性模式开头，且总长度很短（< 50 字符），视为表演性同意
-    if (performativeStart.test(text) && text.length < 100) {
-      return false;
-    }
-    return true;
-  }
-
-  /**
-   * 检查文本中是否包含借口模式
-   */
-  private checkNoExcusePatterns(text: string): boolean {
-    if (!text) return true;
-    const excusePatterns = [
-      /稍后修复/,
-      /小问题/,
-      /不影响功能/,
-      /以后再说/,
-      /先这样/,
-      /临时方案/,
-      /暂时这样/,
-    ];
-    return !excusePatterns.some(p => p.test(text));
-  }
-
-  /**
-   * 检查 YAGNI：过度设计信号
-   *
-   * 检查是否存在只有一个实现的 interface/abstract class。
-   * 主要由 promptInjection 驱动，这里是辅助检查。
-   */
-  private async checkYagni(
-    projectPath?: string,
-    changedFiles?: string[]
-  ): Promise<boolean> {
-    // 无上下文时默认通过（主要由 promptInjection 驱动）
-    if (!projectPath || !changedFiles || changedFiles.length === 0) return true;
-
-    try {
-      const path = await import('path');
-      const fs = await import('fs');
-
-      for (const file of changedFiles) {
-        if (!file.endsWith('.ts') && !file.endsWith('.tsx')) continue;
-
-        const filePath = path.join(projectPath, file);
-        if (!fs.existsSync(filePath)) continue;
-
-        const content = fs.readFileSync(filePath, 'utf-8');
-
-        // 检查是否有 export interface/abstract class
-        const hasInterface = /export\s+(?:default\s+)?interface\s+(\w+)/g;
-        const hasAbstract = /export\s+(?:default\s+)?abstract\s+class\s+(\w+)/g;
-
-        const interfaces = [...content.matchAll(hasInterface)].map(m => m[1]);
-        const abstracts = [...content.matchAll(hasAbstract)].map(m => m[1]);
-
-        const exportedTypes = [...interfaces, ...abstracts];
-
-        for (const typeName of exportedTypes) {
-          // 检查同一个 typeName 的 implements/extends 出现次数
-          const implPattern = new RegExp(`(?:implements|extends)\\s+${typeName}\\b`, 'g');
-          // 在整个项目中搜索（简化版：只在 changedFiles 中搜索）
-          let implCount = 0;
-          for (const f of changedFiles) {
-            if (!f.endsWith('.ts') && !f.endsWith('.tsx')) continue;
-            const fp = path.join(projectPath, f);
-            if (!fs.existsSync(fp)) continue;
-            const fc = fs.readFileSync(fp, 'utf-8');
-            const matches = fc.match(implPattern);
-            if (matches) implCount += matches.length;
-          }
-
-          // 只有一个实现者 → YAGNI 违规
-          if (implCount <= 1) {
-            return false;
-          }
-        }
-      }
-    } catch {
-      // 文件读取失败，默认通过
-      return true;
-    }
-
-    return true;
-  }
-
-  /**
-   * 检查 no_bypass_checkpoint：检查代码中是否有 skip/bypass 关键词
-   */
-  private async checkNoBypassCheckpoint(context: ConstraintContext): Promise<boolean> {
-    const changedFiles = context.changedFiles || [];
-    
-    if (changedFiles.length === 0) {
-      return true; // 无变更文件，默认通过
-    }
-
-    // 检查文件内容是否有 skip/bypass 关键词
-    const bypassPatterns = [
-      /\.skip\(/,          // Jest/Vitest skip
-      /\.bypass\s*=/,      // bypass flag
-      /skip:\s*true/,      // skip option
-      /bypass\s*checkpoint/, // explicit bypass
-      /\/\/\s*skip/,       // comment skip
-    ];
-
-    for (const file of changedFiles) {
-      if (!existsSync(file)) continue;
-      try {
-        const content = readFileSync(file, 'utf-8');
-        for (const pattern of bypassPatterns) {
-          if (pattern.test(content)) {
-            return false; // 发现 bypass 关键词
-          }
-        }
-      } catch {
-        // 文件读取失败，忽略
-      }
-    }
-
-    return true;
-  }
-
-  /**
-   * 检查 no_test_simplification：检查 git diff 是否删除了测试
-   */
-  private async checkNoTestSimplification(projectPath: string): Promise<boolean> {
-    try {
-      // 检查是否有删除测试的 diff
-      const diff = await runCommand('git diff --cached', projectPath);
-      
-      // 检查是否删除了测试行
-      const deletedTestPatterns = [
-        /^-\s*(test|it|describe)\s*\(/,  // 删除 test/it/describe
-        /^-\s*expect\s*\(/,               // 删除 expect
-        /^-\s*\/\/\s*test/,               // 删除注释的 test
-      ];
-
-      for (const pattern of deletedTestPatterns) {
-        if (pattern.test(diff)) {
-          return false; // 发现删除测试
-        }
-      }
-
-      return true;
-    } catch {
-      return true; // git 命令失败，默认通过
-    }
-  }
-
-  /**
-   * 检查 no_any_type：grep any 类型
-   */
-  private async checkNoAnyType(projectPath: string, changedFiles?: string[]): Promise<boolean> {
-    try {
-      const filesToCheck = changedFiles && changedFiles.length > 0
-        ? changedFiles.filter(f => f.endsWith('.ts') || f.endsWith('.tsx'))
-        : [];
-
-      if (filesToCheck.length === 0) {
-        return true; // 无 TS 文件变更
-      }
-
-      // 检查是否有 : any 类型
-      for (const file of filesToCheck) {
-        if (!existsSync(file)) continue;
-        try {
-          const content = readFileSync(file, 'utf-8');
-          // 检查 : any（排除注释和字符串）
-          const lines = content.split('\n');
-          for (const line of lines) {
-            // 跳过注释和字符串
-            if (line.trim().startsWith('//') || line.trim().startsWith('*')) continue;
-            if (line.includes(': any') && !line.includes('// ') && !line.includes('/*')) {
-              return false; // 发现 any 类型
-            }
-          }
-        } catch {
-          // 文件读取失败，忽略
-        }
-      }
-
-      return true;
-    } catch {
-      return true; // 检查失败，默认通过
-    }
-  }
-
-  /**
-   * 检查 capability_sync：检查 CAPABILITIES.md 是否与代码同步
-   *
-   * 两步验证：
-   *   1. Git diff 检查 — 当前变更的非测试文件是否在文档中有记录（增量检查）
-   *   2. 全量扫描 — src/ 下的所有源文件是否都在 CAPABILITIES.md 中（完整性检查）
-   */
-  private async checkCapabilitySync(projectPath: string): Promise<boolean> {
-    try {
-      const capabilitiesPath = join(projectPath, 'CAPABILITIES.md');
-      if (!existsSync(capabilitiesPath)) {
-        // 检查是否有代码变更，无变更则跳过
-        const diff = await runCommand('git diff --cached --name-only', projectPath);
-        const changedCodeFiles = diff.split('\n').filter(
-          (f: string) => f.endsWith('.ts') || f.endsWith('.tsx') || f.endsWith('.js')
-        );
-        return changedCodeFiles.length === 0;
-      }
-
-      const listedFiles = this.parseCapabilitiesFiles(capabilitiesPath);
-
-      // ── Step 1: Git diff 增量检查 ──
-      const diff = await runCommand('git diff --cached --name-only', projectPath);
-      const changedCodeFiles = diff.split('\n').filter(
-        (f: string) => f.endsWith('.ts') || f.endsWith('.tsx') || f.endsWith('.js')
-      );
-
-      if (changedCodeFiles.length > 0 && listedFiles.length > 0) {
-        const significantChanges = changedCodeFiles.filter(
-          (f: string) => !f.includes('__tests__') && !f.includes('.test.') && !f.includes('.spec.')
-        );
-
-        if (significantChanges.length > 0) {
-          const covered = significantChanges.some((changed: string) =>
-            listedFiles.some((listed: string) => changed.endsWith(listed) || changed.includes(listed))
-          );
-          if (!covered) return false;
-        }
-      }
+    const impl = getConstraintCheck(constraint.id);
+    if (!impl) return true;
 
-      // ── Step 2: 全量 src/ 扫描（T-058 修复核心）──
-      // 检查是否有 src/ 下的源文件未在 CAPABILITIES.md 中记录
-      if (listedFiles.length > 0) {
-        const sourceRoots = detectSourceRoots(projectPath);
-        for (const root of sourceRoots) {
-          const srcDir = join(projectPath, root);
-          if (existsSync(srcDir)) {
-            const actualFiles = this.cache.getSync(`src_scan_${root}`, projectPath, () =>
-              this.findSourceFiles(srcDir, projectPath)
-            );
-            for (const file of actualFiles) {
-              if (!listedFiles.includes(file)) {
-                return false;
-              }
-            }
-          }
-        }
-      }
-
-      return true;
-    } catch {
-      return true; // 检查失败，默认通过
-    }
-  }
-
-  /**
-   * 解析 CAPABILITIES.md 中表格的文件路径列
-   */
-  private parseCapabilitiesFiles(capabilitiesPath: string): string[] {
-    try {
-      const content = readFileSync(capabilitiesPath, 'utf-8');
-      const files: string[] = [];
-
-      // 匹配 markdown 表格行中的 .ts/.tsx/.js/.jsx 文件路径（第二列）
-      const tableRowRegex = /^\|[^|]+\|\s*([^|]+?\.(?:ts|tsx|js|jsx))\s*\|/gm;
-      let match;
-      while ((match = tableRowRegex.exec(content)) !== null) {
-        files.push(match[1].trim());
-      }
-
-      return files;
-    } catch {
-      return [];
-    }
-  }
-
-  /**
-   * 检查 no_simplification_without_approval：检查简化关键词
-   */
-  private async checkNoSimplificationWithoutApproval(projectPath: string): Promise<boolean> {
-    try {
-      const diff = await runCommand('git diff --cached', projectPath);
-
-      // 检查是否有简化关键词
-      const simplificationPatterns = [
-        /removed\s*test/i,
-        /simplified\s*logic/i,
-        /removed\s*validation/i,
-        /skip\s*check/i,
-      ];
-
-      for (const pattern of simplificationPatterns) {
-        if (pattern.test(diff)) {
-          return false; // 发现简化关键词
-        }
-      }
-
-      return true;
-    } catch {
-      return true; // 检查失败，默认通过
-    }
-  }
-
-  /**
-   * 检查 test_coverage_required：读取 coverage 报告
-   */
-  private async checkTestCoverage(projectPath: string): Promise<boolean> {
-    try {
-      // 检查 coverage 报告文件
-      const coverageJsonPath = join(projectPath, 'coverage', 'coverage-final.json');
-      const coverageSummaryPath = join(projectPath, 'coverage', 'coverage-summary.json');
-
-      if (!existsSync(coverageJsonPath) && !existsSync(coverageSummaryPath)) {
-        return true; // 无 coverage 报告，默认通过
-      }
-
-      // 尝试读取 coverage-summary.json
-      if (existsSync(coverageSummaryPath)) {
-        const summary = JSON.parse(readFileSync(coverageSummaryPath, 'utf-8'));
-        const total = summary.total || {};
-        const linesCoverage = total.lines?.pct || 0;
-        
-        // 默认要求 50% 覆盖率（可配置）
-        return linesCoverage >= 50;
-      }
-
-      return true;
-    } catch {
-      return true; // 检查失败，默认通过
-    }
-  }
-
-  /**
-   * 检查 context_doc_sync：关键目录是否有 CONTEXT.md
-   */
-  private async checkContextDocSync(projectPath: string): Promise<boolean> {
-    try {
-      const configPath = join(projectPath, '.harness', 'config.yml');
-      const configContent = readFileSync(configPath, 'utf-8');
-      const config = yaml.load(configContent) as Record<string, unknown>;
-      const governance = config.governance as Record<string, unknown> | undefined;
-      const contextFiles = governance?.context_files as Record<string, unknown> | undefined;
-
-      if (!contextFiles?.enabled || !Array.isArray(contextFiles.required_dirs)) {
-        return true; // 未配置，跳过
-      }
-
-      const requiredDirs = contextFiles.required_dirs as string[];
-      for (const dir of requiredDirs) {
-        const contextPath = join(projectPath, dir, 'CONTEXT.md');
-        if (!existsSync(contextPath)) {
-          return false;
-        }
-      }
-
-      return true;
-    } catch {
-      return true; // 配置不存在或解析失败，跳过
-    }
-  }
-
-  /**
-   * 检查 docs_freshness：CAPABILITIES.md 文件表 + 能力清单格式 + CLAUDE.md + CHANGELOG
-   *
-   * 1. 文件表格式：检查 CAPABILITIES.md 中列出的文件是否存在（防过期引用）
-   * 2. 能力清单格式：通过 FreshnessRunner 配置驱动检查计数/目录
-   * 3. 无配置时注入内置默认配置（等价旧硬编码行为）
-   */
-  private async checkDocsFreshness(projectPath: string): Promise<boolean> {
-    // Step 1: 文件表格式 — 检查列出的文件是否还存在
-    const fileTableResult = await this.checkCapabilitiesFreshness(projectPath);
-    if (!fileTableResult) return false;
-
-    // Step 2: 能力清单格式 + CLAUDE.md + CHANGELOG — 通过 FreshnessRunner
-    try {
-      const configPath = join(projectPath, '.harness', 'config.yml');
-      let freshnessConfig: DocFreshnessConfig | undefined;
-      let requiredDirs: string[] | undefined;
-
-      if (existsSync(configPath)) {
-        try {
-          const raw = yaml.load(readFileSync(configPath, 'utf-8')) as Record<string, unknown>;
-          const governance = raw.governance as Record<string, unknown> | undefined;
-          freshnessConfig = governance?.doc_freshness as DocFreshnessConfig | undefined;
-
-          const contextFiles = governance?.context_files as Record<string, unknown> | undefined;
-          if (contextFiles?.enabled && Array.isArray(contextFiles.required_dirs)) {
-            requiredDirs = contextFiles.required_dirs as string[];
-          }
-        } catch {
-          // 配置解析失败，使用默认
-        }
-      }
-
-      const runner = new FreshnessRunner();
-      let results: FreshnessCheckResult[];
-
-      if (freshnessConfig?.checks && freshnessConfig.checks.length > 0) {
-        results = runner.runAll(freshnessConfig, projectPath, { requiredDirs });
-      } else {
-        const builtIn = this.getBuiltInDocFreshnessConfig(requiredDirs);
-        results = runner.runAll({ checks: builtIn }, projectPath, { requiredDirs });
-      }
-
-      if (!results.every(r => r.pass)) return false;
-    } catch {
-      // FreshnessRunner 失败不影响整体
-    }
-
-    return true;
-  }
-
-  /**
-   * 获取内置默认文档新鲜度检查配置
-   *
-   * 等价旧硬编码的 checkCapabilitiesFreshness + checkClaudeMdFreshness 行为。
-   * 仅当项目未提供 governance.doc_freshness 配置时使用。
-   */
-  private getBuiltInDocFreshnessConfig(_requiredDirs?: string[]): DocFreshnessCheck[] {
-    return [
-      // CONTEXT.md 存在性 — key directories must have CONTEXT.md
-      { type: 'context_docs' },
-      // CHANGELOG 版本 vs package.json 版本 — prevents version drift
-      { type: 'changelog_version' },
-    ];
-  }
-
-  /**
-   * 检查 CAPABILITIES.md 是否与源码同步（文件表格式）
-   *
-   * 检查 CAPABILITIES.md 中列出的文件路径是否仍然存在于磁盘上（防过期引用）。
-   * 多根查找：支持不同项目的源码根（harness=src/, studio=apps/api/src/ 等）。
-   * 无表格行（能力清单格式）时跳过。
-   */
-  private async checkCapabilitiesFreshness(projectPath: string): Promise<boolean> {
-    try {
-      const capabilitiesPath = join(projectPath, 'CAPABILITIES.md');
-      if (!existsSync(capabilitiesPath)) return true;
-      const content = readFileSync(capabilitiesPath, 'utf-8');
-
-      const listedFiles: string[] = [];
-      const tableRowRegex = /^\|[^|]+\|\s*([^|]+?\.(?:ts|tsx|js|jsx))\s*\|/gm;
-      let match;
-      while ((match = tableRowRegex.exec(content)) !== null) {
-        listedFiles.push(match[1].trim());
-      }
-
-      if (listedFiles.length === 0) return true;
-
-      const sourceRoots = detectSourceRoots(projectPath);
-      const fileExists = (file: string): boolean => {
-        if (existsSync(join(projectPath, file))) return true;
-        for (const root of sourceRoots) {
-          if (existsSync(join(projectPath, root, file))) return true;
-        }
-        return false;
-      };
-
-      for (const file of listedFiles) {
-        if (!fileExists(file)) return false;
-      }
-
-      return true;
-    } catch {
-      return true;
-    }
-  }
-
-  /**
-   * 查找 src/ 目录中的源文件
-   */
-  private findSourceFiles(dir: string, projectPath: string): string[] {
-    const results: string[] = [];
-    let entries: string[];
-    try {
-      entries = readdirSync(dir);
-    } catch {
-      return [];
-    }
+    const projectPath = context.projectPath || process.cwd();
+    const env: CheckEnv = {
+      context,
+      projectPath,
+      stagedDiff: () => this.getStagedDiff(projectPath),
+      stagedDiffNames: () => this.getStagedDiffNames(projectPath),
+      srcScan: (root: string) =>
+        this.cache.getSync(`src_scan_${root}`, projectPath, () =>
+          findTsSourceFiles(join(projectPath, root), { skipIndex: true }).map((f) =>
+            relative(projectPath, f)
+          )
+        ),
+    };
 
-    for (const entry of entries) {
-      if (entry === 'node_modules' || entry === '__tests__' || entry === 'dist') continue;
-      const entryPath = join(dir, entry);
-      try {
-        const stat = statSync(entryPath);
-        if (stat.isDirectory()) {
-          results.push(...this.findSourceFiles(entryPath, projectPath));
-        } else if (entry.endsWith('.ts') && !entry.endsWith('.d.ts') && entry !== 'index.ts') {
-          results.push(relative(projectPath, entryPath));
-        }
-      } catch {
-        // ignore
-      }
-    }
-    return results;
+    return await impl.evaluate(env);
   }
 
   /**
@@ -934,59 +343,67 @@ export class ConstraintChecker {
     context: ConstraintContext,
     customConfig?: MergedConstraintsConfig | null
   ): Promise<ConstraintCheckResult> {
-    const result: ConstraintCheckResult = {
-      ironLaws: [],
-      guidelines: [],
-      tips: [],
-      passed: true,
-      warningCount: 0,
-      tipCount: 0,
-    };
+    // run 起始：重置 run 级缓存；run 结束（含铁律提前抛出）清空（工单 18）
+    this.cache.invalidate();
+    this.runCache = new Map();
 
-    const traceCollector = getTraceCollector();
-    const constraints = this.getConstraints(customConfig);
+    try {
+      const result: ConstraintCheckResult = {
+        ironLaws: [],
+        guidelines: [],
+        tips: [],
+        passed: true,
+        warningCount: 0,
+        tipCount: 0,
+      };
 
-    // 1. Iron Laws: 必须全部通过
-    for (const constraint of Object.values(constraints.ironLaws)) {
-      if (!this.matchesTrigger(constraint, context.operation)) continue;
+      const traceCollector = this.traceRecorder;
+      const constraints = this.getConstraints(customConfig);
 
-      const checkResult = await this.check(constraint, context);
-      result.ironLaws.push(checkResult);
-      this.recordTrace(traceCollector, constraint, checkResult, context);
+      // 1. Iron Laws: 必须全部通过
+      for (const constraint of Object.values(constraints.ironLaws)) {
+        if (!this.matchesTrigger(constraint, context.operation)) continue;
 
-      if (!checkResult.satisfied) {
-        result.passed = false;
-        throw new ConstraintViolationError(checkResult);
+        const checkResult = await this.check(constraint, context);
+        result.ironLaws.push(checkResult);
+        this.recordTrace(traceCollector, constraint, checkResult, context);
+
+        if (!checkResult.satisfied) {
+          result.passed = false;
+          throw new ConstraintViolationError(checkResult);
+        }
       }
-    }
 
-    // 2. Guidelines: 记录警告
-    for (const constraint of Object.values(constraints.guidelines)) {
-      if (!this.matchesTrigger(constraint, context.operation)) continue;
+      // 2. Guidelines: 记录警告
+      for (const constraint of Object.values(constraints.guidelines)) {
+        if (!this.matchesTrigger(constraint, context.operation)) continue;
 
-      const checkResult = await this.check(constraint, context);
-      result.guidelines.push(checkResult);
-      this.recordTrace(traceCollector, constraint, checkResult, context);
+        const checkResult = await this.check(constraint, context);
+        result.guidelines.push(checkResult);
+        this.recordTrace(traceCollector, constraint, checkResult, context);
 
-      if (!checkResult.satisfied) {
-        result.warningCount++;
+        if (!checkResult.satisfied) {
+          result.warningCount++;
+        }
       }
-    }
 
-    // 3. Tips: 仅记录
-    for (const constraint of Object.values(constraints.tips)) {
-      if (!this.matchesTrigger(constraint, context.operation)) continue;
+      // 3. Tips: 仅记录
+      for (const constraint of Object.values(constraints.tips)) {
+        if (!this.matchesTrigger(constraint, context.operation)) continue;
 
-      const checkResult = await this.check(constraint, context);
-      result.tips.push(checkResult);
-      this.recordTrace(traceCollector, constraint, checkResult, context);
+        const checkResult = await this.check(constraint, context);
+        result.tips.push(checkResult);
+        this.recordTrace(traceCollector, constraint, checkResult, context);
 
-      if (!checkResult.satisfied) {
-        result.tipCount++;
+        if (!checkResult.satisfied) {
+          result.tipCount++;
+        }
       }
-    }
 
-    return result;
+      return result;
+    } finally {
+      this.runCache = null;
+    }
   }
 
   /**
@@ -999,43 +416,51 @@ export class ConstraintChecker {
     context: ConstraintContext,
     customConfig?: MergedConstraintsConfig | null
   ): Promise<ConstraintCheckResult> {
-    const result: ConstraintCheckResult = {
-      ironLaws: [],
-      guidelines: [],
-      tips: [],
-      passed: true,
-      warningCount: 0,
-      tipCount: 0,
-    };
+    // run 起始：重置 run 级缓存（工单 18）
+    this.cache.invalidate();
+    this.runCache = new Map();
 
-    const traceCollector = getTraceCollector();
-    const constraints = this.getConstraints(customConfig);
+    try {
+      const result: ConstraintCheckResult = {
+        ironLaws: [],
+        guidelines: [],
+        tips: [],
+        passed: true,
+        warningCount: 0,
+        tipCount: 0,
+      };
 
-    for (const constraint of Object.values(constraints.ironLaws)) {
-      if (!this.matchesTrigger(constraint, context.operation)) continue;
-      const checkResult = await this.check(constraint, context);
-      result.ironLaws.push(checkResult);
-      this.recordTrace(traceCollector, constraint, checkResult, context);
-      if (!checkResult.satisfied) result.passed = false;
-    }
+      const traceCollector = this.traceRecorder;
+      const constraints = this.getConstraints(customConfig);
 
-    for (const constraint of Object.values(constraints.guidelines)) {
-      if (!this.matchesTrigger(constraint, context.operation)) continue;
-      const checkResult = await this.check(constraint, context);
-      result.guidelines.push(checkResult);
-      this.recordTrace(traceCollector, constraint, checkResult, context);
-      if (!checkResult.satisfied) result.warningCount++;
-    }
+      for (const constraint of Object.values(constraints.ironLaws)) {
+        if (!this.matchesTrigger(constraint, context.operation)) continue;
+        const checkResult = await this.check(constraint, context);
+        result.ironLaws.push(checkResult);
+        this.recordTrace(traceCollector, constraint, checkResult, context);
+        if (!checkResult.satisfied) result.passed = false;
+      }
 
-    for (const constraint of Object.values(constraints.tips)) {
-      if (!this.matchesTrigger(constraint, context.operation)) continue;
-      const checkResult = await this.check(constraint, context);
-      result.tips.push(checkResult);
-      this.recordTrace(traceCollector, constraint, checkResult, context);
-      if (!checkResult.satisfied) result.tipCount++;
-    }
+      for (const constraint of Object.values(constraints.guidelines)) {
+        if (!this.matchesTrigger(constraint, context.operation)) continue;
+        const checkResult = await this.check(constraint, context);
+        result.guidelines.push(checkResult);
+        this.recordTrace(traceCollector, constraint, checkResult, context);
+        if (!checkResult.satisfied) result.warningCount++;
+      }
+
+      for (const constraint of Object.values(constraints.tips)) {
+        if (!this.matchesTrigger(constraint, context.operation)) continue;
+        const checkResult = await this.check(constraint, context);
+        result.tips.push(checkResult);
+        this.recordTrace(traceCollector, constraint, checkResult, context);
+        if (!checkResult.satisfied) result.tipCount++;
+      }
 
-    return result;
+      return result;
+    } finally {
+      this.runCache = null;
+    }
   }
 
   /**
@@ -1133,37 +558,3 @@ export async function checkBeforeExecution(
 
 // 导出单例
 export const constraintChecker = ConstraintChecker.getInstance();
-
-// ========================================
-// 向后兼容的类和函数
-// ========================================
-
-/**
- * @deprecated 使用 ConstraintChecker 代替
- */
-export const IronLawChecker = ConstraintChecker;
-
-/**
- * @deprecated 使用 checkConstraint 代替
- */
-export async function checkIronLaw(
-  lawId: string,
-  context: ConstraintContext
-): Promise<ConstraintResult> {
-  return checkConstraint(lawId, context);
-}
-
-/**
- * @deprecated 使用 checkConstraints 代替
- */
-export async function checkAllIronLaws(
-  context: ConstraintContext
-): Promise<ConstraintResult[]> {
-  const result = await checkConstraints(context);
-  return [...result.ironLaws, ...result.guidelines, ...result.tips];
-}
-
-/**
- * @deprecated 使用 constraintChecker 代替
- */
-export const ironLawChecker = constraintChecker;