@dommaker/harness 1.2.0 → 1.2.2

package/src/cli/commands/init.ts

@@ -569,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 过滤全部反映在注入文本里
@@ -632,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);
+}
+
 /**
  * 设置治理相关文件
  */
@@ -648,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;
@@ -768,6 +888,26 @@ async function createContextMd(projectPath: string, dir: string): Promise<void>
   console.log(chalk.green(`✅ 已创建 ${dir}/CONTEXT.md`));
 }
 
+/**
+ * 检测已有 workflow 是否已覆盖 harness 治理命令
+ * （harness check / passes-gate / sync-docs --check，含 npx、scoped 包名等调用形式）
+ */
+const GOVERNANCE_COMMAND_PATTERN = /\bharness\s+(?:check\b|passes-gate\b|sync-docs\b[^\n]*--check)/;
+
+async function findGovernanceCoverage(workflowsDir: string): Promise<string | undefined> {
+  for (const file of await findCiWorkflows(workflowsDir)) {
+    try {
+      const content = await fs.readFile(path.join(workflowsDir, file), 'utf-8');
+      if (GOVERNANCE_COMMAND_PATTERN.test(content)) {
+        return file;
+      }
+    } catch {
+      // 读取失败，忽略该文件
+    }
+  }
+  return undefined;
+}
+
 /**
  * 设置治理 CI workflow
  */
@@ -784,6 +924,13 @@ async function setupGovernanceWorkflow(projectPath: string, level: string): Prom
     // 不存在，继续创建
   }
 
+  // 能力检测：已有 workflow 已跑 harness 治理命令时跳过，避免重复 CI 面
+  const coveredBy = await findGovernanceCoverage(workflowsDir);
+  if (coveredBy) {
+    console.log(chalk.gray(`治理检查已由 ${coveredBy} 覆盖，跳过创建 harness-governance.yml`));
+    return;
+  }
+
   await fs.mkdir(workflowsDir, { recursive: true });
 
   const docsCheckStep = level !== 'minimal'

package/src/core/CONTEXT.md

@@ -4,7 +4,7 @@
 约束引擎核心：check/prompt 二元约束系统（ADR-0001）、生效集合并（effective-constraints）、检查点验证器(CSO/passes-gate)、会话管理、Spec 验证器、项目配置加载。
 
 ## 核心导出
-- `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)/使用统计(usage-report)；CheckEnv 生产侧唯一构造点 `buildCheckEnv(context, providers|'none')`（checkers/types.ts：providers = 证据接线，'none' = 显式不接 → evidence flag checker 按契约 skip）
+- `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 验证器

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/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]));

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

@@ -97,4 +97,26 @@ export const GUIDELINES: Record<string, Constraint> = {
 - 测试目录（__tests__、test）
 - 生成代码目录（dist、build、generated）`,
   },
+
+  /**
+   * 治理契约在场守护（studio #302，ADR 2026-08-21 落点模型）
+   * 原因：PRESERVE 只保「存在」不保「在场」——AGENTS.md 治理段被删除/掏空后
+   *       sync-docs 重新生成会静默丢失约束正本
+   */
+  governance_presence: {
+    id: 'governance_presence',
+    kind: 'check',
+    rule: 'GOVERNANCE CONTRACT MUST BE PRESENT (AGENTS.MD PRESERVE:GOVERNANCE BLOCK OR CLAUDE.MD GOVERNANCE RULES)',
+    message: '治理契约缺失：AGENTS.md 缺少非空 PRESERVE:governance 段，且 CLAUDE.md 无 Governance Rules 块',
+    level: 'guideline',
+    trigger: ['file_modification', 'module_creation', 'module_modification', 'doc_update', 'config_change', 'commit'],
+    enforcement: 'governance-presence-check',
+    description: `治理契约（约束清单正本）必须在场，两处居其一：
+- 新模型：AGENTS.md 手写 \`<!-- PRESERVE:governance -->\` 段（块体非空）
+- 旧模型：CLAUDE.md 的 \`## Governance Rules\` 块 / HARNESS_CONSTRAINTS 注入段
+
+PRESERVE 机制只保证「存在的段重新生成时保留」，不保证「段在场」——段被删除或掏空后，
+sync-docs 重新生成会静默丢弃治理契约。本检查在 harness check 时校验在场性，防静默丢失。
+未采用 harness 治理（无 .harness/config.yml）的项目跳过评估（skip）。`,
+  },
 };

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

@@ -1,5 +1,5 @@
 /**
- * CLAUDE.md 约束注入段漂移校验（ADR-0001 决策 7）
+ * 治理约束注入段漂移校验（ADR-0001 决策 7）
  *
  * 检测三类漂移：
  * 1. 版本漂移：标记段内 `<!-- version: x -->` ≠ 当前 harness 包版本
@@ -9,8 +9,12 @@
  * 3. 重复章节：标记段之外还存在另一个 `## Governance Rules` 标题
  *    （init 旧版本在无标记时追加第二个同名章节的历史问题）
  *
+ * 落点路由（studio #307，ADR 2026-08-21 落点模型）：注入段可能在
+ * CLAUDE.md（旧模型仓）或 AGENTS.md `PRESERVE:governance` 段内（新模型仓），
+ * 与 init 的 setupGovernanceConstraints 路由一致——CLAUDE.md 有标记优先。
+ *
  * 纯检测、只读：不改任何文件。check 仅警告不阻断，详细差异进 report。
- * 文件无标记段 = 未注入，不算漂移（report 一句话提示，check 不警告）。
+ * 两处均无标记段 = 未注入，不算漂移（report 一句话提示，check 不警告）。
  */
 
 import * as fs from 'fs';
@@ -22,12 +26,18 @@ import {
   renderConstraintsSection,
 } from './injection-renderer';
 
+/** 注入段落点文件名（检测顺序即路由优先级：旧模型仓 CLAUDE.md 豁免优先） */
+const INJECTION_FILES = ['CLAUDE.md', 'AGENTS.md'] as const;
+export type InjectionFile = (typeof INJECTION_FILES)[number];
+
 /** 注入漂移检测结果 */
 export interface InjectionDrift {
   /** 是否存在任一漂移（版本/内容/重复章节） */
   hasDrift: boolean;
-  /** CLAUDE.md 不存在或无约束标记段（未注入，不算漂移） */
+  /** CLAUDE.md / AGENTS.md 均无约束标记段（未注入，不算漂移） */
   notInjected: boolean;
+  /** 注入段落点文件（未注入时 undefined） */
+  injectionFile?: InjectionFile;
   /** 版本漂移：注入段版本 ≠ 当前 harness 版本 */
   versionDrift?: { expected: string; actual: string };
   /**
@@ -73,8 +83,41 @@ function significantLines(section: string): string[] {
     .filter(l => ENTRY_LINE_RE.test(l) || GROUP_HEADING_RE.test(l));
 }
 
+function readIfExists(filePath: string): string | null {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return typeof content === 'string' ? content : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 解析治理约束注入段落点（studio #307，ADR 2026-08-21 落点模型）
+ *
+ * 与 init 的 setupGovernanceConstraints 路由一致：CLAUDE.md 含标记段优先
+ * （旧模型仓豁免），否则看 AGENTS.md（新模型仓注入段在 PRESERVE:governance 内）；
+ * 两处均无完整标记段 → null（未注入）。
+ *
+ * detectInjectionDrift 与 constraints retire 的注入段同步共用本路由。
+ */
+export function resolveInjectionTarget(
+  projectRoot: string
+): { file: InjectionFile; content: string; startIdx: number; endIdx: number } | null {
+  for (const file of INJECTION_FILES) {
+    const content = readIfExists(path.join(projectRoot, file));
+    if (content === null) continue;
+    const startIdx = content.indexOf(CONSTRAINTS_START_MARKER);
+    const endIdx = content.indexOf(CONSTRAINTS_END_MARKER);
+    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+      return { file, content, startIdx, endIdx };
+    }
+  }
+  return null;
+}
+
 /**
- * 检测 CLAUDE.md 约束注入段漂移
+ * 检测约束注入段漂移
  *
  * @param projectRoot 项目根路径
  * @param currentVersion 当前 harness 版本（缺省读 package.json；测试可显式传入）
@@ -90,31 +133,27 @@ export function detectInjectionDrift(
     fixHint: INJECTION_DRIFT_FIX_HINT,
   };
 
-  const claudeMdPath = path.join(projectRoot, 'CLAUDE.md');
-  let content: string;
-  try {
-    content = fs.readFileSync(claudeMdPath, 'utf-8');
-  } catch {
-    result.notInjected = true;
-    return result;
-  }
-  if (typeof content !== 'string') {
+  const target = resolveInjectionTarget(projectRoot);
+  if (!target) {
+    // 两处均无标记段 = 未注入，不算漂移（check 不警告）。
+    // 重复章节仍如实记录供 report 提示：旧落点 CLAUDE.md 优先，其次 AGENTS.md。
+    const legacy =
+      readIfExists(path.join(projectRoot, 'CLAUDE.md')) ??
+      readIfExists(path.join(projectRoot, 'AGENTS.md'));
+    if (legacy !== null) {
+      result.duplicateHeading = (legacy.match(GOVERNANCE_HEADING_RE) ?? []).length > 1;
+    }
     result.notInjected = true;
     return result;
   }
 
+  result.injectionFile = target.file;
+  const { content, startIdx, endIdx } = target;
+
   // 重复章节：全文统计 `## Governance Rules` 标题数（含标记段所属的合法标题）
   const headingCount = (content.match(GOVERNANCE_HEADING_RE) ?? []).length;
   result.duplicateHeading = headingCount > 1;
 
-  const startIdx = content.indexOf(CONSTRAINTS_START_MARKER);
-  const endIdx = content.indexOf(CONSTRAINTS_END_MARKER);
-  if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) {
-    // 无标记段 = 未注入，不算漂移（check 不警告；duplicateHeading 仍如实记录供 report 提示）
-    result.notInjected = true;
-    return result;
-  }
-
   const actualSection = content.slice(startIdx, endIdx + CONSTRAINTS_END_MARKER.length);
 
   // 1. 版本漂移