@dommaker/harness 1.6.0 → 1.8.0

package/src/core/constraints/__tests__/run-env.test.ts

@@ -0,0 +1,377 @@
+/**
+ * 运行级观察面测试（ADR-0023 决策 1/4）
+ *
+ * 钉五件事：① 一次运行内同一份 trace 至多读一次（懒建 + memo）；② 不同尾部窗口的口径
+ * 与 `readJsonl(..., {tail})` 逐字一致（含坏行占槽位）——这是"合并两处读"不改变判定的前提；
+ * ③ context-builder 用注入的 env，而不是自己再读一遍；
+ * ④ 项目配置（config.yml 与自定义约束文件）一次运行一份快照（ADR-0023 决策 2：
+ *    进程级缓存撤销后的口径）；
+ * ⑤ 能力表一次解析多消费——两个 checker 共用同一枚 env 时文档只读一次、判定不变
+ *    （ADR-0023 决策 4）。
+ */
+
+import { jest } from '@jest/globals';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { createRunEnv, resolveRunEnv, TRACE_TAIL_WINDOW, type RunEnv } from '../run-env';
+import { buildConstraintContext } from '../context-builder';
+import { buildCheckEnv, normalizeCheckOutcome } from '../checkers/types';
+import { docsFreshness } from '../checkers/docs-freshness';
+import { capabilitySync } from '../checkers/capability-sync';
+import { collectSourceFiles, reconcileCapabilities } from '../capabilities-reconcile';
+import { loadRawProjectConfig } from '../../project-config-loader';
+import { createProjectFixture, writeProjectConfig } from '../../../test-setup/project-fixture';
+import { readJsonl } from '../../../utils/jsonl';
+import { DEFAULT_TRACE_FILE, type ExecutionTrace } from '../../../types/trace';
+import type { GitEvidence } from '../git-evidence';
+
+// ts-jest 的 namespace 导入属性不可重定义（jest.spyOn 会抛），只包一层 readFileSync
+// 做读计数——其余 fs 能力用真实实现，夹具搭建与被检代码读取都不受影响
+// （同一手法先例：src/__tests__/context-files-resolution.test.ts）
+jest.mock('fs', () => {
+  const actual = jest.requireActual<typeof import('fs')>('fs');
+  return { ...actual, readFileSync: jest.fn(actual.readFileSync) };
+});
+
+const readSpy = (fs as unknown as { readFileSync: jest.Mock }).readFileSync;
+const capsReads = () =>
+  readSpy.mock.calls.filter(call => String(call[0]).endsWith('CAPABILITIES.md')).length;
+
+const tracePathOf = (projectPath: string) => path.join(projectPath, DEFAULT_TRACE_FILE);
+
+function writeTraces(projectPath: string, lines: string[]): void {
+  const file = tracePathOf(projectPath);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, lines.join('\n') + '\n', 'utf-8');
+}
+
+const traceLine = (id: string, result: 'pass' | 'fail'): string =>
+  JSON.stringify({ constraintId: id, level: 'iron_law', timestamp: 1, result });
+
+const CORRUPT = '{"constraintId":"broken"';
+
+describe('createRunEnv', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-run-env-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('一次运行内同一份 trace 至多读一次：取过之后再改文件，仍是老内容', () => {
+    writeTraces(dir, [traceLine('a', 'pass')]);
+    const env = createRunEnv(dir);
+    expect(env.traceTail(1).records.map(r => r.constraintId)).toEqual(['a']);
+
+    // 追加一条 fail：若没有 memo，第二次取会读到新尾部并判出 fail
+    writeTraces(dir, [traceLine('a', 'pass'), traceLine('b', 'fail')]);
+    expect(env.traceTail(2).records.map(r => r.constraintId)).toEqual(['a']);
+  });
+
+  it('懒建：造 env 不碰文件，之后落的数据才读得到', () => {
+    const env = createRunEnv(dir);
+    writeTraces(dir, [traceLine('late', 'fail')]);
+    expect(env.traceTail(5).records.map(r => r.constraintId)).toEqual(['late']);
+  });
+
+  it('缺 trace 文件返回空窗口，不抛', () => {
+    expect(createRunEnv(dir).traceTail(10)).toEqual({ records: [], skippedLines: 0 });
+  });
+
+  it('窗口口径与 readJsonl 的 tail 逐字一致（含坏行占槽位）', () => {
+    const lines = [
+      traceLine('old', 'fail'),
+      traceLine('x1', 'pass'),
+      CORRUPT,
+      traceLine('x2', 'pass'),
+      traceLine('x3', 'pass'),
+    ];
+    writeTraces(dir, lines);
+    const env = createRunEnv(dir);
+    const file = tracePathOf(dir);
+
+    for (const limit of [1, 2, 3, 4, 5]) {
+      expect(env.traceTail(limit)).toEqual(readJsonl<ExecutionTrace>(file, 'skip', { tail: limit }));
+    }
+    // 坏行占住尾部槽位：limit=3 时最近三条含一条坏行 → 有效记录只剩 2 条
+    expect(env.traceTail(3).records.map(r => r.constraintId)).toEqual(['x2', 'x3']);
+    expect(env.traceTail(3).skippedLines).toBe(1);
+  });
+
+  it('超过窗口上限直接抛，不静默少给', () => {
+    writeTraces(dir, Array.from({ length: 40 }, (_, i) => traceLine(`t${i}`, 'pass')));
+    const env = createRunEnv(dir);
+    expect(() => env.traceTail(TRACE_TAIL_WINDOW + 1)).toThrow(`尾部窗口上限 ${TRACE_TAIL_WINDOW} 行`);
+  });
+
+  it('projectPath 原样带出（每个 IO 点锚同一个根，harness#95）', () => {
+    expect(createRunEnv(dir).projectPath).toBe(dir);
+  });
+
+  it('sourceRoots 一次运行内至多探测一次', () => {
+    fs.mkdirSync(path.join(dir, 'src'), { recursive: true });
+    fs.writeFileSync(path.join(dir, 'src', 'a.ts'), 'export const a = 1;\n');
+    const env = createRunEnv(dir);
+    expect(env.sourceRoots()).toContain('src');
+
+    // 运行中途新增源码根：memo 生效，同一份结果不再走盘
+    fs.mkdirSync(path.join(dir, 'packages'), { recursive: true });
+    fs.writeFileSync(path.join(dir, 'packages', 'b.ts'), 'export const b = 1;\n');
+    expect(env.sourceRoots()).not.toContain('packages');
+  });
+});
+
+describe('配置一次装载 — rawConfig / customConstraints（ADR-0023 决策 2）', () => {
+  let dir: string;
+
+  const writeConfig = (content: string) => writeProjectConfig(dir, content);
+
+  /** 落 `.harness/<fileName>`（夹具可能还没有 .harness 目录，先补上） */
+  const writeHarnessFile = (fileName: string, body: string) => {
+    const target = path.join(dir, '.harness', fileName);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, body, 'utf-8');
+  };
+
+  beforeEach(() => {
+    dir = createProjectFixture({ name: 'run-env-config' });
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('run 内至多读一次：取过之后再改文件，仍是老内容', () => {
+    writeConfig('preset: standard\n');
+    const env = createRunEnv(dir);
+    expect(env.rawConfig()).toEqual({ preset: 'standard' });
+
+    writeConfig('preset: strict\n');
+    expect(env.rawConfig()).toEqual({ preset: 'standard' });
+  });
+
+  it('懒建：造 env 不碰文件，之后落的配置才读得到', () => {
+    const env = createRunEnv(dir);
+    writeConfig('preset: minimal\n');
+    expect(env.rawConfig()).toEqual({ preset: 'minimal' });
+  });
+
+  it('无 config.yml = undefined（并记住这个结论，不反复探测）', () => {
+    const env = createRunEnv(dir);
+    expect(env.rawConfig()).toBeUndefined();
+    expect(env.rawConfig()).toBeUndefined();
+  });
+
+  it('空文件回落 {}，与改前 loadRawProjectConfig 逐字一致', () => {
+    writeConfig('');
+    expect(createRunEnv(dir).rawConfig()).toEqual({});
+  });
+
+  it('YAML 解析失败照抛——兜与否属消费方的判定，读面不替它决定', () => {
+    writeConfig('governance: [\n  broken: {{\n');
+    const env = createRunEnv(dir);
+    expect(() => env.rawConfig()).toThrow();
+    // 抛错不入 memo：修好文件后同一枚 env 也能读到正确内容
+    writeConfig('preset: standard\n');
+    expect(env.rawConfig()).toEqual({ preset: 'standard' });
+  });
+
+  it('resolveRunEnv：传 env 原样复用，传路径各自读当下内容（无进程级残留）', () => {
+    writeConfig('preset: standard\n');
+    const env = createRunEnv(dir);
+    expect(resolveRunEnv(env)).toBe(env);
+    expect(resolveRunEnv(dir).rawConfig()).toEqual({ preset: 'standard' });
+
+    writeConfig('preset: strict\n');
+    expect(loadRawProjectConfig(dir)).toEqual({ preset: 'strict' });
+    expect(resolveRunEnv().projectPath).toBe(process.cwd());
+  });
+
+  it('customConstraints 取 custom_constraints 段，run 内同名文件至多读一次', () => {
+    const write = (body: string) => writeHarnessFile('custom-constraints.yml', body);
+    write('custom_constraints:\n  a:\n    level: iron_law\n    rule: 只此一份\n');
+    const env = createRunEnv(dir);
+    expect(Object.keys(env.customConstraints('custom-constraints.yml'))).toEqual(['a']);
+
+    write('custom_constraints:\n  b:\n    level: guideline\n    rule: 后来的\n');
+    expect(Object.keys(env.customConstraints('custom-constraints.yml'))).toEqual(['a']);
+  });
+
+  it('customConstraints：文件缺失 = {}；不同文件名各自 memo', () => {
+    const env = createRunEnv(dir);
+    expect(env.customConstraints('missing.yml')).toEqual({});
+
+    writeHarnessFile(
+      'other.yml',
+      'custom_constraints:\n  c:\n    level: guideline\n    rule: r\n'
+    );
+    expect(Object.keys(env.customConstraints('other.yml'))).toEqual(['c']);
+    expect(env.customConstraints('missing.yml')).toEqual({});
+  });
+});
+
+describe('context-builder 经注入的观察面取证据', () => {
+  let dir: string;
+
+  const fakeGit = (projectPath: string, changed: string[]): GitEvidence => ({
+    projectPath,
+    stagedDiff: () => '',
+    changedFileNames: () => changed.join('\n'),
+    headDirs: () => new Set<string>(),
+  });
+
+  /** 只记次数的假观察面：records 固定，用于断言两个证据探测都从 env 取数 */
+  function countingEnv(records: ExecutionTrace[]) {
+    const limits: number[] = [];
+    const env: RunEnv = {
+      projectPath: dir,
+      traceTail: (limit: number) => {
+        limits.push(limit);
+        return { records: limit >= records.length ? records : records.slice(-limit), skippedLines: 0 };
+      },
+      sourceRoots: () => ['src'],
+      rawConfig: () => undefined,
+      customConstraints: () => ({}),
+      capabilities: () => undefined,
+    };
+    return { env, limits };
+  }
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-ctxbuilder-env-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('hasFailingTest / hasVerificationEvidence 各按自己的窗口向 env 取数，不另开读', async () => {
+    const { env, limits } = countingEnv([
+      { constraintId: 'p', level: 'iron_law', timestamp: 1, result: 'pass' },
+      { constraintId: 'f', level: 'iron_law', timestamp: 2, result: 'fail' },
+    ]);
+    const ctx = await buildConstraintContext({
+      projectPath: dir,
+      staged: false,
+      evidence: fakeGit(dir, ['README.md']),
+      runEnv: env,
+    });
+
+    expect(limits).toEqual([TRACE_TAIL_WINDOW, 10]);
+    expect(ctx.hasFailingTest).toBe(true);
+    expect(ctx.hasVerificationEvidence).toBe(true);
+  });
+
+  it('窗口里没有 pass 时验证证据为 false（合并读取不改判定）', async () => {
+    const { env } = countingEnv([
+      { constraintId: 'f', level: 'iron_law', timestamp: 2, result: 'fail' },
+    ]);
+    const ctx = await buildConstraintContext({
+      projectPath: dir,
+      staged: false,
+      evidence: fakeGit(dir, ['README.md']),
+      runEnv: env,
+    });
+    expect(ctx.hasFailingTest).toBe(true);
+    expect(ctx.hasVerificationEvidence).toBe(false);
+  });
+
+  it('不注入 env 时自造一份并按 projectPath 锚定读取', async () => {
+    writeTraces(dir, [traceLine('a', 'fail')]);
+    const ctx = await buildConstraintContext({
+      projectPath: dir,
+      staged: false,
+      evidence: fakeGit(dir, ['README.md']),
+    });
+    expect(ctx.hasFailingTest).toBe(true);
+  });
+});
+
+describe('capabilities — 能力表一次解析多消费（ADR-0023 决策 4）', () => {
+  const TABLE = '| 能力 | 路径 | 说明 |\n|---|---|---|\n';
+  /** 幽灵条目 src/gone.ts + 一个真实源文件 src/live.ts */
+  const CAPS_DOC = `# C\n\n${TABLE}| 幽灵 | src/gone.ts | 已删 |\n`;
+
+  let dir: string;
+
+  beforeEach(() => {
+    dir = createProjectFixture({
+      name: 'run-env-caps',
+      files: { 'CAPABILITIES.md': CAPS_DOC, 'src/live.ts': 'export const x = 1;\n' },
+    });
+    readSpy.mockClear();
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  /** 两个 checker 共用同一枚 env（= 一次 check run 的形状） */
+  async function evaluateBoth(env: RunEnv) {
+    const scan = collectSourceFiles(dir, env.sourceRoots());
+    const checkEnv = buildCheckEnv(
+      { operation: 'module_modification', projectPath: dir },
+      { stagedDiff: async () => '', stagedDiffNames: async () => '', srcScan: () => scan },
+      env
+    );
+    return {
+      docs: normalizeCheckOutcome(await docsFreshness.evaluate(checkEnv)),
+      caps: normalizeCheckOutcome(await capabilitySync.evaluate(checkEnv)),
+    };
+  }
+
+  it('一次 run 内两个 checker 共用同一份读取：CAPABILITIES.md 只读一次', async () => {
+    const { docs, caps } = await evaluateBoth(createRunEnv(dir));
+
+    // 判定照旧：幽灵条目由 docs_freshness 点名，capability_sync 正常评估不 skip
+    expect(docs.satisfied).toBe(false);
+    expect(docs.evidence.join('\n')).toContain('src/gone.ts');
+    expect(caps.skipped).toBe(false);
+    expect(capsReads()).toBe(1);
+  });
+
+  it('取过之后再改文档 = 同一份内容（run 内 memo，不重复解析）', () => {
+    const env = createRunEnv(dir);
+    const first = env.capabilities(['src/live.ts']);
+    expect(capsReads()).toBe(1);
+
+    fs.writeFileSync(path.join(dir, 'CAPABILITIES.md'), `# C\n\n${TABLE}| 新 | src/live.ts | 在 |\n`, 'utf-8');
+    expect(env.capabilities(['src/live.ts'])).toBe(first);
+    expect(capsReads()).toBe(1);
+  });
+
+  it('无 CAPABILITIES.md → undefined；有文档时判定与直调对照模块同输入同结果', () => {
+    const noDoc = createProjectFixture({ name: 'run-env-caps-none', files: { 'src/a.ts': 'x\n' } });
+    try {
+      expect(createRunEnv(noDoc).capabilities(['src/a.ts'])).toBeUndefined();
+    } finally {
+      fs.rmSync(noDoc, { recursive: true, force: true });
+    }
+
+    const env = createRunEnv(dir);
+    const caps = env.capabilities(['src/live.ts']);
+    expect(caps?.verdict.deadEntries).toEqual(
+      reconcileCapabilities({
+        content: caps!.content,
+        populationFiles: ['src/live.ts'],
+        sourceRoots: caps!.sourceRoots,
+        fileExists: rel => fs.existsSync(path.join(dir, rel)),
+      }).deadEntries
+    );
+    // 增量那一维不在上行数据面（变更清单属 git 证据 #87），共享形状里恒空
+    expect(caps?.verdict.uncoveredChanges).toEqual([]);
+  });
+
+  it('源根探测与能力表共用同一份 memo：取过之后再改目录树不影响', () => {
+    const env = createRunEnv(dir);
+    const before = env.capabilities(['src/live.ts'])?.sourceRoots;
+
+    fs.mkdirSync(path.join(dir, 'packages'), { recursive: true });
+    fs.writeFileSync(path.join(dir, 'packages', 'p.ts'), 'export const p = 1;\n', 'utf-8');
+    expect(env.capabilities(['src/live.ts'])?.sourceRoots).toBe(before);
+  });
+});

package/src/core/constraints/__tests__/triggers.test.ts

@@ -0,0 +1,70 @@
+/**
+ * 约束 trigger 归一与匹配谓词测试（harness#105 语义单点）
+ *
+ * 用例自 `src/__tests__/exec.test.ts` 随迁（harness#137）：二者是约束域谓词，
+ * 归位到 core/constraints 后测试跟着正本走。
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import { normalizeTriggers, matchesTrigger } from '../triggers';
+
+describe('normalizeTriggers', () => {
+  it('应该返回 fallback 当值为 null', () => {
+    const result = normalizeTriggers(null, ['default']);
+    expect(result).toEqual(['default']);
+  });
+
+  it('应该返回 fallback 当值为 undefined', () => {
+    const result = normalizeTriggers(undefined, ['default']);
+    expect(result).toEqual(['default']);
+  });
+
+  it('应该将单值包装为数组', () => {
+    const result = normalizeTriggers('single');
+    expect(result).toEqual(['single']);
+  });
+
+  it('应该直接返回数组', () => {
+    const result = normalizeTriggers(['a', 'b']);
+    expect(result).toEqual(['a', 'b']);
+  });
+
+  it('应该使用空数组作为默认 fallback', () => {
+    const result = normalizeTriggers(undefined);
+    expect(result).toEqual([]);
+  });
+});
+
+describe('matchesTrigger', () => {
+  it('单值 trigger 命中操作返回 true', () => {
+    expect(matchesTrigger({ trigger: 'a' }, ['a'])).toBe(true);
+  });
+
+  it('单值 trigger 未命中返回 false', () => {
+    expect(matchesTrigger({ trigger: 'a' }, ['b'])).toBe(false);
+  });
+
+  it('数组 trigger 任一命中即返回 true', () => {
+    expect(matchesTrigger({ trigger: ['a', 'b'] }, ['b'])).toBe(true);
+  });
+
+  it('数组 trigger 全部未命中返回 false', () => {
+    expect(matchesTrigger({ trigger: ['a', 'b'] }, ['c', 'd'])).toBe(false);
+  });
+
+  it('operations 中任一命中即返回 true', () => {
+    expect(matchesTrigger({ trigger: 'a' }, ['x', 'a'])).toBe(true);
+  });
+
+  it('trigger 为 undefined 时不匹配任何操作', () => {
+    expect(matchesTrigger({ trigger: undefined }, ['a'])).toBe(false);
+  });
+
+  it('trigger 为空数组时不匹配任何操作', () => {
+    expect(matchesTrigger({ trigger: [] }, ['a'])).toBe(false);
+  });
+
+  it('operations 为空数组时返回 false', () => {
+    expect(matchesTrigger({ trigger: 'a' }, [])).toBe(false);
+  });
+});

package/src/core/constraints/agent-prompt-renderer.ts

@@ -12,7 +12,7 @@
  */
 
 import type { ConstraintLevel, ConstraintTrigger } from '../../types/constraint';
-import { matchesTrigger } from '../../utils/exec';
+import { matchesTrigger } from './triggers';
 import { getEffectiveConstraints } from '../effective-constraints';
 
 /**

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

@@ -16,6 +16,7 @@
  * module 读 uncoveredDirs（目录聚合），file 读 uncoveredFiles（逐文件）。
  */
 
+import { existsSync } from 'fs';
 import { join, relative } from 'path';
 import {
   aggregateToSourceSubdir,
@@ -67,8 +68,11 @@ export interface CapabilityVerdict {
  * 目录条目（以 / 结尾）前缀匹配；文件条目精确匹配或路径边界后缀匹配
  * （兼容 basename 条目，但拒绝 xfoo.ts 命中 foo.ts、docs/src/foo.tsx 命中 src/foo.ts
  * 这类 endsWith/includes 模糊匹配造成的碰撞）
+ *
+ * 对外导出（ADR-0023 步骤 4）：共享对照判定的消费方需要按自己的增量清单再算一次覆盖，
+ * 这条规则不得在别处重写。
  */
-function isCoveredBy(entries: string[], file: string): boolean {
+export function isCoveredByEntries(entries: string[], file: string): boolean {
   return entries.some((listed) =>
     listed.endsWith('/')
       ? file.startsWith(listed)
@@ -100,7 +104,7 @@ export function reconcileCapabilities(input: ReconcileInput): CapabilityVerdict
   const dirEntries = allEntries.filter((e) => e.endsWith('/'));
   const coverageEntries = [...fileEntries, ...dirEntries];
 
-  const uncoveredFiles = populationFiles.filter((f) => !isCoveredBy(coverageEntries, f));
+  const uncoveredFiles = populationFiles.filter((f) => !isCoveredByEntries(coverageEntries, f));
   const uncoveredDirs = [...new Set(
     uncoveredFiles.map((file) => {
       // 与 sync-docs 历史聚合同语义：归属第一个能前缀匹配的来源根，兜底首根
@@ -111,7 +115,7 @@ export function reconcileCapabilities(input: ReconcileInput): CapabilityVerdict
 
   // 条目在代码实况中仍有对应文件即算活（裸文件名条目无法做存在性判定的兜底）
   const aliveByPopulation = (entry: string): boolean =>
-    populationFiles.some((f) => isCoveredBy([entry], f));
+    populationFiles.some((f) => isCoveredByEntries([entry], f));
 
   const deadEntries = allEntries.filter((entry) => {
     if (entryExistsOnDisk(entry, fileExists, sourceRoots)) return false;
@@ -124,7 +128,7 @@ export function reconcileCapabilities(input: ReconcileInput): CapabilityVerdict
     coverageEntries,
     hasTable: TABLE_SEPARATOR_REGEX.test(content),
     listingFormat: isCapabilityListingFormat(content),
-    uncoveredChanges: changedFiles.filter((f) => !isCoveredBy(coverageEntries, f)),
+    uncoveredChanges: changedFiles.filter((f) => !isCoveredByEntries(coverageEntries, f)),
     uncoveredFiles,
     uncoveredDirs,
     deadEntries,
@@ -164,3 +168,23 @@ export function collectSourceFiles(
   }
   return files;
 }
+
+/**
+ * 「代码实况清单」的唯一取法：只收真实存在的源码根下的文件（项目相对路径）
+ *
+ * 抽出的理由（ADR-0023 步骤 4）：capability_sync 与 docs_freshness 现在把同一份清单
+ * 喂给 run 内共享的对照判定（`RunEnv.capabilities()`，memo 只记第一次的输入），
+ * 两边必须逐字相同，否则共享的就是一份错的东西。扫描本身仍经调用方注入的 `scan`
+ * （保留 checker 侧 srcScan 证据接缝与测试可替身性）。
+ */
+export function collectPopulationFiles(
+  projectPath: string,
+  roots: string[],
+  scan: (root: string) => string[]
+): string[] {
+  const files: string[] = [];
+  for (const root of roots) {
+    if (existsSync(join(projectPath, root))) files.push(...scan(root));
+  }
+  return files;
+}

package/src/core/constraints/check-cache.ts

@@ -14,7 +14,7 @@
  * ```typescript
  * const cache = new CheckCache({ ttlMs: 5000 });
  * // 普通 TTL 缓存
- * const diff = await cache.get('git_diff', projectPath, () => runCommand('git diff --cached', projectPath));
+ * const diff = await cache.get('git_diff', projectPath, () => createGitEvidence(projectPath).stagedDiff());
  * // 计数采样：每 3 次调用执行 1 次完整检查
  * const ok = await cache.get('goal_check', key, check, { sampleRate: 3, defaultValueOnMiss: true });
  * ```

package/src/core/constraints/checker.ts

@@ -18,12 +18,13 @@ import {
 import type { ExecutionTrace } from '../../types/trace';
 import { IRON_LAWS, GUIDELINES, PROMPTS } from './definitions';
 import type { MergedConstraintsConfig } from '../../types/project-config';
-import { matchesTrigger } from '../../utils/exec';
+import { matchesTrigger } from './triggers';
 import { join, relative } from 'path';
 import { CheckCache } from './check-cache';
 import { findTsSourceFiles } from '../../utils/file-walk';
 import { getConstraintCheck, buildCheckEnv, normalizeCheckOutcome, type CheckOutcome } from './checkers';
 import { createGitEvidence, type GitEvidence } from './git-evidence';
+import { createRunEnv, type RunEnv } from './run-env';
 
 /**
  * trace 记录器最小接口（工单 15 decycle 收尾，harness#88）
@@ -94,11 +95,13 @@ export class ConstraintChecker {
    * 检查单个约束
    *
    * @param evidence 可选，本 run 的 git 证据实例（#87）；不传 = 本次调用独占一份真 git 证据
+   * @param runEnv 可选，本 run 的运行级观察面（ADR-0023）；不传 = 本次调用独占一份
    */
   async check(
     constraint: Constraint,
     context: ConstraintContext,
-    evidence?: GitEvidence
+    evidence?: GitEvidence,
+    runEnv?: RunEnv
   ): Promise<ConstraintResult> {
     // prompt 类约束不参与 checker 执行（ADR-0001：仅参与注入）
     if (constraint.kind === 'prompt') {
@@ -113,7 +116,7 @@ export class ConstraintChecker {
 
     // 检查前置条件（'skip' = 约定未采用/证据未接线：satisfied 置 true 但不计 pass/fail）
     const outcome = normalizeCheckOutcome(
-      await this.checkPrecondition(constraint, context, evidence)
+      await this.checkPrecondition(constraint, context, evidence, runEnv)
     );
 
     if (outcome.skipped) {
@@ -187,11 +190,13 @@ export class ConstraintChecker {
    *
    * git 证据（stagedDiff/stagedDiffNames）单一来源 = GitEvidence adapter（#87）：
    * 一次 run 内调用方传同一实例即至多取证一次，run 外调用独占一份。
+   * 上行数据（config.yml / trace 尾部 / 源根）同一形状 = RunEnv（ADR-0023）。
    */
   private async checkPrecondition(
     constraint: Constraint,
     context: ConstraintContext,
-    evidence?: GitEvidence
+    evidence?: GitEvidence,
+    runEnv?: RunEnv
   ): Promise<CheckOutcome> {
     const impl = getConstraintCheck(constraint.id);
     if (!impl) {
@@ -212,7 +217,7 @@ export class ConstraintChecker {
             relative(projectPath, f)
           )
         ),
-    });
+    }, runEnv);
 
     return await impl.evaluate(env);
   }
@@ -258,13 +263,16 @@ export class ConstraintChecker {
    * @param evidence 可选，本 run 的 git 证据 adapter（#87）。调用方（CLI check）与
    *   buildConstraintContext 传同一实例 → 一次 run 内 git 取证单一来源；
    *   不传则本 run 自建一份，run 级 memo 照样生效（memo 在实例层，非隐式全局）。
+   * @param runEnv 可选，本 run 的运行级观察面（ADR-0023）。调用方（CLI check）与
+   *   buildConstraintContext 传同一实例 → 一次 run 内同一项目文件至多读一次。
    */
   async checkConstraints(
     context: ConstraintContext,
     customConfig?: MergedConstraintsConfig | null,
-    evidence?: GitEvidence
+    evidence?: GitEvidence,
+    runEnv?: RunEnv
   ): Promise<ConstraintCheckResult> {
-    return this.runAllConstraints(context, customConfig, evidence, 'block');
+    return this.runAllConstraints(context, customConfig, evidence, runEnv, 'block');
   }
 
   /**
@@ -278,9 +286,10 @@ export class ConstraintChecker {
   async collectConstraints(
     context: ConstraintContext,
     customConfig?: MergedConstraintsConfig | null,
-    evidence?: GitEvidence
+    evidence?: GitEvidence,
+    runEnv?: RunEnv
   ): Promise<ConstraintCheckResult> {
-    return this.runAllConstraints(context, customConfig, evidence, 'collect');
+    return this.runAllConstraints(context, customConfig, evidence, runEnv, 'collect');
   }
 
   /**
@@ -291,11 +300,15 @@ export class ConstraintChecker {
     context: ConstraintContext,
     customConfig: MergedConstraintsConfig | null | undefined,
     evidence: GitEvidence | undefined,
+    runEnv: RunEnv | undefined,
     mode: 'block' | 'collect'
   ): Promise<ConstraintCheckResult> {
     // run 起始：重置 src 扫描缓存（S7）；git 证据 = 本 run 独占的 adapter 实例（工单 18 → #87）
     this.cache.invalidate();
-    const run = evidence ?? createGitEvidence(context.projectPath || process.cwd());
+    const projectPath = context.projectPath || process.cwd();
+    const run = evidence ?? createGitEvidence(projectPath);
+    // 观察面同一形状（ADR-0023）：调用方传了就共用，没传也只造一枚——逐条 checker 不再各读一遍配置
+    const env = runEnv ?? createRunEnv(projectPath);
 
     const result: ConstraintCheckResult = {
       ironLaws: [],
@@ -312,7 +325,7 @@ export class ConstraintChecker {
     for (const constraint of Object.values(constraints.ironLaws)) {
       if (!matchesTrigger(constraint, operations)) continue;
 
-      const checkResult = await this.check(constraint, context, run);
+      const checkResult = await this.check(constraint, context, run, env);
       result.ironLaws.push(checkResult);
       this.recordTrace(constraint, checkResult, context);
 
@@ -328,7 +341,7 @@ export class ConstraintChecker {
     for (const constraint of Object.values(constraints.guidelines)) {
       if (!matchesTrigger(constraint, operations)) continue;
 
-      const checkResult = await this.check(constraint, context, run);
+      const checkResult = await this.check(constraint, context, run, env);
       result.guidelines.push(checkResult);
       this.recordTrace(constraint, checkResult, context);
 
@@ -353,14 +366,17 @@ export class ConstraintChecker {
     customConfig?: MergedConstraintsConfig | null,
     evidence?: GitEvidence
   ): Promise<void> {
-    const run = evidence ?? createGitEvidence(context.projectPath || process.cwd());
+    const projectPath = context.projectPath || process.cwd();
+    const run = evidence ?? createGitEvidence(projectPath);
+    // 独立 run 入口（ADR-0023）：本函数内所有 checker 共用一枚观察面
+    const env = createRunEnv(projectPath);
     const constraints = this.getConstraints(customConfig);
     const operations = [context.operation, ...(context.extraTriggers ?? [])];
 
     for (const constraint of Object.values(constraints.ironLaws)) {
       if (!matchesTrigger(constraint, operations)) continue;
 
-      const result = await this.check(constraint, context, run);
+      const result = await this.check(constraint, context, run, env);
       if (!result.satisfied) {
         throw new ConstraintViolationError(result);
       }