@dommaker/harness 1.7.0 → 1.8.1

package/src/core/constraints/checkers/__tests__/context-doc-sync.test.ts

@@ -9,8 +9,9 @@
  */
 
 import { describe, it, expect } from '@jest/globals';
+import { join } from 'path';
 import { contextDocSync } from '../context-doc-sync';
-import { buildCheckEnv } from '../types';
+import { buildCheckEnv, normalizeCheckOutcome } from '../types';
 import { createProjectFixture } from '../../../../test-setup/project-fixture';
 import type { ConstraintContext } from '../../../../types/constraint';
 
@@ -65,9 +66,13 @@ describe('context_doc_sync — 判定', () => {
     expect(await evaluate(dir)).toBe(true);
   });
 
-  it('任一目录缺 CONTEXT.md → fail', async () => {
+  it('任一目录缺 CONTEXT.md → fail，证据点名缺的那一个（ADR-0016 补迁）', async () => {
     const dir = setupDir('one-missing', CTX_FILES(true, ['src', 'bin']), ['src']);
-    expect(await evaluate(dir)).toBe(false);
+    const outcome = normalizeCheckOutcome(await evaluate(dir));
+    expect(outcome.satisfied).toBe(false);
+    expect(outcome.skipped).toBe(false);
+    expect(outcome.evidence.join('\n')).toContain(join('bin', 'CONTEXT.md'));
+    expect(outcome.evidence.join('\n')).not.toContain(join('src', 'CONTEXT.md'));
   });
 
   it('配置解析失败 → skip（不炸不报）', async () => {

package/src/core/constraints/checkers/__tests__/governance-presence.test.ts

@@ -18,12 +18,13 @@ import {
 } from '../governance-presence';
 import { detectInjectionDrift } from '../../injection-drift';
 import { createProjectFixture, writeProjectConfig } from '../../../../test-setup/project-fixture';
-import type { CheckEnv } from '../types';
+import { normalizeCheckOutcome, type CheckEnv } from '../types';
+import { createRunEnv } from '../../run-env';
 
 function makeEnv(projectPath: string): CheckEnv {
   return {
+    ...createRunEnv(projectPath),
     context: { operation: 'commit', projectPath },
-    projectPath,
     stagedDiff: async () => '',
     stagedDiffNames: async () => '',
     srcScan: () => [],
@@ -87,12 +88,20 @@ describe('governance_presence checker', () => {
     expect(await governancePresence.evaluate(makeEnv(tempDir))).toBe(true);
   });
 
-  it('两处都没有治理契约 → fail 并报警（防静默丢失）', async () => {
+  /** 判定与证据的统一读法（harness#119/ADR-0016：布尔与 CheckDetail 两种形状同一断言） */
+  const outcomeOf = async (projectPath: string) =>
+    normalizeCheckOutcome(await governancePresence.evaluate(makeEnv(projectPath)));
+
+  it('两处都没有治理契约 → fail，证据点名两处落点与修复入口（不再走 stderr 侧信道）', async () => {
     writeConfig();
     fs.writeFileSync(path.join(tempDir, 'AGENTS.md'), '# AGENTS.md\n\n只有机器生成内容\n');
     fs.writeFileSync(path.join(tempDir, 'CLAUDE.md'), '# CLAUDE.md\n\n@AGENTS.md\n');
-    expect(await governancePresence.evaluate(makeEnv(tempDir))).toBe(false);
-    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('治理契约缺失'));
+    const outcome = await outcomeOf(tempDir);
+    expect(outcome.satisfied).toBe(false);
+    expect(outcome.evidence.join('\n')).toContain('治理契约');
+    expect(outcome.evidence.join('\n')).toContain('harness init');
+    // ADR-0016：证据只有一个出口。侧信道留着会让 CLI 结构化输出与 trace 两头口径不一致
+    expect(errorSpy).not.toHaveBeenCalled();
   });
 
   it('PRESERVE:governance 段为空（被掏空）且 CLAUDE.md 无治理块 → fail', async () => {
@@ -101,7 +110,7 @@ describe('governance_presence checker', () => {
       path.join(tempDir, 'AGENTS.md'),
       '# AGENTS.md\n\n<!-- PRESERVE:governance -->\n\n<!-- /PRESERVE:governance -->\n'
     );
-    expect(await governancePresence.evaluate(makeEnv(tempDir))).toBe(false);
+    expect((await outcomeOf(tempDir)).satisfied).toBe(false);
   });
 
   it('PRESERVE:governance 标记未闭合视为不在场 → fail', async () => {
@@ -110,7 +119,7 @@ describe('governance_presence checker', () => {
       path.join(tempDir, 'AGENTS.md'),
       '# AGENTS.md\n\n<!-- PRESERVE:governance -->\n## Governance Rules\n内容\n'
     );
-    expect(await governancePresence.evaluate(makeEnv(tempDir))).toBe(false);
+    expect((await outcomeOf(tempDir)).satisfied).toBe(false);
   });
 });
 

package/src/core/constraints/checkers/__tests__/no-hardcoded-credentials.test.ts

@@ -12,11 +12,12 @@ import {
   containsHardcodedCredential,
 } from '../no-hardcoded-credentials';
 import type { CheckEnv } from '../types';
+import { createRunEnv } from '../../run-env';
 
 function makeEnv(stagedDiff: string): CheckEnv {
   return {
+    ...createRunEnv('/nonexistent'),
     context: { operation: 'commit', projectPath: '/nonexistent' },
-    projectPath: '/nonexistent',
     stagedDiff: async () => stagedDiff,
     stagedDiffNames: async () => '',
     srcScan: () => [],

package/src/core/constraints/checkers/capability-sync.ts

@@ -17,7 +17,9 @@
  *
  * 例外：「有表格但零条目」= 文档被清空，判违规（历史门，此前靠 Step 2 兜，现显式化）。
  *
- * 覆盖/漏登判定不在本文件实现，统一走 capabilities-reconcile（ADR-0009）：
+ * 覆盖/漏登判定不在本文件实现：全量对照（解析文档 + 代码实况 + 覆盖/幽灵）由
+ * capabilities-reconcile 一次算好并与 docs_freshness 共用（ADR-0009 + ADR-0023 决策 4），
+ * 本文件只按导出的唯一覆盖规则 `isCoveredByEntries` 算「本次变更」那一维（增量清单属 git 证据）。
  * 目录条目（以 / 结尾）前缀匹配，文件条目精确匹配或路径边界后缀匹配；
  * module 模式下目录条目参与覆盖，未覆盖文件按源码根下第一级子目录聚合。
  *
@@ -28,12 +30,15 @@
  * 不计 pass/fail，避免在未采用约定的项目上全量误报。
  */
 
-import { existsSync, readFileSync } from 'fs';
+import { existsSync } from 'fs';
 import { join } from 'path';
-import { isCapabilityListingFormat } from '../capabilities-parser';
 import { getCapabilitiesMode } from '../../project-config-loader';
-import { detectSourceRoots } from '../../../utils/detect-source-roots';
-import { reconcileCapabilities, significantCodeChanges } from '../capabilities-reconcile';
+import {
+  collectPopulationFiles,
+  isCoveredByEntries,
+  significantCodeChanges,
+} from '../capabilities-reconcile';
+import { CAPABILITIES_FILE_REL } from '../run-env';
 import { formatEvidence, type ConstraintCheck } from './types';
 
 export const capabilitySync: ConstraintCheck = {
@@ -41,41 +46,35 @@ export const capabilitySync: ConstraintCheck = {
   async evaluate(env) {
     const projectPath = env.projectPath;
     // ADR-0001 存在性探测：项目未采用 CAPABILITIES.md 约定 → skip（不计 pass/fail）
-    if (!existsSync(join(projectPath, 'CAPABILITIES.md'))) {
+    if (!existsSync(join(projectPath, CAPABILITIES_FILE_REL))) {
       return 'skip';
     }
     try {
-      const capabilitiesPath = join(projectPath, 'CAPABILITIES.md');
-      const content = readFileSync(capabilitiesPath, 'utf-8');
-      const capabilitiesMode = getCapabilitiesMode(projectPath);
+      const capabilitiesMode = getCapabilitiesMode(env);
+      // 文档原文 + 源码根 + 代码实况 + 对照判定 = run 内一份，与 docs_freshness 共用（ADR-0023 决策 4）
+      const caps = env.capabilities(
+        collectPopulationFiles(projectPath, env.sourceRoots(), (root) => env.srcScan(root))
+      );
+      if (!caps) return 'skip'; // 探测与取数之间文档消失：与上方同一语义
+      const verdict = caps.verdict;
 
       // 清单格式（计数行）没有文件表可核对，计数由 sync-docs 维护，直接放行
-      if (capabilitiesMode === 'listing' || isCapabilityListingFormat(content)) {
+      if (capabilitiesMode === 'listing' || verdict.listingFormat) {
         return true;
       }
 
-      const sourceRoots = detectSourceRoots(projectPath);
-      const population: string[] = [];
-      for (const root of sourceRoots) {
-        if (existsSync(join(projectPath, root))) {
-          population.push(...env.srcScan(root));
-        }
-      }
-
       const diffNames = (await env.stagedDiffNames()).split('\n').filter(Boolean);
-      const verdict = reconcileCapabilities({
-        content,
-        populationFiles: population,
-        changedFiles: significantCodeChanges(diffNames),
-        sourceRoots,
-      });
+      // 增量覆盖判定留在本文件：变更清单属 git 证据（#87），不在上行数据面
+      const uncoveredChanges = significantCodeChanges(diffNames).filter(
+        (f) => !isCoveredByEntries(verdict.coverageEntries, f)
+      );
 
       // 无表格的散文文档：历史放行语义
       if (!verdict.hasTable) return true;
 
       // 文档退化门：有表格却什么都没登记（限定「源码根下确有文件」——空仓 + 空表没有可登记
       // 对象，历史行为是放行，本票不顺手扩大 fail 面）
-      if (verdict.coverageEntries.length === 0 && population.length > 0) {
+      if (verdict.coverageEntries.length === 0 && caps.populationFiles.length > 0) {
         return {
           pass: false,
           evidence: ['CAPABILITIES.md 有表格但零条目登记，运行 harness sync-docs 或直接补登记'],
@@ -83,12 +82,12 @@ export const capabilitySync: ConstraintCheck = {
       }
 
       // ── Step 1: Git diff 增量检查（与本次变更有因果，每个变更文件都必须被覆盖）──
-      if (verdict.uncoveredChanges.length > 0) {
+      if (uncoveredChanges.length > 0) {
         return {
           pass: false,
           evidence: formatEvidence(
-            `本次变更有 ${verdict.uncoveredChanges.length} 个文件未登记进 CAPABILITIES.md`,
-            verdict.uncoveredChanges
+            `本次变更有 ${uncoveredChanges.length} 个文件未登记进 CAPABILITIES.md`,
+            uncoveredChanges
           ),
         };
       }

package/src/core/constraints/checkers/context-doc-sync.ts

@@ -10,22 +10,24 @@
 import { existsSync } from 'fs';
 import { join } from 'path';
 import { resolveContextFiles } from '../../project-config-loader';
-import type { ConstraintCheck } from './types';
+import { formatEvidence, type ConstraintCheck } from './types';
 
 export const contextDocSync: ConstraintCheck = {
   id: 'context_doc_sync',
   async evaluate(env) {
     const projectPath = env.projectPath;
-    const resolution = resolveContextFiles(projectPath);
+    const resolution = resolveContextFiles(env);
     if (resolution.state !== 'enabled') {
       return 'skip'; // 未配置或约定已立但无目标，跳过评估
     }
 
-    for (const dir of resolution.dirs) {
-      const contextPath = join(projectPath, dir, 'CONTEXT.md');
-      if (!existsSync(contextPath)) {
-        return false;
-      }
+    // 证据随判定一并返回（ADR-0016 补迁）：此前只回裸 false，
+    // 多个 required_dirs 里到底哪个没落 CONTEXT.md，CLI 与 trace 两头都看不出来
+    const missing = resolution.dirs
+      .map(dir => join(dir, 'CONTEXT.md'))
+      .filter(rel => !existsSync(join(projectPath, rel)));
+    if (missing.length > 0) {
+      return { pass: false, evidence: formatEvidence('关键目录缺 CONTEXT.md', missing) };
     }
 
     return true;

package/src/core/constraints/checkers/docs-freshness.ts

@@ -7,12 +7,12 @@
  * 3. 无配置时注入内置默认配置（等价旧硬编码行为）
  */
 
-import { existsSync, readFileSync } from 'fs';
+import { existsSync } from 'fs';
 import { join } from 'path';
 import { getGovernanceConfig, resolveContextFiles } from '../../project-config-loader';
 import { FreshnessRunner, type FreshnessCheckResult } from '../doc-freshness/runner';
-import { detectSourceRoots } from '../../../utils/detect-source-roots';
-import { reconcileCapabilities } from '../capabilities-reconcile';
+import { collectPopulationFiles } from '../capabilities-reconcile';
+import { CAPABILITIES_FILE_REL } from '../run-env';
 import type { DocFreshnessCheck } from '../../../types/project-config';
 import type { ConstraintCheck, CheckEnv } from './types';
 import { formatEvidence } from './types';
@@ -33,28 +33,19 @@ function getBuiltInDocFreshnessConfig(): DocFreshnessCheck[] {
 
 /**
  * CAPABILITIES.md 文件表新鲜度：登记的条目（文件与目录）必须仍存在（ADR-0009 口径从严）。
- * 判定逻辑统一走 capabilities-reconcile；多根查找支持不同项目的源码根
- * （harness=src/, studio=apps/api/src/ 等）。无表格（能力清单格式）时自然零幽灵。
+ * 判定逻辑与取数都在 run 级：文档原文、源码根、代码实况清单、对照判定一次算好，
+ * 与 capability_sync 共用同一份（ADR-0023 决策 4；此前两边各读一遍、各解析一遍）。
+ * 无表格（能力清单格式）时自然零幽灵。
  */
-function findDeadCapabilityEntries(projectPath: string, env: CheckEnv): string[] {
+function findDeadCapabilityEntries(env: CheckEnv): string[] {
   try {
-    const capabilitiesPath = join(projectPath, 'CAPABILITIES.md');
-    if (!existsSync(capabilitiesPath)) return [];
-    const content = readFileSync(capabilitiesPath, 'utf-8');
-
-    const sourceRoots = detectSourceRoots(projectPath);
-    const population: string[] = [];
-    for (const root of sourceRoots) {
-      if (existsSync(join(projectPath, root))) population.push(...env.srcScan(root));
-    }
-
-    const verdict = reconcileCapabilities({
-      content,
-      populationFiles: population,
-      sourceRoots,
-      fileExists: (rel) => existsSync(join(projectPath, rel)),
-    });
-    return verdict.deadEntries;
+    // 先探存在性再取数：只有 CHANGELOG 而无 CAPABILITIES.md 的项目不该为此扫一遍源码树
+    if (!existsSync(join(env.projectPath, CAPABILITIES_FILE_REL))) return [];
+    const population = collectPopulationFiles(env.projectPath, env.sourceRoots(), (root) =>
+      env.srcScan(root)
+    );
+    const caps = env.capabilities(population);
+    return caps ? caps.verdict.deadEntries : [];
   } catch {
     return [];
   }
@@ -71,18 +62,19 @@ function findDeadCapabilityEntries(projectPath: string, env: CheckEnv): string[]
  *
  * 全部缺失 → 项目未采用该约定，调用方应 skip 而非评估内置默认配置。
  */
-function hasFreshnessTargets(projectPath: string): boolean {
-  if (existsSync(join(projectPath, 'CAPABILITIES.md'))) return true;
+function hasFreshnessTargets(env: CheckEnv): boolean {
+  const projectPath = env.projectPath;
+  if (existsSync(join(projectPath, CAPABILITIES_FILE_REL))) return true;
   if (existsSync(join(projectPath, 'CHANGELOG.md')) || existsSync(join(projectPath, 'CHANGELOG'))) {
     return true;
   }
 
-  const governance = getGovernanceConfig(projectPath);
+  const governance = getGovernanceConfig(env);
   if (governance?.doc_freshness?.checks && governance.doc_freshness.checks.length > 0) {
     return true;
   }
 
-  return resolveContextFiles(projectPath).state === 'enabled';
+  return resolveContextFiles(env).state === 'enabled';
 }
 
 export const docsFreshness: ConstraintCheck = {
@@ -91,10 +83,10 @@ export const docsFreshness: ConstraintCheck = {
     const projectPath = env.projectPath;
 
     // ADR-0001 存在性探测：项目无任何 freshness 配置/目标 → skip（不计 pass/fail）
-    if (!hasFreshnessTargets(projectPath)) return 'skip';
+    if (!hasFreshnessTargets(env)) return 'skip';
 
     // Step 1: 文件表格式 — 登记的条目（文件+目录）是否仍存在（ADR-0009）
-    const deadEntries = findDeadCapabilityEntries(projectPath, env);
+    const deadEntries = findDeadCapabilityEntries(env);
     if (deadEntries.length > 0) {
       // 证据通道点名条目（harness#119）：此前是 console.error 侧信道（2026-08-08 studio
       // CI 4 连红时的临时办法），CLI 结构化输出与 trace 两头都拿不到，
@@ -107,11 +99,11 @@ export const docsFreshness: ConstraintCheck = {
 
     // Step 2: 能力清单格式 + CLAUDE.md + CHANGELOG — 通过 FreshnessRunner
     try {
-      const freshnessConfig = getGovernanceConfig(projectPath)?.doc_freshness;
+      const freshnessConfig = getGovernanceConfig(env)?.doc_freshness;
 
       // context_files 三态统一口径（工单 84）：约定已立但无目标（enabled 但
       // required_dirs 缺失/空）→ skip，与 context_doc_sync 同构；不再静默放行
-      const contextFiles = resolveContextFiles(projectPath);
+      const contextFiles = resolveContextFiles(env);
       if (contextFiles.state === 'enabled-empty') return 'skip';
       const requiredDirs = contextFiles.state === 'enabled' ? contextFiles.dirs : undefined;
 
@@ -119,9 +111,12 @@ export const docsFreshness: ConstraintCheck = {
       let results: FreshnessCheckResult[];
 
       if (freshnessConfig?.checks && freshnessConfig.checks.length > 0) {
-        results = runner.runAll(freshnessConfig, projectPath, { requiredDirs });
+        results = runner.runAll(freshnessConfig, projectPath, { requiredDirs, sourceRoots: () => env.sourceRoots() });
       } else {
-        results = runner.runAll({ checks: getBuiltInDocFreshnessConfig() }, projectPath, { requiredDirs });
+        results = runner.runAll({ checks: getBuiltInDocFreshnessConfig() }, projectPath, {
+          requiredDirs,
+          sourceRoots: () => env.sourceRoots(),
+        });
       }
 
       const failed = results.filter(r => !r.pass);

package/src/core/constraints/checkers/governance-presence.ts

@@ -38,7 +38,7 @@ export const governancePresence: ConstraintCheck = {
     // 存在性探测：无 harness 配置 = 未采用治理约定 → skip（不计 pass/fail）
     let adopted = false;
     try {
-      adopted = loadRawProjectConfig(projectPath) !== undefined;
+      adopted = loadRawProjectConfig(env) !== undefined;
     } catch {
       adopted = false;
     }
@@ -47,10 +47,14 @@ export const governancePresence: ConstraintCheck = {
     if (hasGovernancePreserveBlock(join(projectPath, 'AGENTS.md'))) return true;
     if (hasClaudeGovernance(join(projectPath, 'CLAUDE.md'))) return true;
 
-    console.error(
-      '[governance_presence] 治理契约缺失：AGENTS.md 无非空 PRESERVE:governance 段，' +
-      '且 CLAUDE.md 无 Governance Rules 块——约束正本静默丢失，请恢复其一'
-    );
-    return false;
+    // 证据随判定一并返回（ADR-0016 补迁）：此前这里是 console.error 侧信道——
+    // 只进本地 stderr，进不了 CLI 结论块与 trace，铁律拦截时用户看不到该恢复哪个正本
+    return {
+      pass: false,
+      evidence: [
+        '治理契约缺失：AGENTS.md 无非空 PRESERVE:governance 段，CLAUDE.md 也无 Governance Rules 块（正本静默丢失）',
+        '修复: 恢复其一（重跑 `harness init` 会同步注入段）',
+      ],
+    };
   },
 };

package/src/core/constraints/checkers/types.ts

@@ -6,18 +6,20 @@
  */
 
 import type { ConstraintContext } from '../../../types/constraint';
+import { createRunEnv, type RunEnv } from '../run-env';
 
 /**
- * 检查环境：单次 run 内共享的上下文与 memoized I/O
+ * 检查环境：一次 run 内共享的观察面与证据提供者（ADR-0023 决策 1）
  *
- * - stagedDiff/stagedDiffNames：run 内 git 命令至多一次（工单 18）
+ * = `RunEnv`（项目上行数据的读取：config.yml / trace 尾部 / 源根，run 内至多一次）
+ *   + `context` + git/扫描证据。前者不含 context，故只能派生不能合并成一个对象。
+ *
+ * - stagedDiff/stagedDiffNames：run 内 git 命令至多一次（工单 18 / #87）
  * - srcScan：run 内同根源码扫描至多一次（CheckCache）
  */
-export interface CheckEnv {
+export interface CheckEnv extends RunEnv {
   /** 约束上下文（operation/changedFiles/各类证据标志） */
   context: ConstraintContext;
-  /** 项目根路径（context.projectPath || process.cwd()） */
-  projectPath: string;
   /** staged 全量 diff（run 内 memoized） */
   stagedDiff(): Promise<string>;
   /** staged 变更文件名列表（run 内 memoized） */
@@ -48,24 +50,28 @@ export interface EvidenceProviders {
  * - 'none' = 显式不接证据：证据函数返回空；evidence flag 未接线的
  *   checker 按契约返回 'skip'（见 contextEvidenceFlag），直接读空
  *   证据的 checker 在自然输入下判定
+ * - runEnv = 本 run 的运行级观察面（ADR-0023）：传入即与 context-builder 及
+ *   其余 checker 共用同一份上行数据读取；不传则自造一枚，只服务本次调用
  *
  * studio 侧若需 git 证据（#129），传真实 providers 即可。
  */
 export function buildCheckEnv(
   context: ConstraintContext,
-  evidence: EvidenceProviders | 'none'
+  evidence: EvidenceProviders | 'none',
+  runEnv?: RunEnv
 ): CheckEnv {
   const projectPath = context.projectPath || process.cwd();
+  const run = runEnv ?? createRunEnv(projectPath);
   if (evidence === 'none') {
     return {
+      ...run,
       context,
-      projectPath,
       stagedDiff: async () => '',
       stagedDiffNames: async () => '',
       srcScan: () => [],
     };
   }
-  return { context, projectPath, ...evidence };
+  return { ...run, context, ...evidence };
 }
 
 /**

package/src/core/constraints/context-builder.ts

@@ -8,14 +8,16 @@
  * 架构评审 #87：本模块只做装配不做取证——git 证据一律经 git-evidence
  * adapter 取（缺省真 git adapter，调用方可注入与 checker 层同源的那一份），
  * 因此此处不再有 child_process / raw execSync。
+ *
+ * ADR-0023：同理，trace 记录与源码根探测改经运行级观察面 `RunEnv` 取——
+ * 此前本模块的两个证据探测各自整读一次 traces.log、detectTrigger 与 checker 层
+ * 各探一次源码根，同一次运行内重复读同一批文件。缺省自造一份 env，调用方（CLI check）
+ * 注入即全 run 共用。
  */
 
 import * as fs from 'fs';
 import * as path from 'path';
-import { detectSourceRoots } from '../../utils/detect-source-roots';
-import { readJsonl } from '../../utils/jsonl';
-import { DEFAULT_TRACE_FILE } from '../../types/trace';
-import type { ExecutionTrace } from '../../types/trace';
+import { createRunEnv, TRACE_TAIL_WINDOW, type RunEnv } from './run-env';
 import type { ConstraintContext, ConstraintTrigger } from '../../types/constraint';
 import { createGitEvidence, splitFileNames, type GitEvidence } from './git-evidence';
 
@@ -51,6 +53,8 @@ export function detectTrigger(
     trigger?: ConstraintTrigger;
     projectPath?: string;
     evidence?: GitEvidence;
+    /** 运行级观察面（ADR-0023）：注入即与其余消费方共用同一份源根探测 */
+    runEnv?: RunEnv;
   }
 ): ConstraintTrigger | ConstraintTrigger[] {
   if (options.trigger) return options.trigger;
@@ -62,7 +66,7 @@ export function detectTrigger(
   // pre-commit 场景下变更含代码文件 → 附加 code_implementation 推断
   const hasCodeChange = changedFiles.some(f => CODE_FILE_REGEX.test(f));
   const projectPath = options.projectPath || process.cwd();
-  const sourceRoots = detectSourceRoots(projectPath);
+  const sourceRoots = (options.runEnv ?? createRunEnv(projectPath)).sourceRoots();
   const hasModuleChange = changedFiles.some(f =>
     sourceRoots.some(root => f.startsWith(root + '/') || f.startsWith(root + '\\')) && !f.includes('__tests__')
   );
@@ -85,17 +89,14 @@ export function detectTrigger(
 }
 
 /**
- * 检测是否有失败的测试记录
- * 扫描 trace 文件（DEFAULT_TRACE_FILE）中最近的记录
+ * 检测是否有失败的测试记录（取运行级观察面的最近 20 条）
  */
-export async function detectFailingTest(projectPath: string): Promise<boolean> {
+async function detectFailingTest(env: RunEnv): Promise<boolean> {
   try {
-    const traceFile = path.join(projectPath, DEFAULT_TRACE_FILE);
-    // 坏行策略：skip（原逐行 catch→false 语义不变）；只 parse 最近 20 行
-    // 计数去向：豁免（harness#100）——布尔证据探测，坏行只会让证据变少（判定方向保守），
-    // 消费面是 check 的 pass/fail 判定，没有可挂计数的输出位
-    const { records } = readJsonl<ExecutionTrace>(traceFile, 'skip', { tail: 20 });
-    return records.some(trace => trace.result === 'fail');
+    // 坏行策略与计数去向见 run-env 的读点（ADR-0023 合并两处独立 tail 读为一份窗口）
+    return env
+      .traceTail(TRACE_TAIL_WINDOW)
+      .records.some(trace => trace.result === 'fail');
   } catch {
     return false;
   }
@@ -123,19 +124,18 @@ export function detectRootCauseInvestigation(projectPath: string): boolean {
   return false;
 }
 
+/** 验证证据的尾部窗口（工单 23 原口径：只看最近 10 条） */
+const VERIFICATION_EVIDENCE_TAIL = 10;
+
 /**
- * 检测是否有验证证据
- * 检查 trace 文件（DEFAULT_TRACE_FILE）中最近的成功验证记录
+ * 检测是否有验证证据（取运行级观察面的最近 10 条）
  */
-export async function detectVerificationEvidence(projectPath: string): Promise<boolean> {
+async function detectVerificationEvidence(env: RunEnv): Promise<boolean> {
   try {
-    const traceFile = path.join(projectPath, DEFAULT_TRACE_FILE);
-    // 坏行策略：skip（原逐行 catch→false 语义不变）；只 parse 最近 10 行
     // tail 在 parse 之前截断 → 坏行会占用尾部槽位（#82 裁决范围外的既有口径，本票不改）
-    // 计数去向：豁免（harness#100）——同 detectFailingTest：布尔证据探测无计数输出位，
-    // 坏行只会让证据变少
-    const { records } = readJsonl<ExecutionTrace>(traceFile, 'skip', { tail: 10 });
-    return records.some(trace => trace.result === 'pass');
+    return env
+      .traceTail(VERIFICATION_EVIDENCE_TAIL)
+      .records.some(trace => trace.result === 'pass');
   } catch {
     return false;
   }
@@ -191,17 +191,26 @@ export function detectReuseCheck(projectPath: string): boolean {
  *
  * options.evidence（#87）：git 证据适配器。调用方（CLI check）注入同一实例给
  * checkConstraints，即可让 context-builder 与 checker 层共用同一证据来源。
+ * options.runEnv（ADR-0023）：运行级观察面。注入即本函数内的源根探测与两处 trace
+ * 证据探测与其余消费方共用同一份读取，缺省自造一份（只服务本次调用）。
  */
 export async function buildConstraintContext(options: {
   projectPath?: string;
   staged: boolean;
   trigger?: ConstraintTrigger;
   evidence?: GitEvidence;
+  runEnv?: RunEnv;
 }): Promise<ConstraintContext> {
   const projectPath = options.projectPath || process.cwd();
+  const runEnv = options.runEnv ?? createRunEnv(projectPath);
   const evidence = options.evidence ?? createGitEvidence(projectPath);
   const changedFiles = splitFileNames(evidence.changedFileNames(options.staged));
-  const inferred = detectTrigger(changedFiles, { trigger: options.trigger, projectPath, evidence });
+  const inferred = detectTrigger(changedFiles, {
+    trigger: options.trigger,
+    projectPath,
+    evidence,
+    runEnv,
+  });
   const triggers = Array.isArray(inferred) ? inferred : [inferred];
 
   return {
@@ -210,9 +219,9 @@ export async function buildConstraintContext(options: {
     projectPath,
     changedFiles,
     hasTest: changedFiles.some(f => f.includes('.test.') || f.includes('.spec.')),
-    hasFailingTest: await detectFailingTest(projectPath),
+    hasFailingTest: await detectFailingTest(runEnv),
     hasRootCauseInvestigation: detectRootCauseInvestigation(projectPath),
-    hasVerificationEvidence: await detectVerificationEvidence(projectPath),
+    hasVerificationEvidence: await detectVerificationEvidence(runEnv),
     hasReuseCheck: detectReuseCheck(projectPath),
     hasRequirement: detectRequirement(projectPath),
   };