@dommaker/harness 1.2.3 → 1.4.0

package/src/core/constraints/capabilities-parser.ts

@@ -5,26 +5,18 @@
  * 各持一份正则，收敛到此处。H2 起能力清单计数（checkCapabilityCounts /
  * updateCapabilityCounts）也从 sync-docs/capabilities-syncer 收敛到此，
  * 使本模块成为 CAPABILITIES.md 解析 + 计数唯一入口。
+ *
+ * 计数所需的命令/门禁定义由调用方注入（harness#88：core 不值导入上层定义表）。
  */
 
 import * as fs from 'fs';
 import { IRON_LAWS, GUIDELINES } from './definitions';
-import { COMMAND_DEFINITIONS } from '../../cli/commands/definitions';
-import { GATE_DEFINITIONS } from '../../gates/definitions';
 import { FreshnessRunner } from './doc-freshness/runner';
 import type { DocFreshnessCheck } from '../../types/project-config';
 
-/** CLI 命令数 = 非门禁命令定义 + 门禁命令定义（ADR-0002：定义表是命令形状单一来源） */
-function cliCommandCount(): number {
-  return COMMAND_DEFINITIONS.length + GATE_DEFINITIONS.filter(g => g.cli).length;
-}
-
 /** 匹配表格单元格中的源码文件条目（如 `src/foo.ts`、`foo.tsx`） */
 const FILE_CELL_REGEX = /\|\s*([^|]+?\.(?:ts|tsx|js|jsx))\s*\|/g;
 
-/** 仅匹配表格第二列的文件条目（checker 的历史语义：第一列为模块名，第二列为文件） */
-const FILE_SECOND_COLUMN_REGEX = /^\|[^|]+\|\s*([^|]+?\.(?:ts|tsx|js|jsx))\s*\|/gm;
-
 /**
  * 匹配表格单元格中的目录条目（如 `agents/`）。
  *
@@ -35,26 +27,25 @@ const FILE_SECOND_COLUMN_REGEX = /^\|[^|]+\|\s*([^|]+?\.(?:ts|tsx|js|jsx))\s*\|/
 const DIR_CELL_REGEX = /\|\s*([\w][\w@./-]*\/)\s*\|/g;
 
 export interface CapabilitiesParseOptions {
-  /** 是否同时收集目录条目（sync-docs 需要；checker 只做文件覆盖比对，不需要） */
+  /** 是否同时收集目录条目，默认 false */
   includeDirs?: boolean;
-  /** 只取表格第二列的文件条目（checker 的历史严格语义），默认 false */
-  secondColumnOnly?: boolean;
 }
 
 /**
  * 从 CAPABILITIES.md 内容中提取表格列出的条目
  *
+ * 解析口径（ADR-0009）：表格所有单元格收集；「只看第二列」的历史读法废弃。
+ *
  * @param content markdown 内容
  * @returns 文件路径原样 + （可选）目录条目，按出现顺序去重
  */
 export function parseCapabilitiesEntries(content: string, options: CapabilitiesParseOptions = {}): string[] {
-  const { includeDirs = false, secondColumnOnly = false } = options;
+  const { includeDirs = false } = options;
   const entries: string[] = [];
 
-  const fileRegex = secondColumnOnly ? FILE_SECOND_COLUMN_REGEX : FILE_CELL_REGEX;
   let match: RegExpExecArray | null;
-  fileRegex.lastIndex = 0;
-  while ((match = fileRegex.exec(content)) !== null) {
+  FILE_CELL_REGEX.lastIndex = 0;
+  while ((match = FILE_CELL_REGEX.exec(content)) !== null) {
     const raw = match[1].trim();
     if (!entries.includes(raw)) entries.push(raw);
   }
@@ -111,6 +102,20 @@ export function aggregateToSourceSubdir(root: string, file: string): string {
 
 // ── 能力清单计数 ────────────────────────────────────────────
 
+/**
+ * 调用方注入的定义源（harness#88）
+ *
+ * core 只消费计数所需的最小形状，不 require 命令表：
+ * - commands：非门禁 CLI 命令定义（仅取长度）
+ * - gates：门禁定义（仅取长度与「是否带 cli 元数据」）
+ *
+ * ADR-0002「定义表是命令形状单一来源」不变，只是表的引用方从 core 移到 cli。
+ */
+export interface CapabilityDefinitionSource {
+  commands: readonly unknown[];
+  gates: readonly { cli?: unknown }[];
+}
+
 /**
  * 能力清单统计规则单份定义（ADR-0008：check/write 两方向共用，
  * 此前 label+pattern 在 buildCapabilityChecks 与 updateCapabilityCounts 各写一遍）
@@ -119,31 +124,40 @@ export function aggregateToSourceSubdir(root: string, file: string): string {
  *   write 的替换文本前缀，如 `Quality Gates (6)`）
  * - pattern：同时供 check（doc_regex_count 字符串 pattern，捕获组为文档计数）
  *   与 write（编译为替换 regex）
- * - actual：定义表实际计数（ADR-0002 单一来源）
+ * - actual：实际计数——命令/门禁来自注入源，约束来自 core 自身定义表
  */
 interface CapabilityCountRule {
   label: string;
   pattern: string;
-  actual: () => number;
+  actual: number;
 }
 
-const CAPABILITY_COUNT_RULES: CapabilityCountRule[] = [
-  { label: 'CLI Commands', pattern: 'CLI Commands\\s*\\((\\d+)\\)', actual: cliCommandCount },
-  { label: 'Quality Gates', pattern: 'Quality Gates?\\s*\\((\\d+)\\)', actual: () => GATE_DEFINITIONS.length },
-  { label: 'Iron Laws', pattern: 'Iron Laws?\\s*\\((\\d+)\\)', actual: () => Object.keys(IRON_LAWS).length },
-  { label: 'Guidelines', pattern: 'Guidelines?\\s*\\((\\d+)\\)', actual: () => Object.keys(GUIDELINES).length },
-];
+/**
+ * 能力清单统计规则（CLI Commands 计数 = 非门禁命令数 + 带 cli 元数据的门禁数）
+ */
+function capabilityCountRules(source: CapabilityDefinitionSource): CapabilityCountRule[] {
+  return [
+    {
+      label: 'CLI Commands',
+      pattern: 'CLI Commands\\s*\\((\\d+)\\)',
+      actual: source.commands.length + source.gates.filter(g => g.cli).length,
+    },
+    { label: 'Quality Gates', pattern: 'Quality Gates?\\s*\\((\\d+)\\)', actual: source.gates.length },
+    { label: 'Iron Laws', pattern: 'Iron Laws?\\s*\\((\\d+)\\)', actual: Object.keys(IRON_LAWS).length },
+    { label: 'Guidelines', pattern: 'Guidelines?\\s*\\((\\d+)\\)', actual: Object.keys(GUIDELINES).length },
+  ];
+}
 
 /**
  * 构建 CAPABILITIES.md 能力清单格式的检查配置
  */
-function buildCapabilityChecks(): DocFreshnessCheck[] {
-  return CAPABILITY_COUNT_RULES.map(rule => ({
+function buildCapabilityChecks(source: CapabilityDefinitionSource): DocFreshnessCheck[] {
+  return capabilityCountRules(source).map(rule => ({
     type: 'doc_regex_count' as const,
     doc: 'CAPABILITIES.md',
     label: rule.label,
     pattern: rule.pattern,
-    actual: { kind: 'const_count' as const, value: rule.actual() },
+    actual: { kind: 'const_count' as const, value: rule.actual },
   }));
 }
 
@@ -151,10 +165,11 @@ function buildCapabilityChecks(): DocFreshnessCheck[] {
  * 使用 FreshnessRunner 检查能力清单计数是否与代码一致（--check 模式）
  */
 export function checkCapabilityCounts(
-  projectPath: string
+  projectPath: string,
+  source: CapabilityDefinitionSource
 ): { match: boolean; mismatches: string[] } {
   const runner = new FreshnessRunner();
-  const checks = buildCapabilityChecks();
+  const checks = buildCapabilityChecks(source);
   const results = runner.runAll({ checks }, projectPath);
 
   const mismatches: string[] = [];
@@ -170,14 +185,17 @@ export function checkCapabilityCounts(
 /**
  * 更新 CAPABILITIES.md 中的能力清单计数（write 模式）
  *
- * 命令/门禁计数取自定义表（ADR-0002 单一来源），regex 替换文档计数行；
- * 规则与 check 方向共用 CAPABILITY_COUNT_RULES（ADR-0008）。
+ * 命令/门禁计数取自注入的定义源（ADR-0002 单一来源在调用方），regex 替换文档计数行；
+ * 规则与 check 方向共用 capabilityCountRules（ADR-0008）。
  */
-export function updateCapabilityCounts(content: string, _projectPath: string): string {
-  for (const rule of CAPABILITY_COUNT_RULES) {
+export function updateCapabilityCounts(
+  content: string,
+  source: CapabilityDefinitionSource
+): string {
+  for (const rule of capabilityCountRules(source)) {
     const regex = new RegExp(rule.pattern);
     if (regex.test(content)) {
-      content = content.replace(regex, `${rule.label} (${rule.actual()})`);
+      content = content.replace(regex, `${rule.label} (${rule.actual})`);
     }
   }
 

package/src/core/constraints/capabilities-reconcile.ts

@@ -0,0 +1,166 @@
+/**
+ * CAPABILITIES.md 声明与代码实况的对照判定（ADR-0009）
+ *
+ * 纯判定 module：吃「文档内容 + 实际文件清单（+ 增量清单）」，一次产出全部判定结果；
+ * 不做任何 fs/git IO（存在性可选注入）。此前同一套覆盖/幽灵规则在
+ * capability_sync / docs_freshness / sync-docs 三处独立实现，靠「同规则」注释人工同步，
+ * 同一 bug（basename 碰撞、后缀误配）在多处各修一遍——此处为唯一真相源。
+ *
+ * 方向：
+ *   代码→文档  uncoveredChanges / uncoveredFiles / uncoveredDirs（漏登记）
+ *   文档→代码  deadEntries（幽灵：文档登记的路径既不在代码实况中、文件系统中也不存在）
+ *
+ * 解析口径（ADR-0009）：表格所有单元格收集，文件条目与目录条目都参与覆盖；
+ * 「只看第二列」的历史读法废弃。幽灵判定同样覆盖文件与目录条目（口径从严）。
+ * mode=module / file 的差异不在判定层，而是调用方取哪份输出形状：
+ * module 读 uncoveredDirs（目录聚合），file 读 uncoveredFiles（逐文件）。
+ */
+
+import { join, relative } from 'path';
+import {
+  aggregateToSourceSubdir,
+  isCapabilityListingFormat,
+  parseCapabilitiesEntries,
+} from './capabilities-parser';
+import { findTsSourceFiles } from '../../utils/file-walk';
+
+/** markdown 表格分隔行（|------|------|）：区分「无表格的散文文档」与「有表格但零条目」 */
+const TABLE_SEPARATOR_REGEX = /^\s*\|[\s:|-]+\|\s*$/m;
+
+export interface ReconcileInput {
+  /** CAPABILITIES.md 内容 */
+  content: string;
+  /** 代码实况全集：项目相对路径的源文件清单（由调用方收集，见 collectSourceFiles） */
+  populationFiles: string[];
+  /** 增量变更文件（项目相对路径）；无 git 概念的消费方传空/不传 */
+  changedFiles?: string[];
+  /** 存在性 oracle（项目相对路径 → 是否存在）；缺省退化为「代码实况兜底」 */
+  fileExists?: (relPath: string) => boolean;
+  /** 源码根（如 'src'、'apps/api/src'）：未覆盖聚合与条目多根相对路径解析用 */
+  sourceRoots?: string[];
+}
+
+export interface CapabilityVerdict {
+  /** 文档中的文件条目（原样路径，可能为全路径或裸文件名） */
+  fileEntries: string[];
+  /** 文档中的目录条目（以 / 结尾） */
+  dirEntries: string[];
+  /** 参与覆盖判定的条目集 = 文件条目 + 目录条目 */
+  coverageEntries: string[];
+  /** 文档含 markdown 表格（区分「散文文档」与「有表格零条目」） */
+  hasTable: boolean;
+  /** 能力清单格式（计数行文档）：无文件表可核对，调用方据此短路 */
+  listingFormat: boolean;
+  /** 增量文件中未被覆盖的（capability_sync Step1） */
+  uncoveredChanges: string[];
+  /** 代码实况中未被文档登记的 */
+  uncoveredFiles: string[];
+  /** 未覆盖文件按源码根下第一级子目录聚合（module 模式的 added 形状） */
+  uncoveredDirs: string[];
+  /** 幽灵条目（文件 + 目录）：文档登记但代码实况与文件系统均不存在 */
+  deadEntries: string[];
+}
+
+/**
+ * 变更文件是否被条目覆盖（ADR-0009 唯一覆盖规则）
+ *
+ * 目录条目（以 / 结尾）前缀匹配；文件条目精确匹配或路径边界后缀匹配
+ * （兼容 basename 条目，但拒绝 xfoo.ts 命中 foo.ts、docs/src/foo.tsx 命中 src/foo.ts
+ * 这类 endsWith/includes 模糊匹配造成的碰撞）
+ */
+function isCoveredBy(entries: string[], file: string): boolean {
+  return entries.some((listed) =>
+    listed.endsWith('/')
+      ? file.startsWith(listed)
+      : file === listed || file.endsWith('/' + listed)
+  );
+}
+
+/** 条目多根相对路径的存在性：项目根直查 + 各源码根前缀（docs_freshness/sync-docs 历史同语义） */
+function entryExistsOnDisk(
+  entry: string,
+  fileExists: (rel: string) => boolean,
+  sourceRoots: string[]
+): boolean {
+  if (fileExists(entry)) return true;
+  return sourceRoots.some((root) => fileExists(`${root}/${entry}`));
+}
+
+export function reconcileCapabilities(input: ReconcileInput): CapabilityVerdict {
+  const {
+    content,
+    populationFiles,
+    changedFiles = [],
+    fileExists = () => false,
+    sourceRoots = [],
+  } = input;
+
+  const allEntries = parseCapabilitiesEntries(content, { includeDirs: true });
+  const fileEntries = allEntries.filter((e) => !e.endsWith('/'));
+  const dirEntries = allEntries.filter((e) => e.endsWith('/'));
+  const coverageEntries = [...fileEntries, ...dirEntries];
+
+  const uncoveredFiles = populationFiles.filter((f) => !isCoveredBy(coverageEntries, f));
+  const uncoveredDirs = [...new Set(
+    uncoveredFiles.map((file) => {
+      // 与 sync-docs 历史聚合同语义：归属第一个能前缀匹配的来源根，兜底首根
+      const root = sourceRoots.find((d) => file.startsWith(d + '/')) || sourceRoots[0] || '';
+      return aggregateToSourceSubdir(root, file);
+    })
+  )];
+
+  // 条目在代码实况中仍有对应文件即算活（裸文件名条目无法做存在性判定的兜底）
+  const aliveByPopulation = (entry: string): boolean =>
+    populationFiles.some((f) => isCoveredBy([entry], f));
+
+  const deadEntries = allEntries.filter((entry) => {
+    if (entryExistsOnDisk(entry, fileExists, sourceRoots)) return false;
+    return !aliveByPopulation(entry);
+  });
+
+  return {
+    fileEntries,
+    dirEntries,
+    coverageEntries,
+    hasTable: TABLE_SEPARATOR_REGEX.test(content),
+    listingFormat: isCapabilityListingFormat(content),
+    uncoveredChanges: changedFiles.filter((f) => !isCoveredBy(coverageEntries, f)),
+    uncoveredFiles,
+    uncoveredDirs,
+    deadEntries,
+  };
+}
+
+/**
+ * 变更清单中的「有意义的代码变更」：仅 .ts/.tsx/.js 且非测试文件
+ * （capability_sync Step1 的历史过滤规则，收口于此）
+ */
+export function significantCodeChanges(diffNames: string[]): string[] {
+  return diffNames
+    .filter((f) => f.endsWith('.ts') || f.endsWith('.tsx') || f.endsWith('.js'))
+    .filter((f) => !f.includes('__tests__') && !f.includes('.test.') && !f.includes('.spec.'));
+}
+
+/**
+ * 收集源码根下的实际文件清单（项目相对路径）
+ *
+ * 对 utils/file-walk 的统一封装，替代各调用方自拼 join/relative。
+ * 扩展名口径保持各调用方现状（checker 不含 .tsx；sync-docs 的模块扫描需
+ * ModuleInfo 元数据，继续走 scanSourceModules）——统一扩展名口径属行为变更，
+ * 不在本次纯重构范围（ADR-0009 记录在案）。
+ */
+export function collectSourceFiles(
+  projectPath: string,
+  roots: string[],
+  options: { includeTsx?: boolean } = {}
+): string[] {
+  const files: string[] = [];
+  for (const root of roots) {
+    const found = findTsSourceFiles(join(projectPath, root), {
+      skipIndex: true,
+      includeTsx: options.includeTsx,
+    });
+    files.push(...found.map((f) => relative(projectPath, f)));
+  }
+  return files;
+}

package/src/core/constraints/checker.ts

@@ -12,32 +12,33 @@ import {
   ConstraintContext,
   ConstraintResult,
   ConstraintCheckResult,
-  ConstraintTrigger,
   ConstraintLevel,
   ConstraintViolationError,
 } from '../../types/constraint';
 import type { ExecutionTrace } from '../../types/trace';
-import { getTraceCollector } from '../../monitoring/traces';
 import { IRON_LAWS, GUIDELINES, PROMPTS } from './definitions';
 import type { MergedConstraintsConfig } from '../../types/project-config';
-import { normalizeTriggers } from '../../utils/exec';
-import { runCommand } from '../../utils/exec';
+import { matchesTrigger } from '../../utils/exec';
 import { join, relative } from 'path';
 import { CheckCache } from './check-cache';
 import { findTsSourceFiles } from '../../utils/file-walk';
 import { getConstraintCheck, buildCheckEnv, type CheckOutcome } from './checkers';
+import { createGitEvidence, type GitEvidence } from './git-evidence';
 
 /**
- * trace 记录器最小接口（原工单 15 为消除 core→monitoring 循环；现 monitoring
- * 不反向依赖 core，方向单向、无环，checker 可直接值引用 getTraceCollector）
+ * trace 记录器最小接口（工单 15 decycle 收尾，harness#88）
  *
- * checker 不构造收集器；生产路径首次记录时惰性接线 getTraceCollector()
- * （幂等单点，ADR-0003），测试可经 setTraceRecorder 注入替身。
+ * core 不上行依赖 monitoring：记录器经**构造参数**注入，未注入 = no-op
+ * （默认无副作用）。真实收集器由组合根接线——CLI check/report 与 bootstrap
+ * 各自 `new ConstraintChecker(getTraceCollector())`。
  */
 export interface TraceRecorder {
   record(trace: ExecutionTrace): void;
 }
 
+/** 未注入时的默认记录器：不记录 */
+const NOOP_TRACE_RECORDER: TraceRecorder = { record: () => undefined };
+
 /**
  * 约束检查器
  */
@@ -47,60 +48,15 @@ export class ConstraintChecker {
   /** 检查结果缓存（S7：src 扫描等重复 I/O，TTL=1s 防跨测试污染） */
   private cache: CheckCache = new CheckCache({ ttlMs: 1000 });
 
-  /**
-   * run 级 memo（工单 18）：一次 checkConstraints 内
-   * git diff 等命令只执行一次；run 外直接调用私有检查方法时不 memo（恒新鲜）。
-   */
-  private runCache: Map<string, Promise<string>> | null = null;
-
-  /** trace 记录器（注入式；null = 未显式注入，首次记录时惰性接线全局收集器） */
-  private traceRecorder: TraceRecorder | null = null;
+  /** trace 记录器（构造注入；缺省 no-op） */
+  private readonly traceRecorder: TraceRecorder;
 
-  private constructor() {}
-
-  /**
-   * 取 trace 记录器：未显式注入时惰性接线全局收集器（幂等，ADR-0003 副作用收敛）
-   */
-  private getRecorder(): TraceRecorder {
-    if (!this.traceRecorder) {
-      this.traceRecorder = getTraceCollector();
-    }
-    return this.traceRecorder;
-  }
-
-  /**
-   * 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;
+  constructor(traceRecorder: TraceRecorder = NOOP_TRACE_RECORDER) {
+    this.traceRecorder = traceRecorder;
   }
 
   /**
-   * 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)
-    );
-  }
-
-  /**
-   * 获取单例实例
+   * 获取单例实例（未接线记录器的默认实例：不写 trace）
    */
   static getInstance(): ConstraintChecker {
     if (!ConstraintChecker.instance) {
@@ -109,13 +65,6 @@ export class ConstraintChecker {
     return ConstraintChecker.instance;
   }
 
-  /**
-   * 注入 trace 记录器（测试/定制场景；不调用则首次记录时惰性接线全局收集器）
-   */
-  setTraceRecorder(recorder: TraceRecorder): void {
-    this.traceRecorder = recorder;
-  }
-
   /**
    * 获取当前的约束集合（内置 + 自定义）
    *
@@ -143,10 +92,13 @@ export class ConstraintChecker {
 
   /**
    * 检查单个约束
+   *
+   * @param evidence 可选，本 run 的 git 证据实例（#87）；不传 = 本次调用独占一份真 git 证据
    */
   async check(
     constraint: Constraint,
-    context: ConstraintContext
+    context: ConstraintContext,
+    evidence?: GitEvidence
   ): Promise<ConstraintResult> {
     // prompt 类约束不参与 checker 执行（ADR-0001：仅参与注入）
     if (constraint.kind === 'prompt') {
@@ -160,7 +112,7 @@ export class ConstraintChecker {
     }
 
     // 检查前置条件（'skip' = 约定未采用/证据未接线：satisfied 置 true 但不计 pass/fail）
-    const outcome = await this.checkPrecondition(constraint, context);
+    const outcome = await this.checkPrecondition(constraint, context, evidence);
 
     if (outcome === 'skip') {
       return {
@@ -203,28 +155,15 @@ export class ConstraintChecker {
     }
   }
 
-  /**
-   * 判断约束是否匹配当前触发条件
-   *
-   * context.operation 为主触发条件，context.extraTriggers 为次级推断
-   * （ADR-0001：pre-commit 代码变更附加 code_implementation），任一命中即匹配。
-   */
-  private matchesTrigger(constraint: Constraint, context: ConstraintContext): boolean {
-    const triggers = normalizeTriggers<ConstraintTrigger>(constraint.trigger);
-    const operations = [context.operation, ...(context.extraTriggers ?? [])];
-    return operations.some(op => triggers.includes(op));
-  }
-
   /**
    * 记录约束检查的 trace
    */
   private recordTrace(
-    collector: TraceRecorder,
     constraint: Constraint,
     checkResult: ConstraintResult,
     context: ConstraintContext
   ): void {
-    collector.record({
+    this.traceRecorder.record({
       constraintId: constraint.id,
       level: constraint.level,
       timestamp: Date.now(),
@@ -241,10 +180,14 @@ export class ConstraintChecker {
    *
    * 注册表闭环（ADR-0001）：kind='check' 未注册 checker 直接抛错，
    * 不再有"未注册默认通过"路径；kind='prompt' 在 check() 入口已短路。
+   *
+   * git 证据（stagedDiff/stagedDiffNames）单一来源 = GitEvidence adapter（#87）：
+   * 一次 run 内调用方传同一实例即至多取证一次，run 外调用独占一份。
    */
   private async checkPrecondition(
     constraint: Constraint,
-    context: ConstraintContext
+    context: ConstraintContext,
+    evidence?: GitEvidence
   ): Promise<CheckOutcome> {
     const impl = getConstraintCheck(constraint.id);
     if (!impl) {
@@ -255,9 +198,10 @@ export class ConstraintChecker {
     }
 
     const projectPath = context.projectPath || process.cwd();
+    const git = evidence ?? createGitEvidence(projectPath);
     const env = buildCheckEnv(context, {
-      stagedDiff: () => this.getStagedDiff(projectPath),
-      stagedDiffNames: () => this.getStagedDiffNames(projectPath),
+      stagedDiff: async () => git.stagedDiff(),
+      stagedDiffNames: async () => git.changedFileNames(true),
       srcScan: (root: string) =>
         this.cache.getSync(`src_scan_${root}`, projectPath, () =>
           findTsSourceFiles(join(projectPath, root), { skipIndex: true }).map((f) =>
@@ -287,12 +231,9 @@ export class ConstraintChecker {
     const constraints = this.getConstraints(customConfig);
 
     const filterByTrigger = (constraintSet: Record<string, Constraint>): Constraint[] => {
-      return Object.values(constraintSet).filter(constraint => {
-        const triggers = Array.isArray(constraint.trigger)
-          ? constraint.trigger
-          : [constraint.trigger];
-        return operations.some(op => triggers.includes(op));
-      });
+      return Object.values(constraintSet).filter(constraint =>
+        matchesTrigger(constraint, operations)
+      );
     };
 
     return {
@@ -310,57 +251,58 @@ export class ConstraintChecker {
    *
    * @param context 约束上下文
    * @param customConfig 可选，per-request 自定义配置（避免多请求间的单例状态污染）
+   * @param evidence 可选，本 run 的 git 证据 adapter（#87）。调用方（CLI check）与
+   *   buildConstraintContext 传同一实例 → 一次 run 内 git 取证单一来源；
+   *   不传则本 run 自建一份，run 级 memo 照样生效（memo 在实例层，非隐式全局）。
    */
   async checkConstraints(
     context: ConstraintContext,
-    customConfig?: MergedConstraintsConfig | null
+    customConfig?: MergedConstraintsConfig | null,
+    evidence?: GitEvidence
   ): Promise<ConstraintCheckResult> {
-    // run 起始：重置 run 级缓存；run 结束（含铁律提前抛出）清空（工单 18）
+    // run 起始：重置 src 扫描缓存（S7）；git 证据 = 本 run 独占的 adapter 实例（工单 18 → #87）
     this.cache.invalidate();
-    this.runCache = new Map();
-
-    try {
-      const result: ConstraintCheckResult = {
-        ironLaws: [],
-        guidelines: [],
-        passed: true,
-        warningCount: 0,
-      };
+    const run = evidence ?? createGitEvidence(context.projectPath || process.cwd());
 
-      const traceCollector = this.getRecorder();
-      const constraints = this.getConstraints(customConfig);
+    const result: ConstraintCheckResult = {
+      ironLaws: [],
+      guidelines: [],
+      passed: true,
+      warningCount: 0,
+    };
+
+    const constraints = this.getConstraints(customConfig);
+    // context.operation 为主触发条件，extraTriggers 为次级推断（ADR-0001），任一命中即匹配
+    const operations = [context.operation, ...(context.extraTriggers ?? [])];
 
-      // 1. Iron Laws: 必须全部通过
-      for (const constraint of Object.values(constraints.ironLaws)) {
-        if (!this.matchesTrigger(constraint, context)) continue;
+    // 1. Iron Laws: 必须全部通过
+    for (const constraint of Object.values(constraints.ironLaws)) {
+      if (!matchesTrigger(constraint, operations)) continue;
 
-        const checkResult = await this.check(constraint, context);
-        result.ironLaws.push(checkResult);
-        this.recordTrace(traceCollector, constraint, checkResult, context);
+      const checkResult = await this.check(constraint, context, run);
+      result.ironLaws.push(checkResult);
+      this.recordTrace(constraint, checkResult, context);
 
-        if (!checkResult.satisfied) {
-          result.passed = false;
-          throw new ConstraintViolationError(checkResult);
-        }
+      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)) continue;
+    // 2. Guidelines: 记录警告
+    for (const constraint of Object.values(constraints.guidelines)) {
+      if (!matchesTrigger(constraint, operations)) 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, run);
+      result.guidelines.push(checkResult);
+      this.recordTrace(constraint, checkResult, context);
 
-        if (!checkResult.satisfied) {
-          result.warningCount++;
-        }
+      if (!checkResult.satisfied) {
+        result.warningCount++;
       }
-
-      return result;
-    } finally {
-      this.runCache = null;
     }
+
+    return result;
   }
 
   /**
@@ -368,19 +310,22 @@ export class ConstraintChecker {
    *
    * @param context 约束上下文
    * @param customConfig 可选，per-request 自定义配置（避免多请求间的单例状态污染）
+   * @param evidence 可选，本次检查共用的 git 证据 adapter（#87，同 checkConstraints）
    * @throws ConstraintViolationError 如果有铁律违规
    */
   async beforeExecution(
     context: ConstraintContext,
-    customConfig?: MergedConstraintsConfig | null
+    customConfig?: MergedConstraintsConfig | null,
+    evidence?: GitEvidence
   ): Promise<void> {
+    const run = evidence ?? createGitEvidence(context.projectPath || process.cwd());
     const constraints = this.getConstraints(customConfig);
     const operations = [context.operation, ...(context.extraTriggers ?? [])];
 
     for (const constraint of Object.values(constraints.ironLaws)) {
-      if (!normalizeTriggers(constraint.trigger).some((t) => operations.includes(t))) continue;
+      if (!matchesTrigger(constraint, operations)) continue;
 
-      const result = await this.check(constraint, context);
+      const result = await this.check(constraint, context, run);
       if (!result.satisfied) {
         throw new ConstraintViolationError(result);
       }
@@ -465,5 +410,5 @@ export async function checkBeforeExecution(
   return ConstraintChecker.getInstance().beforeExecution(context, customConfig);
 }
 
-// 导出单例
+// 导出单例（未接线记录器：只评估约束，不写 trace；写 trace 由组合根自行 new）
 export const constraintChecker = ConstraintChecker.getInstance();