@dommaker/harness 1.1.1 → 1.2.1

package/src/cli/commands/constraints-retire.ts

@@ -20,7 +20,8 @@
  *         retired: { at, reason, stats: { total, fail, failRate } }
  *
  * 每条同时写一条 KnowledgeStore 记录（consumptionMode: 'signal'），
- * 并同步 CLAUDE.md 注入段（存在 HARNESS_CONSTRAINTS 标记时）。
+ * 并同步治理注入段（CLAUDE.md 或 AGENTS.md，存在 HARNESS_CONSTRAINTS 标记时；
+ * 落点路由与 init 一致，见 core/constraints/injection-drift resolveInjectionTarget）。
  *
  * retire 不是删除——恢复方法：内置删 config.yml 中 constraints.<id> 段；
  * custom 删 custom-constraints.yml 中 custom_constraints.<id>.retired 段。
@@ -35,7 +36,8 @@ import * as readline from 'readline';
 import * as yaml from 'js-yaml';
 import chalk from 'chalk';
 import { getConstraint } from '../../core/constraints/definitions';
-import { renderConstraintsSection, CONSTRAINTS_START_MARKER, CONSTRAINTS_END_MARKER } from '../../core/constraints/injection-renderer';
+import { renderConstraintsSection, CONSTRAINTS_END_MARKER } from '../../core/constraints/injection-renderer';
+import { resolveInjectionTarget } from '../../core/constraints/injection-drift';
 import { getEffectiveConstraints } from '../../core/effective-constraints';
 import { loadRawProjectConfig, ProjectConfigLoader } from '../../core/project-config-loader';
 import { FileKnowledgeStore } from '../../knowledge/store';
@@ -65,8 +67,10 @@ export interface RetireResult {
   /** 退役落点：custom 约束落 custom-constraints.yml（#82 D6），内置落 config.yml */
   landing: 'config.yml' | 'custom-constraints.yml';
   stats: { total: number; fail: number; failRate: number };
-  /** CLAUDE.md 注入段是否已同步 */
-  claudeMdSynced: boolean;
+  /** 治理注入段（CLAUDE.md / AGENTS.md）是否已同步 */
+  injectionSynced: boolean;
+  /** 实际同步的落点文件（injectionSynced 时存在） */
+  injectionFile?: string;
   /** KnowledgeStore 条目 id（status='retired' 时存在） */
   knowledgeEntryId?: string;
 }
@@ -265,27 +269,25 @@ function saveRetireKnowledge(
 }
 
 /**
- * 同步 CLAUDE.md 注入段（存在 HARNESS_CONSTRAINTS 标记时）
+ * 同步治理注入段（CLAUDE.md 或 AGENTS.md，存在 HARNESS_CONSTRAINTS 标记时）
  *
+ * 落点路由复用 resolveInjectionTarget（studio #307：新模型仓注入段在
+ * AGENTS.md PRESERVE:governance 内；旧模型仓 CLAUDE.md 优先）。
  * 复用 renderConstraintsSection（P3 导出纯函数）按退役后生效集重渲染。
  * 无标记段不动（不追加——retire 不承担 init 职责）。
  */
-function syncClaudeMdInjection(projectRoot: string): boolean {
-  const claudeMdPath = path.join(projectRoot, 'CLAUDE.md');
-  if (!fs.existsSync(claudeMdPath)) return false;
-
-  const content = fs.readFileSync(claudeMdPath, 'utf-8');
-  const startIdx = content.indexOf(CONSTRAINTS_START_MARKER);
-  const endIdx = content.indexOf(CONSTRAINTS_END_MARKER);
-  if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) return false;
+function syncGovernanceInjection(projectRoot: string): { synced: boolean; file?: string } {
+  const target = resolveInjectionTarget(projectRoot);
+  if (!target) return { synced: false };
 
+  const filePath = path.join(projectRoot, target.file);
   const body = renderConstraintsSection(getEffectiveConstraints(projectRoot), getHarnessVersion());
-  const after = content.slice(endIdx + CONSTRAINTS_END_MARKER.length).replace(/^\n+/, '');
-  const newContent = content.slice(0, startIdx) + body + (after ? '\n' + after : '');
-  if (newContent !== content) {
-    fs.writeFileSync(claudeMdPath, newContent, 'utf-8');
+  const after = target.content.slice(target.endIdx + CONSTRAINTS_END_MARKER.length).replace(/^\n+/, '');
+  const newContent = target.content.slice(0, target.startIdx) + body + (after ? '\n' + after : '');
+  if (newContent !== target.content) {
+    fs.writeFileSync(filePath, newContent, 'utf-8');
   }
-  return true;
+  return { synced: true, file: target.file };
 }
 
 /**
@@ -307,7 +309,7 @@ export function retireConstraint(
   const landing: RetireResult['landing'] =
     target?.source === 'custom' ? 'custom-constraints.yml' : 'config.yml';
   if (!target) {
-    return { id, status: 'unknown_id', isIronLaw: false, landing, stats: emptyStats, claudeMdSynced: false };
+    return { id, status: 'unknown_id', isIronLaw: false, landing, stats: emptyStats, injectionSynced: false };
   }
 
   // 已退役保护：内置看 config.yml constraints.<id>.enabled === false；
@@ -318,10 +320,10 @@ export function retireConstraint(
     const loader = new ProjectConfigLoader(projectRoot);
     loader.load();
     if (loader.getCustomConstraints()[id]?.retired || existing?.enabled === false) {
-      return { id, status: 'already_retired', isIronLaw: target.isIronLaw, landing, stats: emptyStats, claudeMdSynced: false };
+      return { id, status: 'already_retired', isIronLaw: target.isIronLaw, landing, stats: emptyStats, injectionSynced: false };
     }
   } else if (existing?.enabled === false) {
-    return { id, status: 'already_retired', isIronLaw: target.isIronLaw, landing, stats: emptyStats, claudeMdSynced: false };
+    return { id, status: 'already_retired', isIronLaw: target.isIronLaw, landing, stats: emptyStats, injectionSynced: false };
   }
 
   // 历史统计（来自 traces.log）
@@ -346,10 +348,19 @@ export function retireConstraint(
   // 2. KnowledgeStore
   const knowledgeEntryId = saveRetireKnowledge(projectRoot, id, target, reason, stats, iso);
 
-  // 3. CLAUDE.md 注入段同步
-  const claudeMdSynced = syncClaudeMdInjection(projectRoot);
+  // 3. 治理注入段同步（CLAUDE.md / AGENTS.md，路由见 syncGovernanceInjection）
+  const injection = syncGovernanceInjection(projectRoot);
 
-  return { id, status: 'retired', isIronLaw: target.isIronLaw, landing, stats, claudeMdSynced, knowledgeEntryId };
+  return {
+    id,
+    status: 'retired',
+    isIronLaw: target.isIronLaw,
+    landing,
+    stats,
+    injectionSynced: injection.synced,
+    injectionFile: injection.file,
+    knowledgeEntryId,
+  };
 }
 
 /**
@@ -367,8 +378,8 @@ export function printRetireResult(result: RetireResult): void {
       console.log(chalk.green(`✅ ${result.id}: 已退役`));
       console.log(`   历史统计: total=${result.stats.total} fail=${result.stats.fail} fail率=${Math.round(result.stats.failRate * 100)}%`);
       console.log(`   知识沉淀: ${result.knowledgeEntryId}（.harness/knowledge）`);
-      if (result.claudeMdSynced) {
-        console.log('   已同步 CLAUDE.md 注入段');
+      if (result.injectionSynced) {
+        console.log(`   已同步 ${result.injectionFile ?? '治理文档'} 注入段`);
       }
       const recovery =
         result.landing === 'custom-constraints.yml'
@@ -485,7 +496,7 @@ export async function runRetireInteractive(
       }
       console.log(`  - KnowledgeStore: 写入 constraint-retired-${p.id}`);
     }
-    console.log('  - CLAUDE.md: 若含 HARNESS_CONSTRAINTS 标记段则同步重渲染');
+    console.log('  - CLAUDE.md / AGENTS.md: 若含 HARNESS_CONSTRAINTS 标记段则同步重渲染');
     const finalConfirm = await ask('确认执行？(y/N) ');
     if (finalConfirm.toLowerCase() !== 'y' && finalConfirm.toLowerCase() !== 'yes') {
       console.log('已取消');

package/src/cli/commands/definitions.ts

@@ -81,6 +81,8 @@ export interface CommandDefinition {
   subcommands?: Record<string, CommandSubcommand>;
   /** false = 未知位置参数不报错、落回默认 action（spec 的文件参数用法） */
   subcommandStrict?: boolean;
+  /** true = 有 subcommands 但无位置参数时运行默认 action 而非显示帮助（门禁命令语义） */
+  bareRunsAction?: boolean;
   /** 选项条件路由（匹配时替代默认 action 执行） */
   optionRoutes?: CommandOptionRoute[];
   /** 默认 action 实参构造（缺省为 [options]） */

package/src/cli/commands/init.ts

@@ -37,19 +37,15 @@ export interface InitOptions {
 
 /**
  * 默认配置
+ *
+ * 只写有运行时消费者的字段：preset（ADR-0001 生效集链路由 mergeConstraints 消费）。
+ * 历史模板里的 enabled / ironLaws.enforceErrors / ironLaws.warnWarnings /
+ * validators.{checkpoint,passesGate,cso} 均为零消费者的死字段，不再写入；
+ * strict/standard/relaxed 三档差异曾只存在于这些死字段上（实为两档），
+ * 现在三档差异完全由 preset 键经生效集链路体现。
  */
 const DEFAULT_CONFIG = {
   preset: 'standard',
-  enabled: true,
-  ironLaws: {
-    enforceErrors: true,
-    warnWarnings: true,
-  },
-  validators: {
-    checkpoint: true,
-    passesGate: true,
-    cso: false,
-  },
 };
 
 /**
@@ -59,15 +55,6 @@ const PRESETS = {
   strict: {
     ...DEFAULT_CONFIG,
     preset: 'strict',
-    ironLaws: {
-      enforceErrors: true,
-      warnWarnings: true,
-    },
-    validators: {
-      checkpoint: true,
-      passesGate: true,
-      cso: true,
-    },
   },
   standard: {
     ...DEFAULT_CONFIG,
@@ -76,10 +63,6 @@ const PRESETS = {
   relaxed: {
     ...DEFAULT_CONFIG,
     preset: 'relaxed',
-    ironLaws: {
-      enforceErrors: true,
-      warnWarnings: false,
-    },
   },
 };
 
@@ -483,7 +466,6 @@ custom_constraints:
   #   rule: "NO MOMENT.JS IMPORTS"
   #   message: "禁止使用 moment.js，请使用 date-fns 或 dayjs"
   #   trigger: ["code_implementation"]
-  #   exceptions: ["legacy_migration"]
 
   # 示例 3：要求特定的文件命名
   # my_project_component_naming:
@@ -492,19 +474,6 @@ custom_constraints:
   #   rule: "REACT COMPONENTS SHOULD BE PASCAL CASE"
   #   message: "React 组件文件名应使用 PascalCase"
   #   trigger: ["file_creation"]
-
-# ========================================
-# 扩展内置约束的例外
-# ========================================
-
-# 如果需要为内置约束添加项目特定的例外，
-# 可以在 .harness/config.yml 中配置：
-
-# constraints:
-#   no_fix_without_root_cause:
-#     # 添加项目特定的例外
-#     exceptions:
-#       - my_custom_exception
 `;
 
   await fs.writeFile(customConstraintsPath, content, 'utf-8');
@@ -600,7 +569,102 @@ export async function setupClaudeMdOutputStyle(projectPath: string): Promise<voi
 }
 
 /**
- * 在 CLAUDE.md 中写入/更新 Governance Rules 约束段
+ * 治理契约 PRESERVE 段标记（studio #302，ADR 2026-08-21 落点模型：
+ * 治理契约正本住 AGENTS.md 手写 PRESERVE 段，sync-docs 重新生成时原样保留）
+ */
+const GOVERNANCE_PRESERVE_BEGIN = '<!-- PRESERVE:governance -->';
+const GOVERNANCE_PRESERVE_END = '<!-- /PRESERVE:governance -->';
+
+/**
+ * 在 AGENTS.md 的 PRESERVE:governance 段写入/更新 Governance Rules 约束段（新落点模型）
+ *
+ * - AGENTS.md 不存在：创建最小骨架（标题 + 说明 + PRESERVE:governance 段），
+ *   完整导读由 `harness sync-docs --agents` 生成，PRESERVE 段在重新生成时原样保留
+ * - 已有 PRESERVE:governance 段：段内机器管理的只有 HARNESS_CONSTRAINTS 标记区间——
+ *   有标记则只替换标记区间，段内其余手写内容（治理契约引言/流程/纪律等）原样保留；
+ *   无标记（纯手写段）则在段尾追加注入段，不动手写内容
+ * - 无该段：在文件末尾追加
+ * - 段标记残缺（只有单边标记）：不写入，告警交由人工修复（防二次损坏）
+ */
+export async function setupAgentsMdConstraints(projectPath: string): Promise<void> {
+  const agentsMdPath = path.join(projectPath, 'AGENTS.md');
+  const version = getPackageVersion();
+
+  const constraints = getEffectiveConstraints(projectPath);
+  const bodyOnly = renderConstraintsSection(constraints, version);
+  const block = `${GOVERNANCE_PRESERVE_BEGIN}\n## Governance Rules\n${bodyOnly}${GOVERNANCE_PRESERVE_END}\n`;
+
+  let existingContent: string | null = null;
+  try {
+    existingContent = await fs.readFile(agentsMdPath, 'utf-8');
+  } catch {
+    // AGENTS.md 不存在
+  }
+
+  if (existingContent === null) {
+    const skeleton = [
+      '# AGENTS.md',
+      '',
+      '> 机器生成部分由 `harness sync-docs --agents` 维护；`PRESERVE:governance` 段是治理契约正本（手写/治理变更流程管控），重新生成时原样保留。',
+      '',
+      block,
+    ].join('\n');
+    await fs.writeFile(agentsMdPath, skeleton, 'utf-8');
+    console.log(chalk.green(`✅ 已创建 AGENTS.md 并写入治理契约 PRESERVE:governance 段 (v${version})`));
+    return;
+  }
+
+  const startIdx = existingContent.indexOf(GOVERNANCE_PRESERVE_BEGIN);
+  const endIdx = existingContent.indexOf(GOVERNANCE_PRESERVE_END);
+
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    // 段内机器管理的只有 HARNESS_CONSTRAINTS 标记区间；其余手写内容原样保留
+    const before = existingContent.slice(0, startIdx);
+    const blockContent = existingContent.slice(startIdx + GOVERNANCE_PRESERVE_BEGIN.length, endIdx);
+    const after = existingContent.slice(endIdx + GOVERNANCE_PRESERVE_END.length).replace(/^\n+/, '');
+
+    const csIdx = blockContent.indexOf(CONSTRAINTS_START_MARKER);
+    const ceIdx = blockContent.indexOf(CONSTRAINTS_END_MARKER);
+    let newBlockContent: string;
+    if (csIdx !== -1 && ceIdx !== -1 && ceIdx > csIdx) {
+      // 只替换标记区间。bodyOnly 自带结尾换行，故剥掉尾部恰好一个前导换行
+      // （END 标记行的行尾换行），其余手写内容逐字保留，保证幂等。
+      newBlockContent =
+        blockContent.slice(0, csIdx) +
+        bodyOnly +
+        blockContent.slice(ceIdx + CONSTRAINTS_END_MARKER.length).replace(/^\n/, '');
+    } else {
+      // 纯手写段（无约束标记）：段尾追加注入段，手写内容不动
+      newBlockContent = blockContent.trimEnd() + '\n\n## Governance Rules\n' + bodyOnly;
+    }
+
+    const newContent =
+      before +
+      GOVERNANCE_PRESERVE_BEGIN +
+      newBlockContent +
+      GOVERNANCE_PRESERVE_END +
+      '\n' +
+      (after ? '\n' + after : '');
+    if (newContent !== existingContent) {
+      await fs.writeFile(agentsMdPath, newContent, 'utf-8');
+      console.log(chalk.green(`✅ 已更新 AGENTS.md 治理契约 PRESERVE:governance 段 (v${version})`));
+    }
+    return;
+  }
+
+  if (startIdx !== -1 || endIdx !== -1) {
+    console.log(chalk.yellow('⚠️  AGENTS.md 中 PRESERVE:governance 标记残缺（只有单边），跳过治理契约写入，请人工修复'));
+    return;
+  }
+
+  // 无该段：文件末尾追加
+  const newContent = existingContent.trimEnd() + '\n\n' + block;
+  await fs.writeFile(agentsMdPath, newContent, 'utf-8');
+  console.log(chalk.green(`✅ 已追加治理契约 PRESERVE:governance 段到 AGENTS.md (v${version})`));
+}
+
+/**
+ * 在 CLAUDE.md 中写入/更新 Governance Rules 约束段（旧落点模型，向后兼容保留）
  *
  * - 约束集来自 getEffectiveConstraints（ADR-0001）：preset 裁剪、config.yml
  *   禁用、custom 追加、scenes 过滤全部反映在注入文本里
@@ -663,6 +727,30 @@ export async function setupClaudeMdConstraints(projectPath: string): Promise<voi
   }
 }
 
+/**
+ * 治理约束段写入落点路由（studio #302，ADR 2026-08-21 落点模型）
+ *
+ * - 旧模型仓（CLAUDE.md 已有 HARNESS_CONSTRAINTS 标记或 `## Governance Rules` 块）：
+ *   继续写 CLAUDE.md——init 幂等重跑不破坏既有仓，不制造双份约束正本
+ * - 其余（新仓初始化）：写 AGENTS.md PRESERVE:governance 段（入库公共面正本）
+ */
+export async function setupGovernanceConstraints(projectPath: string): Promise<void> {
+  let claudeContent: string | null = null;
+  try {
+    claudeContent = await fs.readFile(path.join(projectPath, 'CLAUDE.md'), 'utf-8');
+  } catch {
+    // CLAUDE.md 不存在 → 新仓
+  }
+
+  if (
+    claudeContent !== null &&
+    (claudeContent.includes(CONSTRAINTS_START_MARKER) || /^##\s+Governance Rules/m.test(claudeContent))
+  ) {
+    return setupClaudeMdConstraints(projectPath);
+  }
+  return setupAgentsMdConstraints(projectPath);
+}
+
 /**
  * 设置治理相关文件
  */
@@ -679,8 +767,9 @@ async function setupGovernance(projectPath: string, level: string): Promise<void
   // 2. 在 CLAUDE.md 中写入 Output Style 段（仅在不存在时创建）
   await setupClaudeMdOutputStyle(projectPath);
 
-  // 3. 在 CLAUDE.md 中写入/更新 Governance Rules 约束段
-  await setupClaudeMdConstraints(projectPath);
+  // 3. 写入/更新 Governance Rules 约束段（新仓 → AGENTS.md PRESERVE:governance；
+  //    旧模型仓 → CLAUDE.md，落点路由见 setupGovernanceConstraints）
+  await setupGovernanceConstraints(projectPath);
 
   // 4. 生成 CONTEXT.md 文件
   const contextConfig = governance.context_files as Record<string, unknown> | undefined;

package/src/cli/commands/knowledge.ts

@@ -81,22 +81,7 @@ export async function knowledgeSearch(
   const store = new KnowledgeStore({ baseDir: getKnowledgeDir(options.projectPath) });
   const queryEngine = new KnowledgeQuery(store);
 
-  const budget = {
-    phase: 'cli',
-    maxTokens: 10000,
-    maxEntries: options.limit || 20,
-    focusTypes: [] as KnowledgeSubsystem[],
-  };
-
-  const result = queryEngine.query(budget);
-
-  // 简单文本匹配过滤
-  const q = query.toLowerCase();
-  const matched = result.entries.filter(e =>
-    e.title.toLowerCase().includes(q) ||
-    e.content.toLowerCase().includes(q) ||
-    e.tags.some(t => t.toLowerCase().includes(q))
-  );
+  const matched = queryEngine.search(query, { limit: options.limit || 20 });
 
   if (options.json) {
     console.log(JSON.stringify({ query, total: matched.length, entries: matched }, null, 2));

package/src/cli/commands/report.ts

@@ -7,7 +7,6 @@
 import chalk from 'chalk';
 import * as fs from 'fs/promises';
 import { ConstraintChecker } from '../../core/constraints/checker';
-import { getTraceCollector } from '../../monitoring/traces';
 import { IRON_LAWS, GUIDELINES, PROMPTS } from '../../core/constraints/definitions';
 import { executeWithCollect } from '../../failure/constraint-handler';
 import type { ConstraintContext } from '../../types/constraint';
@@ -48,7 +47,6 @@ export async function report(options: ReportOptions): Promise<void> {
 
   const projectPath = options.projectPath || process.cwd();
   const checker = ConstraintChecker.getInstance();
-  checker.setTraceRecorder(getTraceCollector());
 
   const allConstraints = { ...IRON_LAWS, ...GUIDELINES, ...PROMPTS };
   const totalConstraints = Object.keys(allConstraints).length;

package/src/cli/commands/status.ts

@@ -109,7 +109,7 @@ export async function status(options: StatusOptions): Promise<void> {
       const status = s.passRate >= 1 ? '✅' : '❌';
       console.log(`  ${status} ${s.constraintId}`);
       if (options.detail) {
-        console.log(chalk.gray(`     检查: ${s.totalChecks} | 通过: ${(s.passRate * 100).toFixed(0)}% | 绕过: ${(s.bypassRate * 100).toFixed(0)}%`));
+        console.log(chalk.gray(`     检查: ${s.totalChecks} | 通过: ${(s.passRate * 100).toFixed(0)}% | 失败: ${(s.failRate * 100).toFixed(0)}%`));
       }
     });
     console.log();
@@ -123,7 +123,7 @@ export async function status(options: StatusOptions): Promise<void> {
       const status = s.passRate >= 0.8 ? '✅' : s.passRate >= 0.5 ? '⚠️' : '❌';
       console.log(`  ${status} ${s.constraintId}`);
       if (options.detail) {
-        console.log(chalk.gray(`     检查: ${s.totalChecks} | 通过: ${(s.passRate * 100).toFixed(0)}% | 绕过: ${(s.bypassRate * 100).toFixed(0)}%`));
+        console.log(chalk.gray(`     检查: ${s.totalChecks} | 通过: ${(s.passRate * 100).toFixed(0)}% | 失败: ${(s.failRate * 100).toFixed(0)}%`));
       }
     });
     console.log();

package/src/context/index.ts

@@ -1,11 +1,34 @@
 /**
- * 上下文管理模块
+ * 上下文管理模块（ADR-0003：显式清单，禁 export *）
  *
  * Token 预算 + 会话压缩 + 知识注入
  */
 
-export * from './types';
-export * from './token-budget';
-export * from './compaction';
-export * from './session-manager';
-export * from './knowledge-injector';
+// 类型
+export type {
+  CompactionConfig,
+  CompactionLevel,
+  ContextSource,
+  ContextSourceType,
+  ContextUsageSnapshot,
+  SessionCheckpoint,
+  SessionEvent,
+  SessionEventType,
+  SessionHandle,
+  SessionMessage,
+} from './types';
+export { DEFAULT_COMPACTION_CONFIG } from './types';
+
+// Token 预算
+export { AdaptiveTokenBudget, TokenBudget, TokenEstimator } from './token-budget';
+
+// 会话压缩
+export { SessionCompaction } from './compaction';
+export type { CompactionResult } from './compaction';
+
+// 会话管理
+export { SessionManager } from './session-manager';
+
+// 知识注入
+export { KnowledgeInjector } from './knowledge-injector';
+export type { InjectionConfig, InjectionResult } from './knowledge-injector';

package/src/core/CONTEXT.md

@@ -4,12 +4,13 @@
 约束引擎核心：check/prompt 二元约束系统（ADR-0001）、生效集合并（effective-constraints）、检查点验证器(CSO/passes-gate)、会话管理、Spec 验证器、项目配置加载。
 
 ## 核心导出
-- `constraints/` — 约束定义(IRON_LAWS/GUIDELINES/PROMPTS) + 检查引擎(ConstraintChecker) + 拦截器(ConstraintInterceptor) + 缓存(CheckCache：TTL 缓存 + 计数采样，H6/G5 起公开导出) + 注入渲染(injection-renderer) + Agent prompt 渲染(agent-prompt-renderer：trigger 参数化分组渲染，role 路由留 studio，H6/G6)/漂移校验(injection-drift)/使用统计(usage-report)
-- `effective-constraints.ts` — `getEffectiveConstraints(projectRoot)`：全仓唯一生效集来源（内置 → preset → config.yml 禁用（内置与 custom 同效）→ custom 追加（禁用/已退役的不追加）→ scenes 过滤）；`lintEffectiveConfig` 配置诊断
+- `constraints/` — 约束定义(IRON_LAWS/GUIDELINES/PROMPTS) + 检查引擎(ConstraintChecker，拦截统一由 checkBeforeExecution 承担，ADR-0004) + 缓存(CheckCache：TTL 缓存 + 计数采样，H6/G5 起公开导出) + 注入渲染(injection-renderer) + Agent prompt 渲染(agent-prompt-renderer：trigger 参数化分组渲染，role 路由留 studio，H6/G6)/漂移校验(injection-drift：含注入段落点路由 resolveInjectionTarget，CLAUDE.md 有标记优先、否则 AGENTS.md PRESERVE:governance，studio #307)/使用统计(usage-report)；CheckEnv 生产侧唯一构造点 `buildCheckEnv(context, providers|'none')`（checkers/types.ts：providers = 证据接线，'none' = 显式不接 → evidence flag checker 按契约 skip）
+- `effective-constraints.ts` — `getEffectiveConstraints(projectRoot, {preset?})`：全仓唯一生效集来源（内置 → preset → config.yml 禁用（内置与 custom 同效）→ custom 追加（禁用/已退役的不追加）→ scenes 过滤）；`getMergedConstraintsConfig(projectRoot, {preset?})`：同链路的完整 MergedConstraintsConfig 形状（含 disabled/custom/unknownIds），内置工单 23 优先级规则（--preset 仅在无项目自定义配置时生效），check 命令经此入口；`lintEffectiveConfig` 配置诊断
+- `effective-set.ts` — `filterEnabledEntries(knownIds, entries, {onUnknownId})`：约束侧（collect）与门禁侧（throw）共用的 config 条目筛选器
 - `validators/` — checkpoints、passes-gate、CSO 验证器
 - `session/` — 会话管理
 - `spec/validator` — SpecValidator
-- `project-config-loader` — 项目配置加载 + 约束合并
+- `project-config-loader` — 项目配置加载 + 约束合并（mergeConstraints 内含 preset 裁剪：presets/ 纯数据 + 未知名回落 standard，禁用到未知 id 经 effective-set 共享筛选器 collect 模式）
 
 ## 依赖关系
 - 被所有模块依赖（基础层，无上层依赖）

package/src/core/__tests__/effective-set.test.ts

@@ -0,0 +1,80 @@
+/**
+ * effective-set 共享筛选器测试
+ *
+ * 覆盖约束侧（collect）与门禁侧（throw）两种 onUnknownId 模式。
+ */
+
+import { filterEnabledEntries } from '../effective-set';
+
+const KNOWN = new Set(['a', 'b', 'c']);
+
+describe('filterEnabledEntries', () => {
+  describe('onUnknownId: collect（约束侧）', () => {
+    it('已知 id 全部通过，enabled:false 收进 disabledIds', () => {
+      const result = filterEnabledEntries(
+        KNOWN,
+        { a: { enabled: false }, b: { enabled: true }, c: {} },
+        { onUnknownId: 'collect' }
+      );
+      expect(result.disabledIds).toEqual(['a']);
+      expect(result.unknownIds).toEqual([]);
+    });
+
+    it('未知 id 静默忽略并收集进 unknownIds', () => {
+      const result = filterEnabledEntries(
+        KNOWN,
+        { a: {}, ghost: { enabled: false } },
+        { onUnknownId: 'collect' }
+      );
+      expect(result.unknownIds).toEqual(['ghost']);
+      // 未知 id 带 enabled:false 同样计入 disabledIds（历史行为：delete 空桶为 no-op）
+      expect(result.disabledIds).toEqual(['ghost']);
+    });
+
+    it('未知 id 无 enabled 标记时只收集不进 disabledIds', () => {
+      const result = filterEnabledEntries(
+        KNOWN,
+        { ghost: {} },
+        { onUnknownId: 'collect' }
+      );
+      expect(result.unknownIds).toEqual(['ghost']);
+      expect(result.disabledIds).toEqual([]);
+    });
+
+    it('空 entries → 空结果', () => {
+      const result = filterEnabledEntries(KNOWN, {}, { onUnknownId: 'collect' });
+      expect(result).toEqual({ disabledIds: [], unknownIds: [] });
+    });
+  });
+
+  describe('onUnknownId: throw（门禁侧）', () => {
+    it('未知 id 抛错（默认消息）', () => {
+      expect(() =>
+        filterEnabledEntries(KNOWN, { nope: { enabled: false } }, { onUnknownId: 'throw' })
+      ).toThrow(/未注册的 id "nope"/);
+    });
+
+    it('未知 id 抛错（unknownIdError 定制消息）', () => {
+      expect(() =>
+        filterEnabledEntries(
+          KNOWN,
+          { nope: {} },
+          {
+            onUnknownId: 'throw',
+            unknownIdError: id => `gates.${id} 引用了未注册的门禁。可用门禁: a, b, c。`,
+          }
+        )
+      ).toThrow(/gates\.nope 引用了未注册的门禁/);
+    });
+
+    it('已知 id 的 enabled:false 正常收集，不抛错', () => {
+      const result = filterEnabledEntries(
+        KNOWN,
+        { a: { enabled: false }, b: { enabled: true } },
+        { onUnknownId: 'throw' }
+      );
+      expect(result.disabledIds).toEqual(['a']);
+      expect(result.unknownIds).toEqual([]);
+    });
+  });
+});