@dommaker/harness 1.2.0 → 1.2.2

package/src/__tests__/iron-laws.test.ts

@@ -1,5 +1,5 @@
 /**
- * 约束系统测试（ADR-0001：kind 二元模型，25 条清单构成 + 注册表闭环）
+ * 约束系统测试（ADR-0001：kind 二元模型，26 条清单构成 + 注册表闭环）
  */
 
 import { describe, it, expect } from '@jest/globals';
@@ -16,17 +16,17 @@ import { getConstraintCheck, registeredCheckCount } from '../core/constraints/ch
 import type { ConstraintContext } from '../types/constraint';
 
 describe('Constraint System', () => {
-  describe('清单构成（ADR-0001：42 → 25）', () => {
-    it('getAllConstraints 返回 25 条：9 check + 16 prompt', () => {
+  describe('清单构成（ADR-0001：42 → 26）', () => {
+    it('getAllConstraints 返回 26 条：10 check + 16 prompt', () => {
       const all = getAllConstraints();
-      expect(all).toHaveLength(25);
-      expect(all.filter(c => c.kind === 'check')).toHaveLength(9);
+      expect(all).toHaveLength(26);
+      expect(all.filter(c => c.kind === 'check')).toHaveLength(10);
       expect(all.filter(c => c.kind === 'prompt')).toHaveLength(16);
     });
 
-    it('check 层 = 5 iron + 4 guideline', () => {
+    it('check 层 = 5 iron + 5 guideline', () => {
       expect(Object.keys(IRON_LAWS)).toHaveLength(5);
-      expect(Object.keys(GUIDELINES)).toHaveLength(4);
+      expect(Object.keys(GUIDELINES)).toHaveLength(5);
       Object.values(IRON_LAWS).forEach(c => {
         expect(c.kind).toBe('check');
         expect(c.level).toBe('iron_law');

package/src/cli/commands/CONTEXT.md

@@ -12,7 +12,7 @@ H5（#44）起：
 - 各命令文件：check / validate / passes-gate / init / report / status / spec / sync-docs / knowledge / sdd / failure / posteval-plan / release / analyze-sessions / update-user-model / constraints / doc-freshness-check / spec-baseline-check
 - 6 门禁命令实现在 `acceptance` / `command` / `contract` / `performance` / `review` / `security`（其 CLI 元数据在 `src/gates/definitions.ts`，形状同为 `CommandDefinition`，ADR-0007）
 
-`constraints` 下挂治理子命令：`constraints report`（使用统计 + 退役候选诊断 + 配置健康 + 注入漂移，`--export` 脱敏）、`constraints retire`（交互选择 + 人确认退役；带 id 直达需显式 `--yes`（#24 人确认闸门），无 `--yes` 报错 + 非零退出码且不落盘；内置落 config.yml retired 元数据，custom 落 custom-constraints.yml 条目 retired 段（#82 D6 一处真相）+ KnowledgeStore 沉淀 + CLAUDE.md 注入段同步）。
+`constraints` 下挂治理子命令：`constraints report`（使用统计 + 退役候选诊断 + 配置健康 + 注入漂移，`--export` 脱敏）、`constraints retire`（交互选择 + 人确认退役；带 id 直达需显式 `--yes`（#24 人确认闸门），无 `--yes` 报错 + 非零退出码且不落盘；内置落 config.yml retired 元数据，custom 落 custom-constraints.yml 条目 retired 段（#82 D6 一处真相）+ KnowledgeStore 沉淀 + 治理注入段同步）。
 
 ## 依赖关系
 - 依赖 `src/core/constraints/` 约束引擎
@@ -30,5 +30,8 @@ H5（#44）起：
 
 ## 注意事项
 - 新增命令需同步更新 CLAUDE.md / CAPABILITIES.md / src/CONTEXT.md
+- init 治理约束段写入落点（studio #302，ADR 2026-08-21 落点模型）：新仓 → AGENTS.md `PRESERVE:governance` 段（sync-docs 重新生成时保留）；旧模型仓（CLAUDE.md 已有 HARNESS_CONSTRAINTS 标记或 `## Governance Rules` 块）→ 续写 CLAUDE.md，幂等重跑不制造双份正本。治理段「在场守护」由 core 侧 governance_presence checker 承担（段缺失/为空时 check 报警）
+- PRESERVE:governance 段内写入纪律：机器管理的只有 HARNESS_CONSTRAINTS 标记区间——有标记只换标记区间，无标记（纯手写段）在段尾追加注入段；段内其余手写内容（治理契约引言/流程/纪律等）必须原样保留（曾整段替换清空手写内容的回归，init-injection.test 有防回归用例）
+- 注入段读取侧同一路由（studio #307）：`resolveInjectionTarget`（core/constraints/injection-drift）按「CLAUDE.md 有标记优先，否则 AGENTS.md」定位注入段，`detectInjectionDrift` 与 `constraints retire` 的注入段同步共用；未注入 = 两处均无完整标记段
 - knowledge 命令包含 13 个子操作（list/search/import/decay/stats/upsert/sync-status/sync-rag/audit/snapshot/migrate/index/health）
 - 特殊路由（选项条件、子命令兜底、退出码处理、裸跑语义）表达在定义表的 optionRoutes / subcommands / subcommandStrict / bareRunsAction / afterRun 字段，bin 是纯通用引擎、不含单命令知识

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

@@ -57,14 +57,14 @@ describe('buildConstraintsUsageReport', () => {
     const report = buildConstraintsUsageReport(root);
 
     expect(report.traceFileExists).toBe(false);
-    expect(report.stats.length).toBe(9); // 5 iron + 4 guideline
+    expect(report.stats.length).toBe(10); // 5 iron + 5 guideline
     for (const s of report.stats) {
       expect(s.total).toBe(0);
       expect(s.evaluated).toBe(0);
       expect(s.failRate).toBe(0);
       expect(s.firstAt).toBeUndefined();
     }
-    expect(report.candidates.length).toBe(9);
+    expect(report.candidates.length).toBe(10);
     expect(report.candidates.every(c => c.kind === 'zero_trigger')).toBe(true);
     // prompt 注入清单（standard preset、无 scenes → 14 条通用 prompt）
     expect(report.activePromptIds.length).toBe(14);

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__/init.test.ts

@@ -308,6 +308,49 @@ describe('init command', () => {
       expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('harness-governance.yml 已存在'));
     });
 
+    it('应该跳过治理 CI workflow 当已有 workflow 覆盖治理命令', async () => {
+      mockFs.mkdir.mockResolvedValue(undefined);
+      mockFs.writeFile.mockResolvedValue(undefined);
+      // setupGitHubActions 与治理能力检测都会 readdir workflows 目录
+      existingFiles.add(`${PROJECT}/.github/workflows`);
+      mockReaddir.mockResolvedValue(['ci.yml']);
+      mockFs.readFile.mockImplementation((p: any) =>
+        String(p).includes('ci.yml')
+          ? Promise.resolve('run: npx harness sync-docs --agents && npx harness check && npx harness sync-docs --check --agents')
+          : Promise.reject(new Error('ENOENT'))
+      );
+
+      await init({ preset: 'standard', governance: 'standard', projectPath: PROJECT });
+      const writeCalls = mockFs.writeFile.mock.calls;
+      const workflowCall = writeCalls.find((c: any[]) => String(c[0]).includes('harness-governance.yml'));
+      expect(workflowCall).toBeUndefined();
+      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('治理检查已由 ci.yml 覆盖'));
+
+      mockReaddir.mockResolvedValue([]);
+      mockFs.readFile.mockRejectedValue(new Error('ENOENT'));
+    });
+
+    it('应该正常创建治理 CI workflow 当已有 workflow 不含治理命令', async () => {
+      mockFs.mkdir.mockResolvedValue(undefined);
+      mockFs.writeFile.mockResolvedValue(undefined);
+      existingFiles.add(`${PROJECT}/.github/workflows`);
+      mockReaddir.mockResolvedValue(['ci.yml']);
+      mockFs.readFile.mockImplementation((p: any) =>
+        String(p).includes('ci.yml')
+          ? Promise.resolve('run: npm test')
+          : Promise.reject(new Error('ENOENT'))
+      );
+
+      await init({ preset: 'standard', governance: 'standard', projectPath: PROJECT });
+      const writeCalls = mockFs.writeFile.mock.calls;
+      const workflowCall = writeCalls.find((c: any[]) => String(c[0]).includes('harness-governance.yml'));
+      expect(workflowCall).toBeDefined();
+      expect(workflowCall![1]).toContain('Harness Governance');
+
+      mockReaddir.mockResolvedValue([]);
+      mockFs.readFile.mockRejectedValue(new Error('ENOENT'));
+    });
+
     it('strict 治理应在 CI 中包含 docs check', async () => {
       mockFs.mkdir.mockResolvedValue(undefined);
       mockFs.writeFile.mockResolvedValue(undefined);

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('已取消');