@dommaker/harness 1.1.1 → 1.2.1

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

@@ -3,6 +3,8 @@
  *
  * - 三类漂移各自检出：版本 / 内容（条目级 missing/extra）/ 重复章节
  * - 无漂移静默；无标记段 = 未注入不算漂移；CLAUDE.md 不存在不算漂移
+ * - 落点路由（studio #307）：AGENTS.md PRESERVE:governance 内注入段同样校验；
+ *   两文件均有标记段时 CLAUDE.md 优先（旧模型仓豁免）
  * - config.yml 变更后未重跑 init → 内容漂移（extra）
  *
  * 使用真实临时目录（getEffectiveConstraints 读真实 fs）。
@@ -33,6 +35,17 @@ function writeSyncedClaudeMd(root: string, extra = ''): string {
   return content;
 }
 
+/** 新模型仓注入段：AGENTS.md `PRESERVE:governance` 段内含标记段（版本 TEST_VERSION） */
+function writeSyncedAgentsMd(root: string, extra = ''): string {
+  const section =
+    '<!-- PRESERVE:governance -->\n## Governance Rules\n' +
+    renderConstraintsSection(getEffectiveConstraints(root), TEST_VERSION) +
+    '<!-- /PRESERVE:governance -->\n';
+  const content = `# AGENTS.md\n\n${section}${extra}`;
+  fs.writeFileSync(path.join(root, 'AGENTS.md'), content, 'utf-8');
+  return content;
+}
+
 describe('detectInjectionDrift', () => {
   it('无漂移：注入段与期望渲染一致 → hasDrift=false', () => {
     const root = makeTmpProject();
@@ -161,4 +174,81 @@ describe('detectInjectionDrift', () => {
 
     expect(drift.versionDrift).toEqual({ expected: TEST_VERSION, actual: '(缺失)' });
   });
+
+  it('新模型仓：AGENTS.md PRESERVE:governance 注入段一致 → 无漂移，injectionFile=AGENTS.md', () => {
+    const root = makeTmpProject();
+    writeSyncedAgentsMd(root);
+
+    const drift = detectInjectionDrift(root, TEST_VERSION);
+
+    expect(drift.notInjected).toBe(false);
+    expect(drift.injectionFile).toBe('AGENTS.md');
+    expect(drift.hasDrift).toBe(false);
+    expect(drift.duplicateHeading).toBe(false);
+  });
+
+  it('新模型仓：版本漂移与内容漂移照常检出', () => {
+    const root = makeTmpProject();
+    const synced = writeSyncedAgentsMd(root);
+    const originalLine = synced.split('\n').find(l => l.startsWith('- **'))!;
+    const editedLine = originalLine.replace(/: .+$/, ': 手工篡改的注入文本');
+    fs.writeFileSync(
+      path.join(root, 'AGENTS.md'),
+      synced
+        .replace(`<!-- version: ${TEST_VERSION} -->`, '<!-- version: 0.0.1-old -->')
+        .replace(originalLine, editedLine),
+      'utf-8'
+    );
+
+    const drift = detectInjectionDrift(root, TEST_VERSION);
+
+    expect(drift.injectionFile).toBe('AGENTS.md');
+    expect(drift.hasDrift).toBe(true);
+    expect(drift.versionDrift).toEqual({ expected: TEST_VERSION, actual: '0.0.1-old' });
+    expect(drift.contentDrift!.missing).toEqual([originalLine]);
+    expect(drift.contentDrift!.extra).toEqual([editedLine]);
+  });
+
+  it('新模型仓：PRESERVE 段之外还有 ## Governance Rules 标题 → duplicateHeading', () => {
+    const root = makeTmpProject();
+    writeSyncedAgentsMd(root, '\n## Governance Rules\n\n旧版遗留的同名章节\n');
+
+    const drift = detectInjectionDrift(root, TEST_VERSION);
+
+    expect(drift.injectionFile).toBe('AGENTS.md');
+    expect(drift.duplicateHeading).toBe(true);
+    expect(drift.hasDrift).toBe(true);
+  });
+
+  it('两文件均有标记段：旧模型仓豁免，CLAUDE.md 优先（AGENTS.md 漂移不影响判定）', () => {
+    const root = makeTmpProject();
+    writeSyncedClaudeMd(root);
+    const agents = writeSyncedAgentsMd(root);
+    // AGENTS.md 注入段手改出漂移，CLAUDE.md 保持一致
+    fs.writeFileSync(
+      path.join(root, 'AGENTS.md'),
+      agents.replace(`<!-- version: ${TEST_VERSION} -->`, '<!-- version: 0.0.1-old -->'),
+      'utf-8'
+    );
+
+    const drift = detectInjectionDrift(root, TEST_VERSION);
+
+    expect(drift.injectionFile).toBe('CLAUDE.md');
+    expect(drift.hasDrift).toBe(false);
+  });
+
+  it('两处均无标记段但 AGENTS.md 有重复 Governance Rules 标题 → notInjected + duplicateHeading', () => {
+    const root = makeTmpProject();
+    fs.writeFileSync(
+      path.join(root, 'AGENTS.md'),
+      '# AGENTS.md\n\n## Governance Rules\n\n甲\n\n## Governance Rules\n\n乙\n',
+      'utf-8'
+    );
+
+    const drift = detectInjectionDrift(root, TEST_VERSION);
+
+    expect(drift.notInjected).toBe(true);
+    expect(drift.hasDrift).toBe(false);
+    expect(drift.duplicateHeading).toBe(true);
+  });
 });

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

@@ -9,9 +9,16 @@
 
 import * as fs from 'fs';
 import { IRON_LAWS, GUIDELINES } from './definitions';
+import { COMMAND_DEFINITIONS } from '../../cli/commands/definitions';
+import { GATE_DEFINITIONS } from '../../gates/definitions';
 import { FreshnessRunner } from './doc-freshness/runner';
 import type { DocFreshnessCheck } from '../../types/project-config';
 
+/** CLI 命令数 = 非门禁命令定义 + 门禁命令定义（ADR-0002：定义表是命令形状单一来源） */
+function cliCommandCount(): number {
+  return COMMAND_DEFINITIONS.length + GATE_DEFINITIONS.filter(g => g.cli).length;
+}
+
 /** 匹配表格单元格中的源码文件条目（如 `src/foo.ts`、`foo.tsx`） */
 const FILE_CELL_REGEX = /\|\s*([^|]+?\.(?:ts|tsx|js|jsx))\s*\|/g;
 
@@ -104,41 +111,40 @@ export function aggregateToSourceSubdir(root: string, file: string): string {
 
 // ── 能力清单计数 ────────────────────────────────────────────
 
+/**
+ * 能力清单统计规则单份定义（ADR-0008：check/write 两方向共用，
+ * 此前 label+pattern 在 buildCapabilityChecks 与 updateCapabilityCounts 各写一遍）
+ *
+ * - label：CAPABILITIES.md 计数行 label（check 的 DocFreshnessCheck.label +
+ *   write 的替换文本前缀，如 `Quality Gates (6)`）
+ * - pattern：同时供 check（doc_regex_count 字符串 pattern，捕获组为文档计数）
+ *   与 write（编译为替换 regex）
+ * - actual：定义表实际计数（ADR-0002 单一来源）
+ */
+interface CapabilityCountRule {
+  label: string;
+  pattern: string;
+  actual: () => number;
+}
+
+const CAPABILITY_COUNT_RULES: CapabilityCountRule[] = [
+  { label: 'CLI Commands', pattern: 'CLI Commands\\s*\\((\\d+)\\)', actual: cliCommandCount },
+  { label: 'Quality Gates', pattern: 'Quality Gates?\\s*\\((\\d+)\\)', actual: () => GATE_DEFINITIONS.length },
+  { label: 'Iron Laws', pattern: 'Iron Laws?\\s*\\((\\d+)\\)', actual: () => Object.keys(IRON_LAWS).length },
+  { label: 'Guidelines', pattern: 'Guidelines?\\s*\\((\\d+)\\)', actual: () => Object.keys(GUIDELINES).length },
+];
+
 /**
  * 构建 CAPABILITIES.md 能力清单格式的检查配置
  */
 function buildCapabilityChecks(): DocFreshnessCheck[] {
-  return [
-    {
-      type: 'doc_regex_count',
-      doc: 'CAPABILITIES.md',
-      label: 'CLI Commands',
-      pattern: 'CLI Commands\\s*\\((\\d+)\\)',
-      // index.ts（已删 barrel）与 definitions.ts（命令注册表纯数据）不是命令实现，不计入
-      actual: { kind: 'dir_count', path: 'src/cli/commands', extension: '.ts', exclude: ['index.ts', 'definitions.ts'] },
-    },
-    {
-      type: 'doc_regex_count',
-      doc: 'CAPABILITIES.md',
-      label: 'Quality Gates',
-      pattern: 'Quality Gates?\\s*\\((\\d+)\\)',
-      actual: { kind: 'dir_count', path: 'src/gates', extension: '.ts', exclude: ['index.ts', 'types.ts'] },
-    },
-    {
-      type: 'doc_regex_count',
-      doc: 'CAPABILITIES.md',
-      label: 'Iron Laws',
-      pattern: 'Iron Laws?\\s*\\((\\d+)\\)',
-      actual: { kind: 'const_count', value: Object.keys(IRON_LAWS).length },
-    },
-    {
-      type: 'doc_regex_count',
-      doc: 'CAPABILITIES.md',
-      label: 'Guidelines',
-      pattern: 'Guidelines?\\s*\\((\\d+)\\)',
-      actual: { kind: 'const_count', value: Object.keys(GUIDELINES).length },
-    },
-  ];
+  return CAPABILITY_COUNT_RULES.map(rule => ({
+    type: 'doc_regex_count' as const,
+    doc: 'CAPABILITIES.md',
+    label: rule.label,
+    pattern: rule.pattern,
+    actual: { kind: 'const_count' as const, value: rule.actual() },
+  }));
 }
 
 /**
@@ -164,26 +170,14 @@ export function checkCapabilityCounts(
 /**
  * 更新 CAPABILITIES.md 中的能力清单计数（write 模式）
  *
- * 使用 FreshnessRunner 获取实际计数，然后 regex 替换文档计数行。
+ * 命令/门禁计数取自定义表（ADR-0002 单一来源），regex 替换文档计数行；
+ * 规则与 check 方向共用 CAPABILITY_COUNT_RULES（ADR-0008）。
  */
-export function updateCapabilityCounts(content: string, projectPath: string): string {
-  const runner = new FreshnessRunner();
-
-  const cliCount = runner.countFromDir('src/cli/commands', '.ts', ['index.ts', 'definitions.ts'], projectPath);
-  const gateCount = runner.countFromDir('src/gates', '.ts', ['index.ts', 'types.ts'], projectPath);
-  const ironCount = Object.keys(IRON_LAWS).length;
-  const guideCount = Object.keys(GUIDELINES).length;
-
-  const replacements: [RegExp, string][] = [
-    [/CLI Commands\s*\(\d+\)/, `CLI Commands (${cliCount})`],
-    [/Quality Gates?\s*\(\d+\)/, `Quality Gates (${gateCount})`],
-    [/Iron Laws?\s*\(\d+\)/, `Iron Laws (${ironCount})`],
-    [/Guidelines?\s*\(\d+\)/, `Guidelines (${guideCount})`],
-  ];
-
-  for (const [regex, replacement] of replacements) {
+export function updateCapabilityCounts(content: string, _projectPath: string): string {
+  for (const rule of CAPABILITY_COUNT_RULES) {
+    const regex = new RegExp(rule.pattern);
     if (regex.test(content)) {
-      content = content.replace(regex, replacement);
+      content = content.replace(regex, `${rule.label} (${rule.actual()})`);
     }
   }
 

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/governance-presence.ts

@@ -0,0 +1,74 @@
+/**
+ * governance_presence：治理契约在场守护（studio #302，ADR 2026-08-21 落点模型）
+ *
+ * 治理契约正本 = AGENTS.md 手写 `PRESERVE:governance` 段（旧模型仓 = CLAUDE.md
+ * Governance Rules / HARNESS_CONSTRAINTS 注入段）。PRESERVE 只保「存在」不保「在场」：
+ * 段被删除/掏空后 sync-docs 重新生成会静默丢失，此处补「在场」校验。
+ *
+ * ADR-0001 存在性探测：项目未采用 harness 治理（无 .harness/config.yml）→ skip。
+ * 向后兼容：旧模型仓（CLAUDE.md 有治理块、AGENTS.md 无 PRESERVE:governance）→ pass，
+ * 不强制迁移；两处都没有才报违规。
+ */
+
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { loadRawProjectConfig } from '../../project-config-loader';
+import type { ConstraintCheck } from './types';
+
+/** 治理契约 PRESERVE 段名（ADR 落点模型约定） */
+export const GOVERNANCE_PRESERVE_NAME = 'governance';
+
+const GOVERNANCE_BEGIN_RE = /^<!-- PRESERVE:governance -->\s*$/m;
+
+/** AGENTS.md 是否存在非空 PRESERVE:governance 块（标记须独占一行，与 preserve-block.ts 同语义） */
+export function hasGovernancePreserveBlock(agentsMdPath: string): boolean {
+  let content: string;
+  try {
+    content = readFileSync(agentsMdPath, 'utf-8');
+  } catch {
+    return false;
+  }
+  const beginMatch = GOVERNANCE_BEGIN_RE.exec(content);
+  if (!beginMatch) return false;
+  const rest = content.slice(beginMatch.index + beginMatch[0].length);
+  const endIdx = rest.indexOf(`<!-- /PRESERVE:${GOVERNANCE_PRESERVE_NAME} -->`);
+  if (endIdx === -1) return false;
+  // 块体（首尾标记之间）去空白后非空才算「在场」
+  return rest.slice(0, endIdx).trim().length > 0;
+}
+
+/** CLAUDE.md 是否存在治理块（与 agents-syncer getGovernanceInfo 同判定，旧模型仓豁免） */
+export function hasClaudeGovernance(claudeMdPath: string): boolean {
+  let content: string;
+  try {
+    content = readFileSync(claudeMdPath, 'utf-8');
+  } catch {
+    return false;
+  }
+  return /^##\s+Governance Rules/m.test(content) || content.includes('HARNESS_CONSTRAINTS_START');
+}
+
+export const governancePresence: ConstraintCheck = {
+  id: 'governance_presence',
+  async evaluate(env) {
+    const projectPath = env.projectPath;
+
+    // 存在性探测：无 harness 配置 = 未采用治理约定 → skip（不计 pass/fail）
+    let adopted = false;
+    try {
+      adopted = loadRawProjectConfig(projectPath) !== undefined;
+    } catch {
+      adopted = false;
+    }
+    if (!adopted) return 'skip';
+
+    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;
+  },
+};

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

@@ -22,6 +22,7 @@ import { capabilitySync } from './capability-sync';
 import { contextDocSync } from './context-doc-sync';
 import { docsFreshness } from './docs-freshness';
 import { noHardcodedCredentials } from './no-hardcoded-credentials';
+import { governancePresence } from './governance-presence';
 
 const CHECKS: ConstraintCheck[] = [
   // Iron Laws
@@ -35,6 +36,7 @@ const CHECKS: ConstraintCheck[] = [
   noBypassCheckpoint,
   capabilitySync,
   contextDocSync,
+  governancePresence,
 ];
 
 const registry = new Map<string, ConstraintCheck>(CHECKS.map(c => [c.id, c]));
@@ -78,4 +80,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';