@dommaker/harness 1.2.0 → 1.2.1

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

@@ -2,7 +2,7 @@
  * harness constraints retire 测试（ADR-0001 P5）
  *
  * 执行逻辑（retireConstraint，纯函数化）：config.yml 写入形态、
- * KnowledgeStore 记录、CLAUDE.md 注入段同步、重复 retire / 未知 id 保护。
+ * KnowledgeStore 记录、治理注入段同步（CLAUDE.md / AGENTS.md 落点路由）、重复 retire / 未知 id 保护。
  * 交互流程（runRetireInteractive）：注入 stdin 流测核心分支
  * （候选选择 + iron 二次确认拒绝；无候选手动输入 + 确认执行）。
  *
@@ -145,7 +145,7 @@ describe('retireConstraint 执行逻辑', () => {
 
     const result = retireConstraint(root, 'no_bypass_checkpoint', { now: FIXED_NOW });
     expect(result.status).toBe('retired');
-    expect(result.claudeMdSynced).toBe(true);
+    expect(result.injectionSynced).toBe(true);
 
     const after = fs.readFileSync(path.join(root, 'CLAUDE.md'), 'utf-8');
     expect(after).toContain('HARNESS_CONSTRAINTS_START');
@@ -164,10 +164,51 @@ describe('retireConstraint 执行逻辑', () => {
     fs.writeFileSync(path.join(root, 'CLAUDE.md'), '# 用户自写\n', 'utf-8');
     const result = retireConstraint(root, 'capability_sync', { now: FIXED_NOW });
     expect(result.status).toBe('retired');
-    expect(result.claudeMdSynced).toBe(false);
+    expect(result.injectionSynced).toBe(false);
     expect(fs.readFileSync(path.join(root, 'CLAUDE.md'), 'utf-8')).toBe('# 用户自写\n');
   });
 
+  it('新模型仓：AGENTS.md PRESERVE:governance 内含标记段时同步重渲染（无 CLAUDE.md）', () => {
+    const root = makeTmpProject();
+    const before = renderConstraintsSection(getEffectiveConstraints(root), '0.0.0-test');
+    expect(before).toContain('no_bypass_checkpoint');
+    fs.writeFileSync(
+      path.join(root, 'AGENTS.md'),
+      `# AGENTS.md\n\n<!-- PRESERVE:governance -->\n## Governance Rules\n${before}<!-- /PRESERVE:governance -->\n\n其他内容\n`,
+      'utf-8'
+    );
+
+    const result = retireConstraint(root, 'no_bypass_checkpoint', { now: FIXED_NOW });
+    expect(result.status).toBe('retired');
+    expect(result.injectionSynced).toBe(true);
+    expect(result.injectionFile).toBe('AGENTS.md');
+
+    const after = fs.readFileSync(path.join(root, 'AGENTS.md'), 'utf-8');
+    expect(after).toContain('HARNESS_CONSTRAINTS_START');
+    expect(after).toContain('HARNESS_CONSTRAINTS_END');
+    expect(after).not.toContain('**no_bypass_checkpoint**');
+    expect(after).toContain('PRESERVE:governance');
+    expect(after).toContain('其他内容');
+    // 不制造 CLAUDE.md
+    expect(fs.existsSync(path.join(root, 'CLAUDE.md'))).toBe(false);
+  });
+
+  it('两文件均有标记段时旧模型仓豁免：只同步 CLAUDE.md，AGENTS.md 不动', () => {
+    const root = makeTmpProject();
+    const before = renderConstraintsSection(getEffectiveConstraints(root), '0.0.0-test');
+    fs.writeFileSync(path.join(root, 'CLAUDE.md'), `# 项目\n\n## Governance Rules\n${before}`, 'utf-8');
+    const agentsMd = `# AGENTS.md\n\n<!-- PRESERVE:governance -->\n## Governance Rules\n${before}<!-- /PRESERVE:governance -->\n`;
+    fs.writeFileSync(path.join(root, 'AGENTS.md'), agentsMd, 'utf-8');
+
+    const result = retireConstraint(root, 'no_bypass_checkpoint', { now: FIXED_NOW });
+    expect(result.status).toBe('retired');
+    expect(result.injectionSynced).toBe(true);
+    expect(result.injectionFile).toBe('CLAUDE.md');
+
+    expect(fs.readFileSync(path.join(root, 'CLAUDE.md'), 'utf-8')).not.toContain('**no_bypass_checkpoint**');
+    expect(fs.readFileSync(path.join(root, 'AGENTS.md'), 'utf-8')).toBe(agentsMd);
+  });
+
   it('重复 retire：already_retired，不覆盖原 retired 元数据', () => {
     const root = makeTmpProject();
     const first = retireConstraint(root, 'capability_sync', { reason: '第一次', now: FIXED_NOW });
@@ -214,7 +255,7 @@ describe('retireConstraint 执行逻辑', () => {
 
     expect(result.status).toBe('retired');
     expect(result.landing).toBe('custom-constraints.yml');
-    expect(result.claudeMdSynced).toBe(true);
+    expect(result.injectionSynced).toBe(true);
     // config.yml 不产生该 id 段
     expect(fs.existsSync(path.join(root, '.harness', 'config.yml'))).toBe(false);
     // yml 保留规则原文 + retired 元数据

package/src/cli/commands/__tests__/init-injection.test.ts

@@ -17,6 +17,8 @@ import {
 import {
   setupClaudeMdConstraints,
   setupClaudeMdOutputStyle,
+  setupAgentsMdConstraints,
+  setupGovernanceConstraints,
 } from '../init';
 import { getEffectiveConstraints } from '../../../core/effective-constraints';
 import { getAllConstraints } from '../../../core/constraints/definitions';
@@ -232,3 +234,203 @@ describe('setupClaudeMdOutputStyle（标记化）', () => {
     expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('跳过'));
   });
 });
+
+const GOVERNANCE_PRESERVE_BEGIN = '<!-- PRESERVE:governance -->';
+const GOVERNANCE_PRESERVE_END = '<!-- /PRESERVE:governance -->';
+
+describe('setupAgentsMdConstraints（新落点模型：治理契约 → AGENTS.md PRESERVE:governance 段）', () => {
+  let tempDir: string;
+  let agentsMdPath: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(process.cwd(), 'temp-test-init-agents-'));
+    agentsMdPath = path.join(tempDir, 'AGENTS.md');
+    jest.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('AGENTS.md 不存在时创建骨架并写入 PRESERVE:governance 段', async () => {
+    await setupAgentsMdConstraints(tempDir);
+
+    const content = fs.readFileSync(agentsMdPath, 'utf-8');
+    expect(content).toContain('# AGENTS.md');
+    expect(content).toContain(GOVERNANCE_PRESERVE_BEGIN);
+    expect(content).toContain(GOVERNANCE_PRESERVE_END);
+    expect(content).toContain('## Governance Rules');
+    expect(content).toContain(CONSTRAINTS_START_MARKER);
+    expect(content).toContain(CONSTRAINTS_END_MARKER);
+    expect(content).toContain('### Iron Laws');
+    // PRESERVE 标记在约束段之外（sync-docs 重新生成时整段保留）
+    expect(content.indexOf(GOVERNANCE_PRESERVE_BEGIN)).toBeLessThan(content.indexOf(CONSTRAINTS_START_MARKER));
+    expect(content.indexOf(CONSTRAINTS_END_MARKER)).toBeLessThan(content.indexOf(GOVERNANCE_PRESERVE_END));
+  });
+
+  it('连跑两次输出一致（幂等）', async () => {
+    await setupAgentsMdConstraints(tempDir);
+    const first = fs.readFileSync(agentsMdPath, 'utf-8');
+    await setupAgentsMdConstraints(tempDir);
+    expect(fs.readFileSync(agentsMdPath, 'utf-8')).toBe(first);
+  });
+
+  it('已有 PRESERVE:governance 段（含标记+段内手写内容）：只换标记区间，手写内容原样保留', async () => {
+    // 回归：曾把 PRESERVE 段内 HARNESS 标记之外的手写内容（治理契约引言/流程等）清空
+    fs.writeFileSync(agentsMdPath, [
+      '# AGENTS.md',
+      '',
+      '机器生成导读（保持不变）',
+      '',
+      GOVERNANCE_PRESERVE_BEGIN,
+      '## Governance Rules',
+      CONSTRAINTS_START_MARKER,
+      '<!-- version: 0.0.0 -->',
+      '过期的旧约束内容',
+      CONSTRAINTS_END_MARKER,
+      '',
+      '治理契约引言（手写，保留）',
+      '',
+      '### 治理变更流程（手写，保留）',
+      GOVERNANCE_PRESERVE_END,
+      '',
+      '<!-- PRESERVE:other -->',
+      '另一个手写段（保持不动）',
+      '<!-- /PRESERVE:other -->',
+      '',
+    ].join('\n'));
+
+    await setupAgentsMdConstraints(tempDir);
+
+    const content = fs.readFileSync(agentsMdPath, 'utf-8');
+    expect(content).toContain('机器生成导读（保持不变）');
+    expect(content).toContain('另一个手写段（保持不动）');
+    expect(content).not.toContain('过期的旧约束内容');
+    expect(content).toContain(CONSTRAINTS_START_MARKER);
+    // 段内标记之外的手写内容原样保留
+    expect(content).toContain('治理契约引言（手写，保留）');
+    expect(content).toContain('### 治理变更流程（手写，保留）');
+    expect(content.indexOf(CONSTRAINTS_END_MARKER)).toBeLessThan(content.indexOf('治理契约引言（手写，保留）'));
+    expect(content.indexOf('### 治理变更流程（手写，保留）')).toBeLessThan(content.indexOf(GOVERNANCE_PRESERVE_END));
+    // 幂等
+    await setupAgentsMdConstraints(tempDir);
+    expect(fs.readFileSync(agentsMdPath, 'utf-8')).toBe(content);
+  });
+
+  it('已有 PRESERVE:governance 段但无 HARNESS 标记（纯手写段）：段尾追加注入段，手写内容不动', async () => {
+    fs.writeFileSync(agentsMdPath, [
+      '# AGENTS.md',
+      '',
+      GOVERNANCE_PRESERVE_BEGIN,
+      '治理契约引言（手写，保留）',
+      '',
+      '### 发布纪律（手写，保留）',
+      GOVERNANCE_PRESERVE_END,
+      '',
+    ].join('\n'));
+
+    await setupAgentsMdConstraints(tempDir);
+
+    const content = fs.readFileSync(agentsMdPath, 'utf-8');
+    expect(content).toContain('治理契约引言（手写，保留）');
+    expect(content).toContain('### 发布纪律（手写，保留）');
+    expect(content).toContain(CONSTRAINTS_START_MARKER);
+    // 注入段追加在手写内容之后、PRESERVE 段内
+    expect(content.indexOf('### 发布纪律（手写，保留）')).toBeLessThan(content.indexOf(CONSTRAINTS_START_MARKER));
+    expect(content.indexOf(CONSTRAINTS_END_MARKER)).toBeLessThan(content.indexOf(GOVERNANCE_PRESERVE_END));
+    // 幂等
+    await setupAgentsMdConstraints(tempDir);
+    expect(fs.readFileSync(agentsMdPath, 'utf-8')).toBe(content);
+  });
+
+  it('AGENTS.md 存在但无 PRESERVE:governance 段：末尾追加，既有内容不动', async () => {
+    fs.writeFileSync(agentsMdPath, '# AGENTS.md\n\n既有导读内容\n');
+
+    await setupAgentsMdConstraints(tempDir);
+
+    const content = fs.readFileSync(agentsMdPath, 'utf-8');
+    expect(content).toContain('既有导读内容');
+    expect(content).toContain(GOVERNANCE_PRESERVE_BEGIN);
+    expect(content.indexOf('既有导读内容')).toBeLessThan(content.indexOf(GOVERNANCE_PRESERVE_BEGIN));
+  });
+
+  it('PRESERVE:governance 标记残缺（只有单边）：不写入并告警', async () => {
+    const original = `# AGENTS.md\n\n${GOVERNANCE_PRESERVE_BEGIN}\n残缺的段\n`;
+    fs.writeFileSync(agentsMdPath, original);
+    const logSpy = jest.spyOn(console, 'log');
+
+    await setupAgentsMdConstraints(tempDir);
+
+    expect(fs.readFileSync(agentsMdPath, 'utf-8')).toBe(original);
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('残缺'));
+  });
+
+  it('段内注入文本与 renderConstraintsSection(getEffectiveConstraints()) 一致', async () => {
+    await setupAgentsMdConstraints(tempDir);
+
+    const content = fs.readFileSync(agentsMdPath, 'utf-8');
+    const start = content.indexOf(CONSTRAINTS_START_MARKER);
+    const end = content.indexOf(CONSTRAINTS_END_MARKER) + CONSTRAINTS_END_MARKER.length + 1;
+    const actual = content.slice(start, end);
+    const version = /<!-- version: ([^ ]+) -->/.exec(content)![1];
+    expect(actual).toBe(renderConstraintsSection(getEffectiveConstraints(tempDir), version));
+  });
+});
+
+describe('setupGovernanceConstraints（落点路由）', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(process.cwd(), 'temp-test-init-routing-'));
+    jest.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('新仓（无 CLAUDE.md）：治理契约写向 AGENTS.md，不创建 CLAUDE.md', async () => {
+    await setupGovernanceConstraints(tempDir);
+
+    expect(fs.existsSync(path.join(tempDir, 'AGENTS.md'))).toBe(true);
+    expect(fs.existsSync(path.join(tempDir, 'CLAUDE.md'))).toBe(false);
+    const content = fs.readFileSync(path.join(tempDir, 'AGENTS.md'), 'utf-8');
+    expect(content).toContain(GOVERNANCE_PRESERVE_BEGIN);
+    expect(content).toContain(CONSTRAINTS_START_MARKER);
+  });
+
+  it('旧模型仓（CLAUDE.md 已有 HARNESS_CONSTRAINTS 标记）：继续写 CLAUDE.md，不动 AGENTS.md', async () => {
+    fs.writeFileSync(path.join(tempDir, 'CLAUDE.md'), [
+      '# CLAUDE.md',
+      '',
+      '## Governance Rules',
+      CONSTRAINTS_START_MARKER,
+      '<!-- version: 0.0.0 -->',
+      '旧约束',
+      CONSTRAINTS_END_MARKER,
+      '',
+    ].join('\n'));
+    fs.writeFileSync(path.join(tempDir, 'AGENTS.md'), '# AGENTS.md\n\n既有导读\n');
+
+    await setupGovernanceConstraints(tempDir);
+
+    const claude = fs.readFileSync(path.join(tempDir, 'CLAUDE.md'), 'utf-8');
+    expect(claude).not.toContain('旧约束');
+    expect(claude).toContain('### Iron Laws');
+    // AGENTS.md 不被写入治理段
+    expect(fs.readFileSync(path.join(tempDir, 'AGENTS.md'), 'utf-8')).toBe('# AGENTS.md\n\n既有导读\n');
+  });
+
+  it('旧模型仓（CLAUDE.md 有无标记 Governance Rules 块）：路由到 CLAUDE.md', async () => {
+    fs.writeFileSync(path.join(tempDir, 'CLAUDE.md'), '# CLAUDE.md\n\n## Governance Rules\n\n手写条款\n');
+
+    await setupGovernanceConstraints(tempDir);
+
+    const claude = fs.readFileSync(path.join(tempDir, 'CLAUDE.md'), 'utf-8');
+    expect(claude).toContain('手写条款');
+    expect(claude).toContain(CONSTRAINTS_START_MARKER);
+    expect(fs.existsSync(path.join(tempDir, 'AGENTS.md'))).toBe(false);
+  });
+});

package/src/cli/commands/__tests__/sync-docs-agents.test.ts

@@ -592,5 +592,33 @@ describe('sync-docs --agents', () => {
 
       fs.rmSync(testDir, { recursive: true, force: true });
     });
+
+    it('PRESERVE:governance 治理契约段开箱即用：重新生成保留、--check 通过（studio #302）', async () => {
+      const testDir = path.join(tempDir, 'preserve-governance');
+      createFixture(testDir, { pnpm: true, withCapabilities: true });
+
+      const GOVERNANCE_BLOCK = [
+        '<!-- PRESERVE:governance -->',
+        '## Governance Rules',
+        '',
+        '<!-- HARNESS_CONSTRAINTS_START -->',
+        '- **law_a**: 治理契约条款',
+        '<!-- HARNESS_CONSTRAINTS_END -->',
+        '<!-- /PRESERVE:governance -->',
+      ].join('\n');
+
+      await syncDocs({ projectPath: testDir, agents: true });
+      appendBlock(testDir, GOVERNANCE_BLOCK);
+      await syncDocs({ projectPath: testDir, agents: true });
+
+      const content = fs.readFileSync(path.join(testDir, 'AGENTS.md'), 'utf-8');
+      expect(content).toContain(GOVERNANCE_BLOCK);
+
+      // 幂等 + --check 通过（块内含 HARNESS_CONSTRAINTS 标记不影响漂移比对）
+      expect(await syncDocs({ projectPath: testDir, agents: true })).toBe(true);
+      expect(await syncDocs({ projectPath: testDir, agents: true, check: true })).toBe(true);
+
+      fs.rmSync(testDir, { recursive: true, force: true });
+    });
   });
 });

package/src/cli/commands/check.ts

@@ -123,7 +123,7 @@ export async function check(options: CheckOptions): Promise<void> {
       const drift = detectInjectionDrift(projectPath);
       if (drift.hasDrift) {
         console.log();
-        console.log(chalk.yellow('⚠️  检测到 CLAUDE.md 约束注入漂移（仅警告，不阻断）:'));
+        console.log(chalk.yellow(`⚠️  检测到 ${drift.injectionFile ?? '治理文档'} 约束注入漂移（仅警告，不阻断）:`));
         if (drift.versionDrift) {
           console.log(chalk.yellow(`   ⚠️⚠️ 注入段版本 (${drift.versionDrift.actual}) ≠ 已安装 harness 版本 (${drift.versionDrift.expected})：agent 上下文中的规则与已安装 harness 版本不一致`));
         }

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

@@ -118,7 +118,7 @@ export function renderExportMarkdown(
 export function renderInjectionDriftLines(drift: InjectionDrift): string[] {
   const lines: string[] = [];
   if (drift.notInjected) {
-    lines.push('  CLAUDE.md 无约束注入标记段（未注入，不算漂移）；可运行 npx @dommaker/harness init 注入');
+    lines.push('  CLAUDE.md / AGENTS.md 均无约束注入标记段（未注入，不算漂移）；可运行 npx @dommaker/harness init 注入');
     if (drift.duplicateHeading) {
       lines.push('  另检测到多个 "## Governance Rules" 标题（历史遗留重复章节），建议手工清理后重跑 npx @dommaker/harness init');
     }

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

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 验证器