@dommaker/harness 0.16.6 → 0.16.8

package/dist/core/constraints/checker.js

@@ -7,58 +7,20 @@
  * - Guidelines：检查失败记录警告
  * - Tips：检查失败记录提示
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ironLawChecker = exports.IronLawChecker = exports.constraintChecker = exports.ConstraintChecker = void 0;
+exports.constraintChecker = exports.ConstraintChecker = void 0;
 exports.checkConstraint = checkConstraint;
 exports.checkConstraints = checkConstraints;
 exports.checkConstraintsSafe = checkConstraintsSafe;
 exports.checkBeforeExecution = checkBeforeExecution;
-exports.checkIronLaw = checkIronLaw;
-exports.checkAllIronLaws = checkAllIronLaws;
 const constraint_1 = require("../../types/constraint");
-const traces_1 = require("../../monitoring/traces");
 const definitions_1 = require("./definitions");
-const runner_1 = require("./doc-freshness/runner");
 const exec_1 = require("../../utils/exec");
 const exec_2 = require("../../utils/exec");
-const fs_1 = require("fs");
 const path_1 = require("path");
-const yaml = __importStar(require("js-yaml"));
 const check_cache_1 = require("./check-cache");
-const detect_source_roots_1 = require("../../utils/detect-source-roots");
+const file_walk_1 = require("../../utils/file-walk");
+const checkers_1 = require("./checkers");
 /**
  * 例外名称 → ConstraintContext 中布尔字段的映射
  */
@@ -88,6 +50,7 @@ const EXCEPTION_FIELD_MAP = {
     emergency_fix: 'isEmergencyFix',
     existing_design: 'isExistingDesign',
 };
+const NOOP_TRACE_RECORDER = { record: () => undefined };
 /**
  * 约束检查器
  */
@@ -95,9 +58,41 @@ class ConstraintChecker {
     static instance;
     /** 自定义约束配置（项目级） */
     customConfig = null;
-    /** 检查结果缓存（S7：减少重复 git diff / src scan I/O，TTL=1s 防跨测试污染） */
+    /** 检查结果缓存（S7：src 扫描等重复 I/O，TTL=1s 防跨测试污染） */
     cache = new check_cache_1.CheckCache({ ttlMs: 1000 });
+    /**
+     * run 级 memo（工单 18）：一次 checkConstraints/checkConstraintsSafe 内
+     * git diff 等命令只执行一次；run 外直接调用私有检查方法时不 memo（恒新鲜）。
+     */
+    runCache = null;
+    /** trace 记录器（注入式，默认 no-op；生产入口经 setTraceRecorder 接入真实收集器） */
+    traceRecorder = NOOP_TRACE_RECORDER;
     constructor() { }
+    /**
+     * run 内 memoize；无活动 run 时直接执行（工单 18）
+     */
+    memoRun(key, fn) {
+        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）
+     */
+    getStagedDiff(projectPath) {
+        return this.memoRun(`git_diff_staged:${projectPath}`, () => (0, exec_2.runCommand)('git diff --cached', projectPath));
+    }
+    /**
+     * staged 变更文件名列表（同一次 run 内只执行一次 git 命令，工单 18）
+     */
+    getStagedDiffNames(projectPath) {
+        return this.memoRun(`git_diff_staged_names:${projectPath}`, () => (0, exec_2.runCommand)('git diff --cached --name-only', projectPath));
+    }
     /**
      * 获取单例实例
      */
@@ -107,6 +102,12 @@ class ConstraintChecker {
         }
         return ConstraintChecker.instance;
     }
+    /**
+     * 注入 trace 记录器（工单 15：解耦 core 对 monitoring 的值依赖）
+     */
+    setTraceRecorder(recorder) {
+        this.traceRecorder = recorder;
+    }
     /**
      * 设置项目级约束配置
      *
@@ -213,603 +214,23 @@ class ConstraintChecker {
         });
     }
     /**
-     * 检查约束前置条件
-     */
-    async checkPrecondition(constraint, context) {
-        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;
-        }
-    }
-    /**
-     * 检查文本中是否包含模糊词
-     */
-    checkNoFuzzyWords(text) {
-        if (!text)
-            return true; // 没有文本时默认通过（由其他检查覆盖）
-        const fuzzyPatterns = [
-            /应该没问题/,
-            /应该可以/,
-            /大概/,
-            /可能/,
-            /好像/,
-            /似乎/,
-            /差不多/,
-            /基本完成/,
-            /大部分/,
-            // audit-learned (2026-05-18): unverified completion claims
-            /我记得删[过掉]了/,
-            /之前说删了/,
-            /已删除.*但/,
-            /大部分实现/,
-            /大部分完成/,
-            /已修复.*但/,
-        ];
-        return !fuzzyPatterns.some(p => p.test(text));
-    }
-    /**
-     * 检查文本中是否包含表演性同意模式
-     */
-    checkNoPerformativePatterns(text) {
-        if (!text)
-            return true;
-        // 检查是否只有"好的/明白了"等同意词，没有后续分析
-        const performativeStart = /^(好的[，,]*\s*我[来去]做|明白了[，,]*|没问题[，,]*|ok[，,]*\s*i.?ll)/i;
-        // 如果以表演性模式开头，且总长度很短（< 50 字符），视为表演性同意
-        if (performativeStart.test(text) && text.length < 100) {
-            return false;
-        }
-        return true;
-    }
-    /**
-     * 检查文本中是否包含借口模式
-     */
-    checkNoExcusePatterns(text) {
-        if (!text)
-            return true;
-        const excusePatterns = [
-            /稍后修复/,
-            /小问题/,
-            /不影响功能/,
-            /以后再说/,
-            /先这样/,
-            /临时方案/,
-            /暂时这样/,
-        ];
-        return !excusePatterns.some(p => p.test(text));
-    }
-    /**
-     * 检查 YAGNI：过度设计信号
-     *
-     * 检查是否存在只有一个实现的 interface/abstract class。
-     * 主要由 promptInjection 驱动，这里是辅助检查。
-     */
-    async checkYagni(projectPath, changedFiles) {
-        // 无上下文时默认通过（主要由 promptInjection 驱动）
-        if (!projectPath || !changedFiles || changedFiles.length === 0)
-            return true;
-        try {
-            const path = await Promise.resolve().then(() => __importStar(require('path')));
-            const fs = await Promise.resolve().then(() => __importStar(require('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 关键词
-     */
-    async checkNoBypassCheckpoint(context) {
-        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 (!(0, fs_1.existsSync)(file))
-                continue;
-            try {
-                const content = (0, fs_1.readFileSync)(file, 'utf-8');
-                for (const pattern of bypassPatterns) {
-                    if (pattern.test(content)) {
-                        return false; // 发现 bypass 关键词
-                    }
-                }
-            }
-            catch {
-                // 文件读取失败，忽略
-            }
-        }
-        return true;
-    }
-    /**
-     * 检查 no_test_simplification：检查 git diff 是否删除了测试
-     */
-    async checkNoTestSimplification(projectPath) {
-        try {
-            // 检查是否有删除测试的 diff
-            const diff = await (0, exec_2.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 类型
-     */
-    async checkNoAnyType(projectPath, changedFiles) {
-        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 (!(0, fs_1.existsSync)(file))
-                    continue;
-                try {
-                    const content = (0, fs_1.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 是否与代码同步
+     * 检查约束前置条件（工单 21：分发至 checkers/ 注册表）
      *
-     * 两步验证：
-     *   1. Git diff 检查 — 当前变更的非测试文件是否在文档中有记录（增量检查）
-     *   2. 全量扫描 — src/ 下的所有源文件是否都在 CAPABILITIES.md 中（完整性检查）
+     * 未注册的约束默认通过（保持历史 default 分支语义）。
      */
-    async checkCapabilitySync(projectPath) {
-        try {
-            const capabilitiesPath = (0, path_1.join)(projectPath, 'CAPABILITIES.md');
-            if (!(0, fs_1.existsSync)(capabilitiesPath)) {
-                // 检查是否有代码变更，无变更则跳过
-                const diff = await (0, exec_2.runCommand)('git diff --cached --name-only', projectPath);
-                const changedCodeFiles = diff.split('\n').filter((f) => 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 (0, exec_2.runCommand)('git diff --cached --name-only', projectPath);
-            const changedCodeFiles = diff.split('\n').filter((f) => f.endsWith('.ts') || f.endsWith('.tsx') || f.endsWith('.js'));
-            if (changedCodeFiles.length > 0 && listedFiles.length > 0) {
-                const significantChanges = changedCodeFiles.filter((f) => !f.includes('__tests__') && !f.includes('.test.') && !f.includes('.spec.'));
-                if (significantChanges.length > 0) {
-                    const covered = significantChanges.some((changed) => listedFiles.some((listed) => changed.endsWith(listed) || changed.includes(listed)));
-                    if (!covered)
-                        return false;
-                }
-            }
-            // ── Step 2: 全量 src/ 扫描（T-058 修复核心）──
-            // 检查是否有 src/ 下的源文件未在 CAPABILITIES.md 中记录
-            if (listedFiles.length > 0) {
-                const sourceRoots = (0, detect_source_roots_1.detectSourceRoots)(projectPath);
-                for (const root of sourceRoots) {
-                    const srcDir = (0, path_1.join)(projectPath, root);
-                    if ((0, fs_1.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 中表格的文件路径列
-     */
-    parseCapabilitiesFiles(capabilitiesPath) {
-        try {
-            const content = (0, fs_1.readFileSync)(capabilitiesPath, 'utf-8');
-            const files = [];
-            // 匹配 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：检查简化关键词
-     */
-    async checkNoSimplificationWithoutApproval(projectPath) {
-        try {
-            const diff = await (0, exec_2.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 报告
-     */
-    async checkTestCoverage(projectPath) {
-        try {
-            // 检查 coverage 报告文件
-            const coverageJsonPath = (0, path_1.join)(projectPath, 'coverage', 'coverage-final.json');
-            const coverageSummaryPath = (0, path_1.join)(projectPath, 'coverage', 'coverage-summary.json');
-            if (!(0, fs_1.existsSync)(coverageJsonPath) && !(0, fs_1.existsSync)(coverageSummaryPath)) {
-                return true; // 无 coverage 报告，默认通过
-            }
-            // 尝试读取 coverage-summary.json
-            if ((0, fs_1.existsSync)(coverageSummaryPath)) {
-                const summary = JSON.parse((0, fs_1.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
-     */
-    async checkContextDocSync(projectPath) {
-        try {
-            const configPath = (0, path_1.join)(projectPath, '.harness', 'config.yml');
-            const configContent = (0, fs_1.readFileSync)(configPath, 'utf-8');
-            const config = yaml.load(configContent);
-            const governance = config.governance;
-            const contextFiles = governance?.context_files;
-            if (!contextFiles?.enabled || !Array.isArray(contextFiles.required_dirs)) {
-                return true; // 未配置，跳过
-            }
-            const requiredDirs = contextFiles.required_dirs;
-            for (const dir of requiredDirs) {
-                const contextPath = (0, path_1.join)(projectPath, dir, 'CONTEXT.md');
-                if (!(0, fs_1.existsSync)(contextPath)) {
-                    return false;
-                }
-            }
-            return true;
-        }
-        catch {
-            return true; // 配置不存在或解析失败，跳过
-        }
-    }
-    /**
-     * 检查 docs_freshness：CAPABILITIES.md 文件表 + 能力清单格式 + CLAUDE.md + CHANGELOG
-     *
-     * 1. 文件表格式：检查 CAPABILITIES.md 中列出的文件是否存在（防过期引用）
-     * 2. 能力清单格式：通过 FreshnessRunner 配置驱动检查计数/目录
-     * 3. 无配置时注入内置默认配置（等价旧硬编码行为）
-     */
-    async checkDocsFreshness(projectPath) {
-        // Step 1: 文件表格式 — 检查列出的文件是否还存在
-        const fileTableResult = await this.checkCapabilitiesFreshness(projectPath);
-        if (!fileTableResult)
-            return false;
-        // Step 2: 能力清单格式 + CLAUDE.md + CHANGELOG — 通过 FreshnessRunner
-        try {
-            const configPath = (0, path_1.join)(projectPath, '.harness', 'config.yml');
-            let freshnessConfig;
-            let requiredDirs;
-            if ((0, fs_1.existsSync)(configPath)) {
-                try {
-                    const raw = yaml.load((0, fs_1.readFileSync)(configPath, 'utf-8'));
-                    const governance = raw.governance;
-                    freshnessConfig = governance?.doc_freshness;
-                    const contextFiles = governance?.context_files;
-                    if (contextFiles?.enabled && Array.isArray(contextFiles.required_dirs)) {
-                        requiredDirs = contextFiles.required_dirs;
-                    }
-                }
-                catch {
-                    // 配置解析失败，使用默认
-                }
-            }
-            const runner = new runner_1.FreshnessRunner();
-            let results;
-            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 配置时使用。
-     */
-    getBuiltInDocFreshnessConfig(_requiredDirs) {
-        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/ 等）。
-     * 无表格行（能力清单格式）时跳过。
-     */
-    async checkCapabilitiesFreshness(projectPath) {
-        try {
-            const capabilitiesPath = (0, path_1.join)(projectPath, 'CAPABILITIES.md');
-            if (!(0, fs_1.existsSync)(capabilitiesPath))
-                return true;
-            const content = (0, fs_1.readFileSync)(capabilitiesPath, 'utf-8');
-            const listedFiles = [];
-            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 = (0, detect_source_roots_1.detectSourceRoots)(projectPath);
-            const fileExists = (file) => {
-                if ((0, fs_1.existsSync)((0, path_1.join)(projectPath, file)))
-                    return true;
-                for (const root of sourceRoots) {
-                    if ((0, fs_1.existsSync)((0, path_1.join)(projectPath, root, file)))
-                        return true;
-                }
-                return false;
-            };
-            for (const file of listedFiles) {
-                if (!fileExists(file))
-                    return false;
-            }
-            return true;
-        }
-        catch {
+    async checkPrecondition(constraint, context) {
+        const impl = (0, checkers_1.getConstraintCheck)(constraint.id);
+        if (!impl)
             return true;
-        }
-    }
-    /**
-     * 查找 src/ 目录中的源文件
-     */
-    findSourceFiles(dir, projectPath) {
-        const results = [];
-        let entries;
-        try {
-            entries = (0, fs_1.readdirSync)(dir);
-        }
-        catch {
-            return [];
-        }
-        for (const entry of entries) {
-            if (entry === 'node_modules' || entry === '__tests__' || entry === 'dist')
-                continue;
-            const entryPath = (0, path_1.join)(dir, entry);
-            try {
-                const stat = (0, fs_1.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((0, path_1.relative)(projectPath, entryPath));
-                }
-            }
-            catch {
-                // ignore
-            }
-        }
-        return results;
+        const projectPath = context.projectPath || process.cwd();
+        const env = {
+            context,
+            projectPath,
+            stagedDiff: () => this.getStagedDiff(projectPath),
+            stagedDiffNames: () => this.getStagedDiffNames(projectPath),
+            srcScan: (root) => this.cache.getSync(`src_scan_${root}`, projectPath, () => (0, file_walk_1.findTsSourceFiles)((0, path_1.join)(projectPath, root), { skipIndex: true }).map((f) => (0, path_1.relative)(projectPath, f))),
+        };
+        return await impl.evaluate(env);
     }
     /**
      * 查找适用于当前操作的约束
@@ -845,51 +266,59 @@ class ConstraintChecker {
      * @param customConfig 可选，per-request 自定义配置（避免多请求间的单例状态污染）
      */
     async checkConstraints(context, customConfig) {
-        const result = {
-            ironLaws: [],
-            guidelines: [],
-            tips: [],
-            passed: true,
-            warningCount: 0,
-            tipCount: 0,
-        };
-        const traceCollector = (0, traces_1.getTraceCollector)();
-        const constraints = this.getConstraints(customConfig);
-        // 1. Iron Laws: 必须全部通过
-        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;
-                throw new constraint_1.ConstraintViolationError(checkResult);
+        // run 起始：重置 run 级缓存；run 结束（含铁律提前抛出）清空（工单 18）
+        this.cache.invalidate();
+        this.runCache = new Map();
+        try {
+            const result = {
+                ironLaws: [],
+                guidelines: [],
+                tips: [],
+                passed: true,
+                warningCount: 0,
+                tipCount: 0,
+            };
+            const traceCollector = this.traceRecorder;
+            const constraints = this.getConstraints(customConfig);
+            // 1. Iron Laws: 必须全部通过
+            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;
+                    throw new constraint_1.ConstraintViolationError(checkResult);
+                }
             }
-        }
-        // 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);
-            if (!checkResult.satisfied) {
-                result.warningCount++;
+            // 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);
+                if (!checkResult.satisfied) {
+                    result.warningCount++;
+                }
             }
-        }
-        // 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);
-            if (!checkResult.satisfied) {
-                result.tipCount++;
+            // 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);
+                if (!checkResult.satisfied) {
+                    result.tipCount++;
+                }
             }
+            return result;
+        }
+        finally {
+            this.runCache = null;
         }
-        return result;
     }
     /**
      * S11: 安全全量检查 — 全部三层约束检查，不抛异常
@@ -898,44 +327,52 @@ class ConstraintChecker {
      * 调用方通过 result.passed + result.warningCount 判断状态。
      */
     async checkConstraintsSafe(context, customConfig) {
-        const result = {
-            ironLaws: [],
-            guidelines: [],
-            tips: [],
-            passed: true,
-            warningCount: 0,
-            tipCount: 0,
-        };
-        const traceCollector = (0, traces_1.getTraceCollector)();
-        const constraints = this.getConstraints(customConfig);
-        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.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++;
+        // run 起始：重置 run 级缓存（工单 18）
+        this.cache.invalidate();
+        this.runCache = new Map();
+        try {
+            const result = {
+                ironLaws: [],
+                guidelines: [],
+                tips: [],
+                passed: true,
+                warningCount: 0,
+                tipCount: 0,
+            };
+            const traceCollector = this.traceRecorder;
+            const constraints = this.getConstraints(customConfig);
+            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.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;
         }
-        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++;
+        finally {
+            this.runCache = null;
         }
-        return result;
     }
     /**
      * 执行前检查（仅检查 Iron Laws）
@@ -1007,28 +444,4 @@ async function checkBeforeExecution(context, customConfig) {
 }
 // 导出单例
 exports.constraintChecker = ConstraintChecker.getInstance();
-// ========================================
-// 向后兼容的类和函数
-// ========================================
-/**
- * @deprecated 使用 ConstraintChecker 代替
- */
-exports.IronLawChecker = ConstraintChecker;
-/**
- * @deprecated 使用 checkConstraint 代替
- */
-async function checkIronLaw(lawId, context) {
-    return checkConstraint(lawId, context);
-}
-/**
- * @deprecated 使用 checkConstraints 代替
- */
-async function checkAllIronLaws(context) {
-    const result = await checkConstraints(context);
-    return [...result.ironLaws, ...result.guidelines, ...result.tips];
-}
-/**
- * @deprecated 使用 constraintChecker 代替
- */
-exports.ironLawChecker = exports.constraintChecker;
 //# sourceMappingURL=checker.js.map