@dommaker/harness 1.7.0 → 1.8.0

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

@@ -0,0 +1,200 @@
+/**
+ * CONTEXT.md「核心导出」节与目录导出面的对照判定（harness#142 / ADR-0025）
+ *
+ * 纯判定 module：吃「CONTEXT.md 正文 + 目录导出面清单（+ barrel 值符号清单）」，
+ * 一次产出双向判定；不做任何 fs IO——文件遍历、正文读取、`export *` 目标解析
+ * 全在调用方（cli 侧），与 ADR-0009 的 capabilities-reconcile 同一套组装形状。
+ *
+ * 方向（语义与 capabilities-reconcile 对齐：幽灵 = 文档说谎，未登记 = 代码有而文档漏）：
+ *   文档→代码  ghosts（「核心导出」节声明的符号在目录导出面里不存在）
+ *   代码→文档  unlistedBarrelExports（index.ts 再导出的值符号未出现在该节）
+ *
+ * 口径（ADR-0025，两条都是「可操作」而非「越严越好」的取舍）：
+ * - 声明只取 bullet **行首**的反引号标识符（`/` 连接的多符号逐个取，形参列表与
+ *   `（type）`注解剥掉）。行首不是标识符的 bullet 是模块/目录条目
+ *   （`types.ts`、`audit-scoring`、`constraints/`），不属符号声明面，整条跳过。
+ * - 覆盖方向只管 barrel 的**值**符号：类型面（interface/type）不要求逐个登记
+ *   ——否则每次加一个公开类型都要回灌文档，正是本闸要避免的「连注释都要改」。
+ *   类型-only 的剔除在采集侧（读得懂 `export type { }` 与声明关键字的那一层）。
+ * - 「出现在该节」按标识符边界匹配（inline 提及即算登记），bullet 行首之外的正文同样参与，
+ *   但**其它 `## ` 节**的正文不参与——绕过闸需要把符号塞进「核心导出」节，而不是塞满全文件。
+ */
+
+/** markdown「## 核心导出」节标题（其后括注允许，如 `## 核心导出 (dist/)`） */
+const SECTION_HEADING_REGEX = /^##\s*核心导出/;
+/** 任意二级标题：节的终点（三级标题属节内子结构，不终止） */
+const H2_HEADING_REGEX = /^##\s/;
+/** bullet 行 */
+const BULLET_REGEX = /^\s*[-*]\s*(.*)$/;
+/** bullet 行首（及 `/` 连接的后续）反引号片段 */
+const LEADING_BACKTICK_REGEX = /^`([^`]+)`/;
+/** token 间的 `/` 分隔（可含空白）+ 下一个反引号起点 */
+const NEXT_TOKEN_REGEX = /^(?:\s*\/\s*)?\s*`/;
+/** 合法导出标识符 */
+const IDENTIFIER_REGEX = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+/** 源码导出声明：`export [默认] [形式] 名字` 与 `export { … } [from '…']` */
+const DECLARATION_REGEX =
+  /^export\s+(?:declare\s+)?(?:abstract\s+)?(?:async\s+)?(function|const|let|var|class|interface|type|enum)\s+([A-Za-z_$][\w$]*)/gm;
+/** `export { … }` / `export type { … }`（可带 from） */
+const EXPORT_LIST_REGEX = /^export\s+(type\s+)?\{([^}]*)\}(?:\s*from\s*['"]([^'"]+)['"])?/gm;
+/** `export * from '…'` / `export * as ns from '…'` */
+const STAR_EXPORT_REGEX = /^export\s+\*\s*(?:as\s+[A-Za-z_$][\w$]*\s*)?from\s*['"]([^'"]+)['"]/gm;
+
+export interface ExportedSymbol {
+  /** 导出名（`a as b` 取 b） */
+  name: string;
+  /** 来源侧的本名（`a as b` 取 a；自身声明与无别名再导出时等于 name）——调用方按它核对正本是否真有此物 */
+  localName: string;
+  /** 类型-only（interface/type 声明、`export type { }` 块、逐项 `type` 标记） */
+  typeOnly: boolean;
+  /** 再导出的来源 spec（`from './x'`），模块自身声明为 undefined */
+  from?: string;
+}
+
+export interface ExportStatementParse {
+  symbols: ExportedSymbol[];
+  /** 待调用方解析的 `export *` 目标 spec（fs 侧才知道文件在不在） */
+  starFrom: string[];
+}
+
+export interface ContextReconcileInput {
+  /** CONTEXT.md 全文 */
+  contextMdContent: string;
+  /** 目录导出面全集：目录内所有 .ts 导出的符号名（值 + 类型，含 barrel 与内部 seam） */
+  exportSurface: string[];
+  /** index.ts barrel 再导出的**值**符号清单；无 index.ts 的目录不传（跳过覆盖方向） */
+  barrelExports?: string[];
+}
+
+export interface ContextVerdict {
+  /** 文档是否含「## 核心导出」节；无节 = 两方向都不参与判定 */
+  hasCoreExportsSection: boolean;
+  /** 该节解析出的符号声明（去重、按出现序） */
+  declaredSymbols: string[];
+  /** 幽灵：声明了但目录导出面没有 */
+  ghosts: string[];
+  /** 未登记：barrel 值符号未出现在该节 */
+  unlistedBarrelExports: string[];
+}
+
+/**
+ * 取「## 核心导出」节正文（不含标题行），到下一个二级标题为止。
+ * 无该节 → null。
+ */
+export function parseCoreExportsSection(content: string): string | null {
+  const lines = content.split(/\r?\n/);
+  const start = lines.findIndex((line) => SECTION_HEADING_REGEX.test(line));
+  if (start === -1) return null;
+
+  const body: string[] = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    if (H2_HEADING_REGEX.test(lines[i])) break;
+    body.push(lines[i]);
+  }
+  return body.join('\n');
+}
+
+/** 反引号片段 → 导出符号名；剥形参列表与 `type` 关键字前缀，非标识符返回 null */
+function toSymbolName(token: string): string | null {
+  const bare = token.replace(/[（(].*$/, '').trim();
+  const withoutKeyword = /^type\s+/.test(bare) ? bare.replace(/^type\s+/, '').trim() : bare;
+  return IDENTIFIER_REGEX.test(withoutKeyword) ? withoutKeyword : null;
+}
+
+/**
+ * 解析「## 核心导出」节的符号声明：只认 bullet 行首的反引号标识符
+ * （`/` 连接视为多个声明，其后的散文与 inline 提及不参与幽灵判定）。
+ */
+export function parseDeclaredExportSymbols(content: string): string[] {
+  const section = parseCoreExportsSection(content);
+  if (section === null) return [];
+
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const line of section.split(/\r?\n/)) {
+    const bullet = BULLET_REGEX.exec(line);
+    if (!bullet) continue;
+
+    let rest = bullet[1];
+    for (;;) {
+      const token = LEADING_BACKTICK_REGEX.exec(rest);
+      if (!token) break;
+      const name = toSymbolName(token[1]);
+      if (name && !seen.has(name)) {
+        seen.add(name);
+        out.push(name);
+      }
+      rest = rest.slice(token[0].length);
+      const separator = NEXT_TOKEN_REGEX.exec(rest);
+      if (!separator) break;
+      rest = rest.slice(separator[0].length - 1);
+    }
+  }
+  return out;
+}
+
+/**
+ * 解析单个源文件的导出面（口径正本，采集侧与测试共用）：
+ * 声明形、`export { }` 列表形（含别名与逐项 `type`）、`export default`、`export *`。
+ * 只做正则解析，不解析 spec 指向谁——那是调用方的 fs 活。
+ */
+export function parseExportStatements(source: string): ExportStatementParse {
+  const symbols: ExportedSymbol[] = [];
+
+  for (const match of source.matchAll(DECLARATION_REGEX)) {
+    symbols.push({
+      name: match[2],
+      localName: match[2],
+      typeOnly: match[1] === 'interface' || match[1] === 'type',
+    });
+  }
+
+  for (const match of source.matchAll(EXPORT_LIST_REGEX)) {
+    const blockIsType = Boolean(match[1]);
+    const from = match[3];
+    for (const part of match[2].split(',')) {
+      const specifier = part.trim();
+      if (!specifier || specifier === 'default') continue;
+      const typeOnly = blockIsType || /^type\s+/.test(specifier);
+      const cleaned = specifier.replace(/^type\s+/, '').trim();
+      const aliased = /^([A-Za-z_$][\w$]*)\s+as\s+([A-Za-z_$][\w$]*)$/.exec(cleaned);
+      const single = /^([A-Za-z_$][\w$]*)$/.exec(cleaned);
+      if (aliased) symbols.push({ name: aliased[2], localName: aliased[1], typeOnly, ...(from ? { from } : {}) });
+      else if (single) symbols.push({ name: single[1], localName: single[1], typeOnly, ...(from ? { from } : {}) });
+    }
+  }
+
+  if (/^export\s+default\b/m.test(source)) {
+    symbols.push({ name: 'default', localName: 'default', typeOnly: false });
+  }
+
+  return {
+    symbols,
+    starFrom: [...source.matchAll(STAR_EXPORT_REGEX)].map((m) => m[1]),
+  };
+}
+
+/** 符号是否在该节正文中出现（标识符边界匹配） */
+function mentionedInSection(section: string, symbol: string): boolean {
+  const escaped = symbol.replace(/[$]/g, '\\$');
+  return new RegExp(`(?<![\\w$])${escaped}(?![\\w$])`).test(section);
+}
+
+/**
+ * CONTEXT.md 与目录导出面的双向判定（唯一真相源，sync-docs 与任何后续消费方共用）。
+ */
+export function reconcileContext(input: ContextReconcileInput): ContextVerdict {
+  const section = parseCoreExportsSection(input.contextMdContent);
+  const hasCoreExportsSection = section !== null && section.trim() !== '';
+  const declaredSymbols = parseDeclaredExportSymbols(input.contextMdContent);
+  const surface = new Set(input.exportSurface);
+  const ghosts = declaredSymbols.filter((symbol) => !surface.has(symbol));
+
+  const barrelExports = [...new Set(input.barrelExports ?? [])];
+  const unlistedBarrelExports = hasCoreExportsSection
+    ? barrelExports.filter((symbol) => !mentionedInSection(section as string, symbol))
+    : [];
+
+  return { hasCoreExportsSection, declaredSymbols, ghosts, unlistedBarrelExports };
+}

package/src/core/constraints/doc-freshness/__tests__/runner.test.ts

@@ -248,6 +248,31 @@ describe('FreshnessRunner', () => {
       expect(results[0].message).toContain('unlisted');
     });
 
+    it('推不出任何根时用调用方注入的源码根兜底，本模块不再自探（ADR-0023 决策 4）', () => {
+      setupFixture('dirdir-roots-injected', {
+        // 条目是单段目录 `src`：docDirs 非空（否则会先走「未找到目录引用」早退），
+        // 但推不出任何根（根 = 去掉最后一段），落到兜底分支
+        'CLAUDE.md': ['## Key Subsystems', '', '| `src` | Core |'].join('\n'),
+      });
+      mkdirSync(join(TEST_ROOT, 'dirdir-roots-injected', 'src'), { recursive: true });
+      mkdirSync(join(TEST_ROOT, 'dirdir-roots-injected', 'lib', 'nested'), { recursive: true });
+
+      let injectedCalls = 0;
+      const config: DocFreshnessConfig = {
+        checks: [{ type: 'doc_dir_check', doc: 'CLAUDE.md', section: 'Key Subsystems' }],
+      };
+      const results = runner.runAll(config, join(TEST_ROOT, 'dirdir-roots-injected'), {
+        sourceRoots: () => {
+          injectedCalls++;
+          return ['lib'];
+        },
+      });
+
+      expect(injectedCalls).toBe(1);
+      expect(results[0].pass).toBe(false);
+      expect(results[0].message).toContain('lib/nested');
+    });
+
     it('passes for uncovered dir when skip_reverse_check is set', () => {
       setupFixture('dirdir-skip-reverse', {
         'CLAUDE.md': [

package/src/core/constraints/doc-freshness/runner.ts

@@ -41,6 +41,12 @@ interface RunContext {
   projectPath: string;
   /** 外部提供的 required_dirs（来自 governance.context_files，用于 context_docs 检查的默认 dirs） */
   requiredDirs?: string[];
+  /**
+   * 源码根的**懒取**提供者（ADR-0023 决策 4）：只在 doc_dir_check 从文档目录
+   * 推断不出根时用到。调用方传 `() => env.sourceRoots()` 即与本 run 其余消费方
+   * 共用一次探测；不传（sync-docs 等一次性调用方）则本模块自探一次。
+   */
+  sourceRoots?: () => string[];
   /** 外部提供的约束计数（用于内置 harner harness 的 doc_regex_count） */
   constraintCounts?: {
     ironLaws?: number;
@@ -58,7 +64,11 @@ export class FreshnessRunner {
   runAll(
     config: DocFreshnessConfig,
     projectPath: string,
-    ctx?: { requiredDirs?: string[]; constraintCounts?: { ironLaws?: number; guidelines?: number } }
+    ctx?: {
+      requiredDirs?: string[];
+      sourceRoots?: () => string[];
+      constraintCounts?: { ironLaws?: number; guidelines?: number };
+    }
   ): FreshnessCheckResult[] {
     if (config.enabled === false) return [];
     if (!config.checks || config.checks.length === 0) return [];
@@ -66,6 +76,7 @@ export class FreshnessRunner {
     const context: RunContext = {
       projectPath,
       requiredDirs: ctx?.requiredDirs,
+      sourceRoots: ctx?.sourceRoots,
       constraintCounts: ctx?.constraintCounts,
     };
 
@@ -238,7 +249,7 @@ export class FreshnessRunner {
       // 2. fs → doc: 每个实际目录必须在文档中被覆盖
       if (!check.skip_reverse_check) {
         // 从文档目录中推断要扫描的根目录集
-        const rootDirs = this.inferRootDirs(docDirs, ctx.projectPath);
+        const rootDirs = this.inferRootDirs(docDirs, ctx);
         const excludeSet = new Set(check.exclude || DEFAULT_SKIP_DIRS);
 
         for (const rootDir of rootDirs) {
@@ -287,7 +298,7 @@ export class FreshnessRunner {
    * 从文档目录集合推断要扫描的根目录
    * 例如 ["src/core", "src/cli/commands"] → ["src"]
    */
-  private inferRootDirs(docDirs: Set<string>, projectPath: string): string[] {
+  private inferRootDirs(docDirs: Set<string>, ctx: RunContext): string[] {
     const roots = new Set<string>();
 
     for (const dir of docDirs) {
@@ -315,7 +326,10 @@ export class FreshnessRunner {
       }
     }
 
-    return merged.size > 0 ? [...merged] : detectSourceRoots(projectPath);
+    if (merged.size > 0) return [...merged];
+    // 兜底 = 文档一个目录条目都没登记：按项目实际源码根全量比对（删掉它等于静默放行空文档）。
+    // 取根优先用调用方注入的懒取 provider（与本 run 其余消费方共用一次探测，ADR-0023 决策 4）
+    return ctx.sourceRoots ? ctx.sourceRoots() : detectSourceRoots(ctx.projectPath);
   }
 
   // ── doc_regex_count ──────────────────────────────────────────────

package/src/core/constraints/git-evidence.ts

@@ -43,7 +43,7 @@ export interface GitEvidence {
   headDirs(): Set<string> | null;
 }
 
-/** 与 utils/exec.runCommand 同一缓冲上限（大 diff 不 ENOBUFS） */
+/** 大 diff 不 ENOBUFS 的缓冲上限（1MB） */
 const GIT_MAX_BUFFER = 1024 * 1024;
 
 /**

package/src/core/constraints/injection-drift.ts

@@ -18,7 +18,9 @@
  */
 
 import * as path from 'path';
+import type { Constraint } from '../../types/constraint';
 import { getEffectiveConstraints } from '../effective-constraints';
+import { resolveRunEnv, type RunTarget } from './run-env';
 import { getHarnessPackageVersion } from '../../utils/package-version';
 import { CONSTRAINTS_END_MARKER, renderConstraintsSection } from './injection-renderer';
 import {
@@ -72,13 +74,19 @@ function significantLines(section: string): string[] {
 /**
  * 检测约束注入段漂移
  *
- * @param projectRoot 项目根路径
+ * @param target 项目根路径，或本 run 的运行级观察面（CLI check 传入即与本 run 共用
+ *   同一份 config.yml 读取，漂移侧的生效集计算不再重读文件——ADR-0023 决策 2）
  * @param currentVersion 当前 harness 版本（缺省经 getHarnessPackageVersion 正本读取；测试可显式传入）
+ * @param expectedConstraints 本 run 已算好的生效集（CLI check 传入 → 生效集链路一次运行只算
+ *   一遍，且比对用的就是本 run 实际执法的那份）。不传则按 target 自取，行为与改前逐字一致
  */
 export function detectInjectionDrift(
-  projectRoot: string,
-  currentVersion: string = getHarnessPackageVersion()
+  target: RunTarget,
+  currentVersion: string = getHarnessPackageVersion(),
+  expectedConstraints?: Constraint[]
 ): InjectionDrift {
+  const env = resolveRunEnv(target);
+  const projectRoot = env.projectPath;
   const result: InjectionDrift = {
     hasDrift: false,
     notInjected: false,
@@ -86,8 +94,8 @@ export function detectInjectionDrift(
     fixHint: INJECTION_DRIFT_FIX_HINT,
   };
 
-  const target = resolveInjectionTarget(projectRoot);
-  if (!target) {
+  const injected = resolveInjectionTarget(projectRoot);
+  if (!injected) {
     // 两处均无标记段 = 未注入，不算漂移（check 不警告）。
     // 重复章节仍如实记录供 report 提示：旧落点 CLAUDE.md 优先，其次 AGENTS.md。
     const legacy =
@@ -100,8 +108,8 @@ export function detectInjectionDrift(
     return result;
   }
 
-  result.injectionFile = target.file;
-  const { content, startIdx, endIdx } = target;
+  result.injectionFile = injected.file;
+  const { content, startIdx, endIdx } = injected;
 
   // 重复章节：全文统计治理标题数（严格计数 injection-writer.countGovernanceHeadings，#83）
   const headingCount = countGovernanceHeadings(content);
@@ -117,7 +125,10 @@ export function detectInjectionDrift(
   }
 
   // 2. 内容漂移（条目级：期望渲染 vs 实际段）
-  const expectedSection = renderConstraintsSection(getEffectiveConstraints(projectRoot), currentVersion);
+  const expectedSection = renderConstraintsSection(
+    expectedConstraints ?? getEffectiveConstraints(env),
+    currentVersion
+  );
   const expectedLines = new Set(significantLines(expectedSection));
   const actualLines = new Set(significantLines(actualSection));
   const missing = [...expectedLines].filter(l => !actualLines.has(l));

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

@@ -0,0 +1,207 @@
+/**
+ * 运行级观察面（ADR-0023 决策 1）
+ *
+ * 一次 `harness check` 一份、跑完即弃：把「本项目有哪些源码根」「最近的 trace 记录」
+ * 「`.harness/config.yml` 与自定义约束文件写了什么」这类上行数据的读取收在此处，
+ * 同一次运行内每个文件至多读一次。
+ *
+ * 为什么不是一个对象而是两个：checker 拿到的 `CheckEnv` 里含 `context`，而 `context` 正是
+ * context-builder **通过本对象读文件算出来的**——同一对象不能既是构造者的输入又是它的产物。
+ * 故这里只放「不需要 context 就能造」的部分，`CheckEnv` 之后从它派生（见 checkers/types.ts）。
+ *
+ * 与 #87 的 git 证据同一形状：一次运行一份、经参数显式传下去，不做进程级单例——
+ * 测试在同进程内反复改文件，常驻缓存会把「先改后读」读成老内容。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import { detectSourceRoots } from '../../utils/detect-source-roots';
+import { reconcileCapabilities, type CapabilityVerdict } from './capabilities-reconcile';
+import { readJsonlWindow, type JsonlWindow, type JsonlReadResult } from '../../utils/jsonl';
+import { DEFAULT_TRACE_FILE, type ExecutionTrace } from '../../types/trace';
+import type { CustomConstraintDefinition } from '../../types/project-config';
+
+/** config.yml 在项目根下的相对路径（读取口径唯一落点） */
+const CONFIG_FILE_REL = path.join('.harness', 'config.yml');
+
+/** 能力表在项目根下的落点（checker 侧存在性探测与本读面共用此常量） */
+export const CAPABILITIES_FILE_REL = 'CAPABILITIES.md';
+
+/**
+ * 尾部窗口上限 = 本 run 内最大的尾部消费方（有无失败记录看 20 条，见 context-builder）
+ *
+ * 更小的窗口（验证证据看 10 条）从同一份行文本上截，不再二次读文件。
+ */
+const TRACE_TAIL_WINDOW = 20;
+
+export interface RunEnv {
+  /** 项目根（生产代码的每个 IO 点都用它，不再各自取 cwd——harness#95） */
+  readonly projectPath: string;
+  /** 最近 limit 条 trace 记录（≤ TRACE_TAIL_WINDOW；一次运行内至多读文件一次） */
+  traceTail(limit: number): JsonlReadResult<ExecutionTrace>;
+  /** 源码根相对路径列表（一次运行内至多探测一次） */
+  sourceRoots(): string[];
+  /**
+   * `.harness/config.yml` 的解析结果（一次运行内至多读一次）
+   *
+   * 口径与改前的 `loadRawProjectConfig` 逐字一致：文件缺失 → undefined；
+   * 空文件 → `{}`；YAML 解析失败 → **抛出**（兜底与否属各消费方的判定，不在读面上替它决定）。
+   */
+  rawConfig(): Record<string, unknown> | undefined;
+  /**
+   * `.harness/<fileName>` 里的自定义约束定义（一次运行内同名文件至多读一次）
+   *
+   * 文件名由消费方（ProjectConfigLoader）从合并后的 config 解析后传入——
+   * 「`custom_constraints_file` 怎么写才算数」属加载器口径，不在读面上判。
+   * 文件缺失或无 `custom_constraints` 段 → `{}`（与改前的直读逐字一致）。
+   */
+  customConstraints(fileName: string): Record<string, CustomConstraintDefinition>;
+  /**
+   * `CAPABILITIES.md` 的读取 + 解析 + 与代码实况的对照判定（ADR-0023 决策 4）
+   *
+   * 此前 capability_sync 与 docs_freshness 各读一遍文档、各跑一遍 `reconcileCapabilities`
+   * （studio 量得单次 7.6–15.9ms，两边解析输入逐字节相同）。此处一次供给两消费方。
+   * 文档缺失 → `undefined`（消费方据此 skip / 无幽灵）。
+   *
+   * **memo 只记第一次传入的 `populationFiles`**：同一 run 内两消费方必须给同一份代码实况清单。
+   * 二者一律经 `collectPopulationFiles(projectPath, roots, scan)` 取数，形状由构造保证；
+   * 出现第三个消费方且清单不同，就必须改成按输入分列的缓存而不是静默复用。
+   */
+  capabilities(populationFiles: string[]): ProjectCapabilities | undefined;
+}
+
+/**
+ * 一次运行内的能力表面貌：原文 + 源码根 + 代码实况清单 + 对照判定
+ *
+ * `verdict.deadEntries` 按「文件系统中真实存在也算活」的严口径算（带存在性 oracle），
+ * capability_sync 不读它、docs_freshness 只读它；`verdict.uncoveredChanges` 在此恒空
+ * ——本观察面不收 git 变更清单（属证据面，#87），增量覆盖由 capability_sync 自己按
+ * `coverageEntries` 算。直调 `reconcileCapabilities` 的消费方（如 sync-docs）仍可传 changedFiles。
+ */
+export interface ProjectCapabilities {
+  readonly content: string;
+  readonly sourceRoots: string[];
+  readonly populationFiles: string[];
+  readonly verdict: CapabilityVerdict;
+}
+
+/**
+ * 构造运行级观察面
+ *
+ * 懒建：没有消费方就不碰文件（`harness check` 在干净树与脏树上读的并不一样多）。
+ */
+export function createRunEnv(projectPath: string): RunEnv {
+  const traceFile = path.join(projectPath, DEFAULT_TRACE_FILE);
+  let window: JsonlWindow<ExecutionTrace> | null = null;
+  let sourceRoots: string[] | null = null;
+  let configLoaded = false;
+  let configRaw: Record<string, unknown> | undefined;
+  const customDefs = new Map<string, Record<string, CustomConstraintDefinition>>();
+  /** 能力表 memo：undefined = 未算，null = 项目无 CAPABILITIES.md */
+  let caps: ProjectCapabilities | null | undefined;
+
+  return {
+    projectPath,
+    traceTail(limit: number) {
+      if (!window) {
+        // 计数去向：豁免（harness#100）——本观察面只供给「最近有无 fail / 有无 pass」两个
+        // 布尔证据的消费方，它们不读 skippedLines；坏行占尾部槽位只会让证据变少（方向保守），
+        // 告知需要改判定形状，属行为变更不在本票（口径与改前的两处独立 tail 读逐字一致）
+        window = readJsonlWindow<ExecutionTrace>(traceFile, 'skip', TRACE_TAIL_WINDOW);
+      }
+      return window.take(limit);
+    },
+    sourceRoots: roots,
+    rawConfig() {
+      if (!configLoaded) {
+        configRaw = readYamlFile(path.join(projectPath, CONFIG_FILE_REL));
+        configLoaded = true;
+      }
+      return configRaw;
+    },
+    customConstraints(fileName: string) {
+      let defs = customDefs.get(fileName);
+      if (!defs) {
+        defs = readCustomConstraints(path.join(projectPath, '.harness', fileName));
+        customDefs.set(fileName, defs);
+      }
+      return defs;
+    },
+    capabilities(populationFiles: string[]) {
+      if (caps === undefined) {
+        const content = readCapabilitiesContent();
+        caps = content === undefined
+          ? null
+          : {
+              content,
+              sourceRoots: roots(),
+              populationFiles,
+              verdict: reconcileCapabilities({
+                content,
+                populationFiles,
+                sourceRoots: roots(),
+                fileExists: rel => fs.existsSync(path.join(projectPath, rel)),
+              }),
+            };
+      }
+      return caps ?? undefined;
+    },
+  };
+
+  /** 源根探测 memo（sourceRoots() 与能力表共用同一份） */
+  function roots(): string[] {
+    if (!sourceRoots) {
+      sourceRoots = detectSourceRoots(projectPath);
+    }
+    return sourceRoots;
+  }
+
+  /** 读 CAPABILITIES.md 原文；缺失 → undefined（不算异常，未采用该约定的项目占多数） */
+  function readCapabilitiesContent(): string | undefined {
+    const file = path.join(projectPath, CAPABILITIES_FILE_REL);
+    return fs.existsSync(file) ? fs.readFileSync(file, 'utf-8') : undefined;
+  }
+}
+
+/**
+ * 读一个自定义约束文件并取出 `custom_constraints` 段
+ *
+ * 缺失 → `{}`。文档解析成空值（空 yaml 文件）时取段会抛——改前直读就是这个行为，
+ * 不在此新增兜底：畸形配置文件该炸在配置上，不该被读面抹平。
+ */
+function readCustomConstraints(absPath: string): Record<string, CustomConstraintDefinition> {
+  if (!fs.existsSync(absPath)) return {};
+  const loaded = yaml.load(fs.readFileSync(absPath, 'utf-8')) as {
+    custom_constraints?: Record<string, CustomConstraintDefinition>;
+  };
+  return loaded.custom_constraints ?? {};
+}
+
+/**
+ * 读并解析一个 YAML 配置文件
+ *
+ * 缺失 → undefined、空文件 → `{}`，两者都不算异常；解析失败照抛（消费方各自兜底）。
+ * 不判 mtime/size 指纹——ADR-0023 决策 2 撤销了那套进程级口径，新鲜度只由「一次运行一份」保证。
+ */
+function readYamlFile(absPath: string): Record<string, unknown> | undefined {
+  if (!fs.existsSync(absPath)) return undefined;
+  const loaded = yaml.load(fs.readFileSync(absPath, 'utf-8'));
+  return (loaded ?? {}) as Record<string, unknown>;
+}
+
+/**
+ * 运行级访问器的入参形状：观察面，或项目根路径
+ *
+ * 传路径 = 「只此一次」的便利形状：自造一枚用完即弃的观察面，读到的是当下的文件内容。
+ * 想在本 run 内共享读取（`harness check` 的全部消费方）就把同一枚 RunEnv 传下去。
+ */
+export type RunTarget = RunEnv | string;
+
+/** 归一 RunTarget（非 RunEnv 即按项目根自造一枚一次性观察面） */
+export function resolveRunEnv(target?: RunTarget): RunEnv {
+  if (typeof target === 'object' && target !== null) return target;
+  return createRunEnv(target || process.cwd());
+}
+
+export { TRACE_TAIL_WINDOW };

package/src/core/constraints/triggers.ts

@@ -0,0 +1,33 @@
+/**
+ * 约束 trigger 归一与匹配（harness#105 单点）
+ *
+ * 约束域谓词，不是通用工具：`normalizeTriggers` 的「undefined → [] 不匹配任何操作」
+ * 语义只在 trigger 字段上成立。此前二者住在 `utils/exec.ts`、由 core/constraints
+ * 跨模块拉用，utils 层因此挂着一枚只有约束域会调的假接缝（harness#137 归位）。
+ * checker 与 prompt 渲染共用本模块，禁止就地重写。
+ */
+
+/**
+ * 将单值或数组统一为数组（用于 trigger 等字段）
+ */
+export function normalizeTriggers<T>(
+  value: T | T[] | undefined,
+  fallback: T[] = []
+): T[] {
+  if (value === undefined || value === null) return fallback;
+  return Array.isArray(value) ? value : [value];
+}
+
+/**
+ * 判断约束是否匹配当前操作集合（#105：trigger 匹配语义单一来源）
+ *
+ * 语义 = normalizeTriggers（undefined → [] 不匹配任何操作）+ 交集判定，
+ * 任一 operation 命中任一 trigger 即匹配。
+ */
+export function matchesTrigger<T>(
+  constraint: { trigger: T | T[] | undefined },
+  operations: T[]
+): boolean {
+  const triggers = normalizeTriggers(constraint.trigger);
+  return operations.some(op => triggers.includes(op));
+}

package/src/core/effective-constraints.ts

@@ -11,6 +11,7 @@ import type { Constraint } from '../types/constraint';
 import type { MergedConstraintsConfig } from '../types/project-config';
 import { PROMPTS } from './constraints/definitions';
 import { ProjectConfigLoader } from './project-config-loader';
+import type { RunTarget } from './constraints/run-env';
 
 /**
  * 获取项目当前生效的约束集（check + prompt，带 kind）
@@ -21,15 +22,25 @@ import { ProjectConfigLoader } from './project-config-loader';
  * （带 appliesTo 的 prompt 仅当 config.yml `scenes` 与其交集非空时保留，
  * 缺省 scenes=[] 即场景专属 prompt 默认不进入生效集）。
  *
- * @param projectRoot 项目根路径（缺省 process.cwd()）
+ * @param target 项目根路径，或本 run 的运行级观察面（缺省 process.cwd()）
+ *   传观察面 = config.yml 读取与本 run 其余消费方共用同一份（ADR-0023 决策 2）
  * @param options.preset 覆盖 config.yml 的 preset；仅在项目无自定义配置时生效
  *   （与 getMergedConstraintsConfig 同一优先级规则），不传则尊重 config.yml
  */
 export function getEffectiveConstraints(
-  projectRoot: string = process.cwd(),
+  target: RunTarget = process.cwd(),
   options?: { preset?: string }
 ): Constraint[] {
-  const merged = getMergedConstraintsConfig(projectRoot, options);
+  return constraintsFromMerged(getMergedConstraintsConfig(target, options));
+}
+
+/**
+ * 从已算好的合并配置取出生效集清单（与 getEffectiveConstraints 同一形状）
+ *
+ * 给已经持有 `MergedConstraintsConfig` 的消费方复用（CLI check 把这一份同时交给
+ * 漂移检测，避免生效集链路在一次运行里算两遍，ADR-0023 步骤 4.5）。
+ */
+export function constraintsFromMerged(merged: MergedConstraintsConfig): Constraint[] {
   return [
     ...Object.values(merged.ironLaws),
     ...Object.values(merged.guidelines),
@@ -47,13 +58,13 @@ export function getEffectiveConstraints(
  * preset（工单 23 语义：项目自定义配置优先于 CLI 预设）；不传 preset 时
  * 完全尊重 config.yml 的 preset 键。
  *
- * @param projectRoot 项目根路径（缺省 process.cwd()）
+ * @param target 项目根路径，或本 run 的运行级观察面（缺省 process.cwd()）
  */
 export function getMergedConstraintsConfig(
-  projectRoot: string = process.cwd(),
+  target: RunTarget = process.cwd(),
   options?: { preset?: string }
 ): MergedConstraintsConfig {
-  const loader = new ProjectConfigLoader(projectRoot);
+  const loader = new ProjectConfigLoader(target);
   loader.load();
   if (loader.hasCustomConfig() || !options?.preset) {
     return loader.mergeConstraints();