@dommaker/harness 1.1.1 → 1.2.0

package/src/core/constraints/checker.ts

@@ -17,6 +17,7 @@ import {
   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';
@@ -24,50 +25,19 @@ import { runCommand } from '../../utils/exec';
 import { join, relative } from 'path';
 import { CheckCache } from './check-cache';
 import { findTsSourceFiles } from '../../utils/file-walk';
-import { getConstraintCheck, type CheckEnv, type CheckOutcome } from './checkers';
+import { getConstraintCheck, buildCheckEnv, type CheckOutcome } from './checkers';
 
 /**
- * 例外名称 → ConstraintContext 中布尔字段的映射
- */
-const EXCEPTION_FIELD_MAP: Record<string, keyof ConstraintContext> = {
-  scalability_required: 'scalabilityRequired',
-  security_required: 'securityRequired',
-  performance_required: 'performanceRequired',
-  reliability_required: 'reliabilityRequired',
-  simple_typo: 'isSimpleTypo',
-  config_value_error: 'isConfigValueError',
-  missing_config: 'isMissingConfig',
-  config_file: 'isConfigFile',
-  type_definition: 'isTypeDefinition',
-  simple_accessor: 'isSimpleAccessor',
-  pure_display_component: 'isPureDisplayComponent',
-  json_parse_result: 'isJsonParseResult',
-  third_party_no_types: 'isThirdPartyNoTypes',
-  legacy_migration: 'isLegacyMigration',
-  internal_refactor: 'isInternalRefactor',
-  bug_fix_only: 'isBugFixOnly',
-  performance_optimization: 'isPerformanceOptimization',
-  redundant_code_cleanup: 'isRedundantCodeCleanup',
-  same_effect_refactor: 'isSameEffectRefactor',
-  unused_code_removal: 'isUnusedCodeRemoval',
-  external_dependency: 'isExternalDependency',
-  explicit_instruction: 'isExplicitInstruction',
-  emergency_fix: 'isEmergencyFix',
-  existing_design: 'isExistingDesign',
-};
-
-/**
- * trace 记录器最小接口（工单 15：core→monitoring 循环消除）
+ * trace 记录器最小接口（原工单 15 为消除 core→monitoring 循环；现 monitoring
+ * 不反向依赖 core，方向单向、无环，checker 可直接值引用 getTraceCollector）
  *
- * checker 不再值导入 monitoring/traces 的单例；生产调用方经
- * setTraceRecorder 注入真实收集器，默认 no-op。
+ * checker 不构造收集器；生产路径首次记录时惰性接线 getTraceCollector()
+ * （幂等单点，ADR-0003），测试可经 setTraceRecorder 注入替身。
  */
 export interface TraceRecorder {
   record(trace: ExecutionTrace): void;
 }
 
-const NOOP_TRACE_RECORDER: TraceRecorder = { record: () => undefined };
-
 /**
  * 约束检查器
  */
@@ -78,16 +48,26 @@ export class ConstraintChecker {
   private cache: CheckCache = new CheckCache({ ttlMs: 1000 });
 
   /**
-   * run 级 memo（工单 18）：一次 checkConstraints/checkConstraintsSafe 内
+   * run 级 memo（工单 18）：一次 checkConstraints 内
    * git diff 等命令只执行一次；run 外直接调用私有检查方法时不 memo（恒新鲜）。
    */
   private runCache: Map<string, Promise<string>> | null = null;
 
-  /** trace 记录器（注入式，默认 no-op；生产入口经 setTraceRecorder 接入真实收集器） */
-  private traceRecorder: TraceRecorder = NOOP_TRACE_RECORDER;
+  /** trace 记录器（注入式；null = 未显式注入，首次记录时惰性接线全局收集器） */
+  private traceRecorder: TraceRecorder | null = null;
 
   private constructor() {}
 
+  /**
+   * 取 trace 记录器：未显式注入时惰性接线全局收集器（幂等，ADR-0003 副作用收敛）
+   */
+  private getRecorder(): TraceRecorder {
+    if (!this.traceRecorder) {
+      this.traceRecorder = getTraceCollector();
+    }
+    return this.traceRecorder;
+  }
+
   /**
    * run 内 memoize；无活动 run 时直接执行（工单 18）
    */
@@ -130,7 +110,7 @@ export class ConstraintChecker {
   }
 
   /**
-   * 注入 trace 记录器（工单 15：解耦 core 对 monitoring 的值依赖）
+   * 注入 trace 记录器（测试/定制场景；不调用则首次记录时惰性接线全局收集器）
    */
   setTraceRecorder(recorder: TraceRecorder): void {
     this.traceRecorder = recorder;
@@ -139,29 +119,25 @@ export class ConstraintChecker {
   /**
    * 获取当前的约束集合（内置 + 自定义）
    *
+   * 纯查询，无副作用（ADR-0006：原 `.check` 装配已随唯一消费者
+   * interceptor 的删除一并移除，ADR-0004）。
+   *
    * @param customConfig 可选，per-request 自定义配置；不传则返回内置约束集
    */
   getConstraints(customConfig?: MergedConstraintsConfig | null): {
-    ironLaws: Record<string, Constraint & { check: (ctx: ConstraintContext) => Promise<ConstraintResult> }>;
-    guidelines: Record<string, Constraint & { check: (ctx: ConstraintContext) => Promise<ConstraintResult> }>;
-    prompts: Record<string, Constraint & { check: (ctx: ConstraintContext) => Promise<ConstraintResult> }>;
+    ironLaws: Record<string, Constraint>;
+    guidelines: Record<string, Constraint>;
+    prompts: Record<string, Constraint>;
   } {
     const config = customConfig;
     const source = config
       ? { ironLaws: config.ironLaws, guidelines: config.guidelines, prompts: config.prompts ?? PROMPTS }
       : { ironLaws: IRON_LAWS, guidelines: GUIDELINES, prompts: PROMPTS };
 
-    // Wire unified check() method on every constraint
-    const wire = (constraints: Record<string, Constraint>) => {
-      for (const c of Object.values(constraints)) {
-        (c as any).check = (ctx: ConstraintContext) => this.check(c, ctx);
-      }
-      return constraints as Record<string, Constraint & { check: (ctx: ConstraintContext) => Promise<ConstraintResult> }>;
-    };
     return {
-      ironLaws: wire(source.ironLaws),
-      guidelines: wire(source.guidelines),
-      prompts: wire(source.prompts),
+      ironLaws: source.ironLaws,
+      guidelines: source.guidelines,
+      prompts: source.prompts,
     };
   }
 
@@ -183,20 +159,6 @@ export class ConstraintChecker {
       };
     }
 
-    // 检查例外条件（仅 Guidelines 有效）
-    if (constraint.level === 'guideline' && constraint.exceptions) {
-      if (this.checkException(constraint, context)) {
-        return {
-          id: constraint.id,
-          level: constraint.level,
-          satisfied: true,
-          constraint,
-          message: `指导原则 ${constraint.id} 因例外条件被豁免`,
-          checkedAt: new Date(),
-        };
-      }
-    }
-
     // 检查前置条件（'skip' = 约定未采用/证据未接线：satisfied 置 true 但不计 pass/fail）
     const outcome = await this.checkPrecondition(constraint, context);
 
@@ -225,16 +187,6 @@ export class ConstraintChecker {
     };
   }
 
-  /**
-   * 检查例外条件
-   */
-  private checkException(constraint: Constraint, context: ConstraintContext): boolean {
-    if (!constraint.exceptions) return false;
-    return constraint.exceptions.some(
-      (ex) => context[EXCEPTION_FIELD_MAP[ex]] === true
-    );
-  }
-
   /**
    * 根据约束层级获取严重性
    */
@@ -279,9 +231,6 @@ export class ConstraintChecker {
       result: checkResult.skipped ? 'skip' : checkResult.satisfied ? 'pass' : 'fail',
       operation: context.operation,
       severity: this.getSeverity(constraint.level),
-      exceptionApplied: checkResult.message?.includes('豁免')
-        ? constraint.exceptions?.[0]
-        : undefined,
       projectPath: context.projectPath,
       sessionId: context.sessionId,
     });
@@ -306,9 +255,7 @@ export class ConstraintChecker {
     }
 
     const projectPath = context.projectPath || process.cwd();
-    const env: CheckEnv = {
-      context,
-      projectPath,
+    const env = buildCheckEnv(context, {
       stagedDiff: () => this.getStagedDiff(projectPath),
       stagedDiffNames: () => this.getStagedDiffNames(projectPath),
       srcScan: (root: string) =>
@@ -317,7 +264,7 @@ export class ConstraintChecker {
             relative(projectPath, f)
           )
         ),
-    };
+    });
 
     return await impl.evaluate(env);
   }
@@ -380,7 +327,7 @@ export class ConstraintChecker {
         warningCount: 0,
       };
 
-      const traceCollector = this.traceRecorder;
+      const traceCollector = this.getRecorder();
       const constraints = this.getConstraints(customConfig);
 
       // 1. Iron Laws: 必须全部通过
@@ -416,53 +363,6 @@ export class ConstraintChecker {
     }
   }
 
-  /**
-   * S11: 安全全量检查 — 全部约束检查，不抛异常
-   *
-   * 区别 checkConstraints(): Iron Law 违规收集在结果中而不是抛异常。
-   * 调用方通过 result.passed + result.warningCount 判断状态。
-   */
-  async checkConstraintsSafe(
-    context: ConstraintContext,
-    customConfig?: MergedConstraintsConfig | null
-  ): Promise<ConstraintCheckResult> {
-    // run 起始：重置 run 级缓存（工单 18）
-    this.cache.invalidate();
-    this.runCache = new Map();
-
-    try {
-      const result: ConstraintCheckResult = {
-        ironLaws: [],
-        guidelines: [],
-        passed: true,
-        warningCount: 0,
-      };
-
-      const traceCollector = this.traceRecorder;
-      const constraints = this.getConstraints(customConfig);
-
-      for (const constraint of Object.values(constraints.ironLaws)) {
-        if (!this.matchesTrigger(constraint, context)) continue;
-        const checkResult = await this.check(constraint, context);
-        result.ironLaws.push(checkResult);
-        this.recordTrace(traceCollector, constraint, checkResult, context);
-        if (!checkResult.satisfied) result.passed = false;
-      }
-
-      for (const constraint of Object.values(constraints.guidelines)) {
-        if (!this.matchesTrigger(constraint, context)) continue;
-        const checkResult = await this.check(constraint, context);
-        result.guidelines.push(checkResult);
-        this.recordTrace(traceCollector, constraint, checkResult, context);
-        if (!checkResult.satisfied) result.warningCount++;
-      }
-
-      return result;
-    } finally {
-      this.runCache = null;
-    }
-  }
-
   /**
    * 执行前检查（仅检查 Iron Laws）
    *
@@ -524,26 +424,32 @@ export async function checkConstraint(
 }
 
 /**
- * 快捷函数：执行三层检查
- *
- * @param context 约束上下文
- * @param customConfig 可选，per-request 自定义配置
+ * checkConstraints 选项（ADR-0003：包根/子路径统一 options 对象签名）
  */
-export async function checkConstraints(
-  context: ConstraintContext,
-  customConfig?: MergedConstraintsConfig | null
-): Promise<ConstraintCheckResult> {
-  return ConstraintChecker.getInstance().checkConstraints(context, customConfig);
+export interface CheckConstraintsOptions {
+  /** 每条约束检查后的回调（用于记录 trace 到外部存储） */
+  onTrace?: (result: ConstraintResult) => void;
+  /** 可选，per-request 自定义约束配置；不传则用内置约束集 */
+  customConfig?: MergedConstraintsConfig | null;
 }
 
 /**
- * S11: 快捷函数 — 安全全量检查（不抛异常）
+ * 快捷函数：执行三层检查
+ *
+ * @param context 约束上下文
+ * @param options.onTrace 每条约束检查后的回调（用于记录 trace 到外部存储）
+ * @param options.customConfig 可选，per-request 自定义约束配置；不传则用内置约束集
  */
-export async function checkConstraintsSafe(
+export async function checkConstraints(
   context: ConstraintContext,
-  customConfig?: MergedConstraintsConfig | null
+  options?: CheckConstraintsOptions
 ): Promise<ConstraintCheckResult> {
-  return ConstraintChecker.getInstance().checkConstraintsSafe(context, customConfig);
+  const result = await ConstraintChecker.getInstance().checkConstraints(context, options?.customConfig ?? null);
+  if (options?.onTrace) {
+    for (const r of result.ironLaws) options.onTrace(r);
+    for (const r of result.guidelines) options.onTrace(r);
+  }
+  return result;
 }
 
 /**

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

@@ -78,4 +78,5 @@ export function registeredCheckCount(): number {
   return registry.size;
 }
 
-export type { ConstraintCheck, CheckEnv, CheckOutcome } from './types';
+export { buildCheckEnv } from './types';
+export type { ConstraintCheck, CheckEnv, CheckOutcome, EvidenceProviders } from './types';

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

@@ -26,6 +26,48 @@ export interface CheckEnv {
   srcScan(root: string): string[];
 }
 
+/**
+ * 证据提供者组：git diff / 源码扫描的 memoized I/O
+ *
+ * 由调用方绑定后传入 buildCheckEnv（如 ConstraintChecker 绑实例级
+ * run 缓存的方法）；工厂本身不做 memoization。
+ */
+export interface EvidenceProviders {
+  /** staged 全量 diff */
+  stagedDiff(): Promise<string>;
+  /** staged 变更文件名列表 */
+  stagedDiffNames(): Promise<string>;
+  /** 源码根相对路径文件列表 */
+  srcScan(root: string): string[];
+}
+
+/**
+ * 构造 CheckEnv：生产侧唯一构造点
+ *
+ * - providers 传入 = 证据接线，checker 正常评估
+ * - 'none' = 显式不接证据：证据函数返回空；evidence flag 未接线的
+ *   checker 按契约返回 'skip'（见 contextEvidenceFlag），直接读空
+ *   证据的 checker 在自然输入下判定
+ *
+ * studio 侧若需 git 证据（#129），传真实 providers 即可。
+ */
+export function buildCheckEnv(
+  context: ConstraintContext,
+  evidence: EvidenceProviders | 'none'
+): CheckEnv {
+  const projectPath = context.projectPath || process.cwd();
+  if (evidence === 'none') {
+    return {
+      context,
+      projectPath,
+      stagedDiff: async () => '',
+      stagedDiffNames: async () => '',
+      srcScan: () => [],
+    };
+  }
+  return { context, projectPath, ...evidence };
+}
+
 /**
  * 检查结果三态（ADR-0001 存在性探测 / flag 未接线）：
  * - true = 满足（pass）

package/src/core/constraints/definitions/guidelines.ts

@@ -68,7 +68,6 @@ export const GUIDELINES: Record<string, Constraint> = {
 - 性能优化不改变接口
 
 支持模块级目录条目登记：governance.capabilities.mode=module 时按目录覆盖判定（如 src/core/ 一条目录条目覆盖该目录下所有源文件）。`,
-    exceptions: ['internal_refactor', 'bug_fix_only', 'performance_optimization'],
   },
 
   /**
@@ -97,6 +96,5 @@ export const GUIDELINES: Record<string, Constraint> = {
 - 临时目录（tmp、temp）
 - 测试目录（__tests__、test）
 - 生成代码目录（dist、build、generated）`,
-    exceptions: ['temp_dir', 'test_dir', 'generated_code'],
   },
 };

package/src/core/constraints/definitions/prompts.ts

@@ -76,7 +76,6 @@ export const PROMPTS: Record<string, Constraint> = {
 - 用 fallback/兜底值掩盖上游数据异常而不追根因
 - Read 定位后直接 Edit，不对照设计原型确认意图
 - 从"数字异常"直接跳到根因结论，不验证假设的含义与量纲`,
-    exceptions: ['simple_typo', 'config_value_error', 'missing_config'],
     promptInjection: '修复问题前必须先诊断根因——不止"哪里出错"，而是"为什么设计成这样"：用 Read/Grep 定位后禁止直接 Edit，先对照设计原型（CLAUDE.md、类型定义、commit message）确认原设计意图，呈现确认的根因+方案草案后才能动手。遇到空值/异常/不完整数据，禁止用 fallback/兜底/try-catch 掩盖——先追上游：数据谁产生的？为什么是空的？选择防御性兜底时必须在注释中说明根因；同一位置连续兜底 2+ 次是上游 bug 信号，停止修下游、追踪源头。从数据到结论必须先验证关键假设：数字的含义（累积/单次？量纲？）、正常范围、同类场景对比与反例，禁止"数字异常→直接定根因→直接改"的跳级推理。不绕过问题、不遮掩症状、不用临时方案代替根本修复。',
   },
 
@@ -107,7 +106,6 @@ export const PROMPTS: Record<string, Constraint> = {
 - reliability_required: 需要持久化/高可用
 
 YAGNI：不为"未来可能需要"添加抽象层、接口、配置项或插件系统；一个抽象只有一个实现者时删除该抽象。`,
-    exceptions: ['scalability_required', 'security_required', 'performance_required', 'reliability_required'],
     promptInjection: '最简方案优先：用最少代码解决当前问题，不添加"以防万一"的冗余功能，不为仅用一次的代码强行设计抽象。创建新模块/文件/能力前，先查现有能力索引确认无可复用——优先级：直接复用 > 扩展现有 > 组合现有 > 新建。遵循 YAGNI：不为"未来可能需要"添加抽象层、接口、配置项或插件系统；一个 interface/abstract class 只有一个实现者时，删除这个抽象。自检：资深工程师是否会认为此实现过度复杂？若是，立即简化。',
     injectPrompt: true,
   },
@@ -137,7 +135,6 @@ YAGNI：不为"未来可能需要"添加抽象层、接口、配置项或插件
 - 类型定义文件（.d.ts、interface）
 - 简单 getter/setter
 - 纯展示 UI 组件（无交互逻辑）`,
-    exceptions: ['config_file', 'type_definition', 'simple_accessor', 'pure_display_component'],
     promptInjection: '新代码必须同时编写测试。实现功能前先写测试用例（RED），然后实现让测试通过（GREEN）。不得提交无测试覆盖的实现代码。',
   },
 
@@ -164,7 +161,6 @@ YAGNI：不为"未来可能需要"添加抽象层、接口、配置项或插件
 - 发现冗余代码后的重构优化
 - 用更简洁的实现达到相同效果
 - 删除不再使用的遗留代码`,
-    exceptions: ['redundant_code_cleanup', 'same_effect_refactor', 'unused_code_removal'],
     promptInjection: '不得擅自简化或删除测试、lint 规则、类型检查或约束。如需降低检查标准，必须先提案并获明确批准。',
   },
 
@@ -272,7 +268,6 @@ YAGNI：不为"未来可能需要"添加抽象层、接口、配置项或插件
 - 用户明确说"直接做"、"不用问"
 - 紧急修复
 - 已有明确设计文档`,
-    exceptions: ['explicit_instruction', 'emergency_fix', 'existing_design'],
     promptInjection: '涉及架构变更、新增依赖、API 设计等重大决策时，必须先提出讨论获得确认，再开始实现。不要凭单方面判断做架构决策。',
   },
 

package/src/core/constraints/index.ts

@@ -20,6 +20,7 @@ export {
   checkBeforeExecution,
   constraintChecker,
 } from './checker';
+export type { CheckConstraintsOptions, TraceRecorder } from './checker';
 
 // CLAUDE.md 约束注入段渲染（纯函数，init 注入与漂移校验共用）
 export {
@@ -51,20 +52,4 @@ export type {
   IronLawContext,
 } from '../../types/constraint';
 
-export { ConstraintViolationError } from '../../types/constraint';
-
-// 约束拦截器
-export {
-  ConstraintInterceptor,
-  constraintInterceptor,
-  interceptOperation,
-  claimOperation,
-} from './interceptor';
-
-export type {
-  EnforcementId,
-  EnforcementExecutor,
-  EnforcementContext,
-  EnforcementResult,
-  InterceptionResult,
-} from '../../types/enforcement';
+export { ConstraintViolationError } from '../../types/constraint';

package/src/core/constraints/usage-report.ts

@@ -33,12 +33,11 @@ export interface ConstraintUsageStats {
   id: string;
   level: Constraint['level'];
 
-  /** trace 总行数（含 skip/bypassed） */
+  /** trace 总行数（含 skip） */
   total: number;
   pass: number;
   fail: number;
   skip: number;
-  bypassed: number;
 
   /** 实际评估次数（total - skip；skip 未评估不计入，与 TraceAnalyzer 一致） */
   evaluated: number;
@@ -129,26 +128,25 @@ export function readProjectTraces(projectRoot: string): ExecutionTrace[] {
 export function collectUsageByConstraint(
   traces: ExecutionTrace[]
 ): Map<string, Omit<ConstraintUsageStats, 'id' | 'level' | 'evaluated' | 'failRate'>> {
-  const map = new Map<string, { total: number; pass: number; fail: number; skip: number; bypassed: number; firstAt?: number; lastAt?: number }>();
+  const map = new Map<string, { total: number; pass: number; fail: number; skip: number; firstAt?: number; lastAt?: number }>();
   for (const t of traces) {
     let agg = map.get(t.constraintId);
     if (!agg) {
-      agg = { total: 0, pass: 0, fail: 0, skip: 0, bypassed: 0 };
+      agg = { total: 0, pass: 0, fail: 0, skip: 0 };
       map.set(t.constraintId, agg);
     }
     agg.total++;
     if (t.result === 'pass') agg.pass++;
     else if (t.result === 'fail') agg.fail++;
     else if (t.result === 'skip') agg.skip++;
-    else if (t.result === 'bypassed') agg.bypassed++;
     if (agg.firstAt === undefined || t.timestamp < agg.firstAt) agg.firstAt = t.timestamp;
     if (agg.lastAt === undefined || t.timestamp > agg.lastAt) agg.lastAt = t.timestamp;
   }
   return map;
 }
 
-function toStats(id: string, level: Constraint['level'], agg: { total: number; pass: number; fail: number; skip: number; bypassed: number; firstAt?: number; lastAt?: number } | undefined): ConstraintUsageStats {
-  const a = agg ?? { total: 0, pass: 0, fail: 0, skip: 0, bypassed: 0 };
+function toStats(id: string, level: Constraint['level'], agg: { total: number; pass: number; fail: number; skip: number; firstAt?: number; lastAt?: number } | undefined): ConstraintUsageStats {
+  const a = agg ?? { total: 0, pass: 0, fail: 0, skip: 0 };
   const evaluated = a.total - a.skip;
   return {
     id,
@@ -157,7 +155,6 @@ function toStats(id: string, level: Constraint['level'], agg: { total: number; p
     pass: a.pass,
     fail: a.fail,
     skip: a.skip,
-    bypassed: a.bypassed,
     evaluated,
     failRate: evaluated > 0 ? a.fail / evaluated : 0,
     firstAt: a.firstAt,

package/src/core/effective-constraints.ts

@@ -8,24 +8,28 @@
  */
 
 import type { Constraint } from '../types/constraint';
+import type { MergedConstraintsConfig } from '../types/project-config';
 import { PROMPTS } from './constraints/definitions';
 import { ProjectConfigLoader } from './project-config-loader';
 
 /**
  * 获取项目当前生效的约束集（check + prompt，带 kind）
  *
- * 内部完成完整合并：内置 → preset 裁剪 → config.yml `constraints.<id>.enabled:false`
- * 删除（内置与 custom 同效）→ custom-constraints 追加/extend_exceptions
- * （禁用/已退役的 custom 不追加）→ scenes 过滤
+ * 生效集链路同 getMergedConstraintsConfig：内置 → preset 裁剪 → config.yml
+ * `constraints.<id>.enabled:false` 删除（内置与 custom 同效）→ custom-constraints
+ * 追加（禁用/已退役的 custom 不追加）→ scenes 过滤
  * （带 appliesTo 的 prompt 仅当 config.yml `scenes` 与其交集非空时保留，
  * 缺省 scenes=[] 即场景专属 prompt 默认不进入生效集）。
  *
  * @param projectRoot 项目根路径（缺省 process.cwd()）
+ * @param options.preset 覆盖 config.yml 的 preset；仅在项目无自定义配置时生效
+ *   （与 getMergedConstraintsConfig 同一优先级规则），不传则尊重 config.yml
  */
-export function getEffectiveConstraints(projectRoot: string = process.cwd()): Constraint[] {
-  const loader = new ProjectConfigLoader(projectRoot);
-  loader.load();
-  const merged = loader.mergeConstraints();
+export function getEffectiveConstraints(
+  projectRoot: string = process.cwd(),
+  options?: { preset?: string }
+): Constraint[] {
+  const merged = getMergedConstraintsConfig(projectRoot, options);
   return [
     ...Object.values(merged.ironLaws),
     ...Object.values(merged.guidelines),
@@ -33,6 +37,30 @@ export function getEffectiveConstraints(projectRoot: string = process.cwd()): Co
   ];
 }
 
+/**
+ * 获取项目当前生效的合并约束配置（ADR-0001 唯一来源的完整形状）
+ *
+ * 与 getEffectiveConstraints 同一生效集链路，返回完整 MergedConstraintsConfig
+ * （含 disabled/custom/unknownIds），供 check 等需要诊断信息的消费方使用。
+ *
+ * options.preset（CLI --preset）仅在项目无自定义配置时覆盖 config.yml 的
+ * preset（工单 23 语义：项目自定义配置优先于 CLI 预设）；不传 preset 时
+ * 完全尊重 config.yml 的 preset 键。
+ *
+ * @param projectRoot 项目根路径（缺省 process.cwd()）
+ */
+export function getMergedConstraintsConfig(
+  projectRoot: string = process.cwd(),
+  options?: { preset?: string }
+): MergedConstraintsConfig {
+  const loader = new ProjectConfigLoader(projectRoot);
+  loader.load();
+  if (loader.hasCustomConfig() || !options?.preset) {
+    return loader.mergeConstraints();
+  }
+  return loader.mergeConstraints({ preset: options.preset });
+}
+
 /**
  * 生效集配置诊断结果
  */

package/src/core/effective-set.ts

@@ -0,0 +1,56 @@
+/**
+ * 生效集共享筛选器（ADR-0001 收口）
+ *
+ * 「config.yml 引用了哪些 id、哪些被禁用」的判定，约束侧与门禁侧共用一份：
+ * - 约束侧（ProjectConfigLoader.mergeConstraints）：未知 id 静默忽略，
+ *   收集进结果 unknownIds 供诊断（历史配置可能存在已移除约束的禁用残留）
+ * - 门禁侧（getEffectiveGates）：未知 id 抛错（闭环校验；gates 配置段为
+ *   新增面，不存在历史残留配置）
+ *
+ * 行为差异仅收敛为 onUnknownId 一个开关，筛选语义两侧一致。
+ */
+
+export interface FilterEnabledEntriesOptions {
+  /** 未知 id 处理：'collect' 收集进结果 unknownIds；'throw' 立即抛错 */
+  onUnknownId: 'collect' | 'throw';
+
+  /** onUnknownId='throw' 时的错误消息定制（如附带可用 id 清单） */
+  unknownIdError?: (id: string) => string;
+}
+
+export interface FilterEnabledEntriesResult {
+  /** enabled === false 的 id（未知 id 若带 enabled:false 同样计入，与历史行为一致） */
+  disabledIds: string[];
+
+  /** 未知 id（仅 onUnknownId='collect' 时非空） */
+  unknownIds: string[];
+}
+
+/**
+ * 按 config 条目筛选：未知 id 按 onUnknownId 处理，enabled:false 收进 disabledIds
+ */
+export function filterEnabledEntries(
+  knownIds: ReadonlySet<string>,
+  entries: Record<string, { enabled?: boolean } | undefined>,
+  options: FilterEnabledEntriesOptions
+): FilterEnabledEntriesResult {
+  const disabledIds: string[] = [];
+  const unknownIds: string[] = [];
+
+  for (const [id, entry] of Object.entries(entries)) {
+    if (!knownIds.has(id)) {
+      if (options.onUnknownId === 'throw') {
+        throw new Error(
+          options.unknownIdError?.(id) ??
+            `[harness] 配置引用了未注册的 id "${id}"。`
+        );
+      }
+      unknownIds.push(id);
+    }
+    if (entry?.enabled === false) {
+      disabledIds.push(id);
+    }
+  }
+
+  return { disabledIds, unknownIds };
+}