@dommaker/harness 1.1.1 → 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__/knowledge.test.ts

@@ -2,7 +2,7 @@
  * knowledge 命令测试 — knowledgeAudit
  */
 
-import { knowledgeAudit, knowledgeStats, knowledgeHealth } from '../knowledge';
+import { knowledgeAudit, knowledgeStats, knowledgeHealth, knowledgeSearch } from '../knowledge';
 
 // Mock chalk
 jest.mock('chalk', () => ({
@@ -233,3 +233,92 @@ describe('knowledgeHealth CLI', () => {
     expect(parsed.summary.staleEntries).toBe(1);
   });
 });
+
+/**
+ * knowledgeSearch 回归测试 — harness#63
+ * bug：先按 token budget 截断再文本匹配，新条目（lastReferenced 为空、排序队尾）
+ * 在语料超过 budget 时永远进不了匹配阶段。
+ */
+describe('knowledgeSearch CLI (harness#63)', () => {
+  const fs = require('fs');
+  const os = require('os');
+  const path = require('path');
+  const { FileKnowledgeStore } = require('../../../knowledge/store');
+
+  let tmpProject: string;
+  let knowledgeDir: string;
+  let consoleSpy: jest.SpyInstance;
+
+  const FILLER_COUNT = 25; // 25 × ~800 tokens ≈ 20000 > maxTokens 10000
+  const TARGET_ID = 'PIT-020';
+
+  function makeEntry(overrides: Record<string, any>): any {
+    return {
+      id: 'X-000',
+      type: 'pitfall',
+      title: '条目',
+      content: '内容',
+      maturity: 'proven',
+      layer: 'project',
+      created: '2026-08-01T00:00:00.000Z',
+      lastReferenced: '2026-08-01T00:00:00.000Z',
+      contributors: [],
+      projects: [],
+      tags: [],
+      applicablePhases: [],
+      sourceReferences: [],
+      referencedBy: [],
+      executionResults: [],
+      consumptionMode: 'reference',
+      origin: 'agent',
+      ...overrides,
+    };
+  }
+
+  beforeEach(() => {
+    tmpProject = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-k63-'));
+    knowledgeDir = path.join(tmpProject, '.harness', 'knowledge');
+    fs.mkdirSync(knowledgeDir, { recursive: true });
+    consoleSpy = jest.spyOn(console, 'log').mockImplementation();
+
+    const store = new FileKnowledgeStore({ baseDir: knowledgeDir });
+    // 高成熟度 + 有 lastReferenced 的填充条目排在前面，吃满 token budget
+    for (let i = 0; i < FILLER_COUNT; i++) {
+      store.save(makeEntry({
+        id: `FILL-${String(i).padStart(3, '0')}`,
+        title: `填充条目 ${i}`,
+        content: '填'.repeat(399) + '共同词',
+      }));
+    }
+    // 目标条目：新条目，draft + lastReferenced 为空，排在队尾
+    store.save(makeEntry({
+      id: TARGET_ID,
+      title: '新条目',
+      maturity: 'draft',
+      lastReferenced: '',
+      content: 'autolink 相关条目 共同词',
+    }));
+  });
+
+  afterEach(() => {
+    consoleSpy.mockRestore();
+    fs.rmSync(tmpProject, { recursive: true, force: true });
+  });
+
+  async function searchJson(query: string, limit: number): Promise<any> {
+    await knowledgeSearch(query, { projectPath: tmpProject, json: true, limit });
+    const output = consoleSpy.mock.calls.map((c: any[]) => c[0]).join('\n');
+    return JSON.parse(output);
+  }
+
+  it('语料超过 token budget 时，排在队尾的新条目仍可被搜到', async () => {
+    const result = await searchJson('autolink', 200);
+    expect(result.total).toBe(1);
+    expect(result.entries[0].id).toBe(TARGET_ID);
+  });
+
+  it('超高频关键词的返回数 = 实际匹配数（截断只发生在匹配之后）', async () => {
+    const result = await searchJson('共同词', 200);
+    expect(result.total).toBe(FILLER_COUNT + 1);
+  });
+});

package/src/cli/commands/__tests__/registry.test.ts

@@ -51,11 +51,10 @@ describe('命令注册表闭环', () => {
   });
 
   it('全部实现引用可解析（module 存在且 export 是函数）', () => {
-    const refs = collectRefs(COMMAND_DEFINITIONS);
-    for (const def of GATE_DEFINITIONS) {
-      refs.push(def.cli.action);
-      for (const entry of Object.values(def.cli.subcommands || {})) refs.push(entry);
-    }
+    const refs = collectRefs([
+      ...COMMAND_DEFINITIONS,
+      ...GATE_DEFINITIONS.map(d => d.cli),
+    ]);
     expect(refs.length).toBeGreaterThan(0);
 
     for (const ref of refs) {
@@ -107,7 +106,10 @@ describe('命令注册表闭环', () => {
         }
         for (const child of def.children || []) walk(child);
       };
-      for (const def of COMMAND_DEFINITIONS) walk(def);
+      for (const def of [
+        ...COMMAND_DEFINITIONS,
+        ...GATE_DEFINITIONS.map(d => d.cli),
+      ]) walk(def);
       // sync-docs --check 失败路径确实会请求退出
       expect(exitSpy).toHaveBeenCalled();
     } finally {

package/src/cli/commands/__tests__/status-extra.test.ts

@@ -81,7 +81,7 @@ describe('status command - 补充覆盖', () => {
       ];
       const mockAnalyze = {
         summarize: jest.fn().mockReturnValue([
-          { constraintId: 'no_bypass_checkpoint', level: 'iron_law', passRate: 0.2, totalChecks: 10, bypassRate: 0.1 },
+          { constraintId: 'no_bypass_checkpoint', level: 'iron_law', passRate: 0.2, failRate: 0.8, totalChecks: 10 },
         ]),
         detectAnomalies: jest.fn().mockReturnValue(mockAnomalies),
       };
@@ -119,8 +119,8 @@ describe('status command - 补充覆盖', () => {
       mockFs.readFileSync.mockReturnValue(mockTraces.map(t => JSON.stringify(t)).join('\n'));
 
       const mockSummaries = [
-        { constraintId: 'no_bypass_checkpoint', level: 'iron_law', passRate: 1, totalChecks: 10, bypassRate: 0 },
-        { constraintId: 'no_completion_without_verification', level: 'iron_law', passRate: 0.8, totalChecks: 5, bypassRate: 0 },
+        { constraintId: 'no_bypass_checkpoint', level: 'iron_law', passRate: 1, failRate: 0, totalChecks: 10 },
+        { constraintId: 'no_completion_without_verification', level: 'iron_law', passRate: 0.8, failRate: 0.2, totalChecks: 5 },
       ];
       const mockAnalyze = {
         summarize: jest.fn().mockReturnValue(mockSummaries),
@@ -141,7 +141,7 @@ describe('status command - 补充覆盖', () => {
       mockFs.readFileSync.mockReturnValue(mockTraces.map(t => JSON.stringify(t)).join('\n'));
 
       const mockSummaries = [
-        { constraintId: 'capability_sync', level: 'guideline', passRate: 0.9, totalChecks: 20, bypassRate: 0.1 },
+        { constraintId: 'capability_sync', level: 'guideline', passRate: 0.9, failRate: 0.1, totalChecks: 20 },
       ];
       const mockAnalyze = {
         summarize: jest.fn().mockReturnValue(mockSummaries),
@@ -164,8 +164,8 @@ describe('status command - 补充覆盖', () => {
       mockFs.readFileSync.mockReturnValue(mockTraces.map(t => JSON.stringify(t)).join('\n'));
 
       const mockSummaries = [
-        { constraintId: 'no_bypass_checkpoint', level: 'iron_law', passRate: 1, totalChecks: 10, bypassRate: 0 },
-        { constraintId: 'capability_sync', level: 'guideline', passRate: 0.9, totalChecks: 20, bypassRate: 0.1 },
+        { constraintId: 'no_bypass_checkpoint', level: 'iron_law', passRate: 1, failRate: 0, totalChecks: 10 },
+        { constraintId: 'capability_sync', level: 'guideline', passRate: 0.9, failRate: 0.1, totalChecks: 20 },
       ];
       const mockAnalyze = {
         summarize: jest.fn().mockReturnValue(mockSummaries),

package/src/cli/commands/__tests__/status.test.ts

@@ -87,7 +87,7 @@ describe('status command', () => {
       mockFs.readFileSync.mockReturnValue(mockTraces.map(t => JSON.stringify(t)).join('\n'));
 
       const mockSummarize = jest.fn().mockReturnValue([
-        { constraintId: 'test1', level: 'iron_law', passRate: 1, totalChecks: 1, bypassRate: 0 },
+        { constraintId: 'test1', level: 'iron_law', passRate: 1, failRate: 0, totalChecks: 1 },
       ]);
       const mockAnalyze = {
         summarize: mockSummarize,
@@ -106,7 +106,7 @@ describe('status command', () => {
       mockFs.readFileSync.mockReturnValue(mockTraces.map(t => JSON.stringify(t)).join('\n'));
 
       const mockSummarize = jest.fn().mockReturnValue([
-        { constraintId: 'no_bypass_checkpoint', level: 'iron_law', passRate: 1, totalChecks: 5, bypassRate: 0 },
+        { constraintId: 'no_bypass_checkpoint', level: 'iron_law', passRate: 1, failRate: 0, totalChecks: 5 },
       ]);
       const mockAnalyze = {
         summarize: mockSummarize,
@@ -131,7 +131,7 @@ describe('status command', () => {
       ];
       const mockAnalyze = {
         summarize: jest.fn().mockReturnValue([
-          { constraintId: 'test1', level: 'iron_law', passRate: 0.2, totalChecks: 5, bypassRate: 0 },
+          { constraintId: 'test1', level: 'iron_law', passRate: 0.2, failRate: 0.8, totalChecks: 5 },
         ]),
         detectAnomalies: jest.fn().mockReturnValue(mockAnomalies),
       };
@@ -150,7 +150,7 @@ describe('status command', () => {
       mockFs.readFileSync.mockReturnValue(mockTraces.map(t => JSON.stringify(t)).join('\n'));
 
       const mockSummarize = jest.fn().mockReturnValue([
-        { constraintId: 'test1', level: 'iron_law', passRate: 0.8, totalChecks: 10, bypassRate: 0.1 },
+        { constraintId: 'test1', level: 'iron_law', passRate: 0.8, failRate: 0.2, totalChecks: 10 },
       ]);
       const mockAnalyze = {
         summarize: mockSummarize,
@@ -184,7 +184,7 @@ describe('status command', () => {
 
       const mockAnalyze = {
         summarize: jest.fn().mockReturnValue([
-          { constraintId: 'test_guide', level: 'guideline', passRate: 0.9, totalChecks: 10, bypassRate: 0 },
+          { constraintId: 'test_guide', level: 'guideline', passRate: 0.9, failRate: 0.1, totalChecks: 10 },
         ]),
         detectAnomalies: jest.fn().mockReturnValue([]),
       };
@@ -276,7 +276,7 @@ describe('status command', () => {
 
       const mockAnalyze = {
         summarize: jest.fn().mockReturnValue([
-          { constraintId: 'test_guide', level: 'guideline', passRate: 0.6, totalChecks: 10, bypassRate: 0.1 },
+          { constraintId: 'test_guide', level: 'guideline', passRate: 0.6, failRate: 0.4, totalChecks: 10 },
         ]),
         detectAnomalies: jest.fn().mockReturnValue([]),
       };

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

@@ -2,17 +2,16 @@
  * harness check 命令
  *
  * 检查约束是否满足（check 层：Iron Laws / Guidelines；prompt 层仅注入不检查）
- * 工单 23：触发条件与证据检测迁至 core/constraints/context-builder；--preset 经 mergeConstraints 生效
- * ADR-0001：约束集统一走 mergeConstraints 生效集链路（preset/config 禁用/custom/scenes）
+ * 工单 23：触发条件与证据检测迁至 core/constraints/context-builder
+ * ADR-0001：约束集统一走 getMergedConstraintsConfig 生效集链路（preset/config 禁用/custom/scenes）
  */
 
 import chalk from 'chalk';
 import * as fs from 'fs';
 import * as path from 'path';
 import { constraintChecker } from '../../core/constraints/checker';
-import { getTraceCollector } from '../../monitoring/traces';
 import { IRON_LAWS, GUIDELINES, PROMPTS } from '../../core/constraints/definitions';
-import { ProjectConfigLoader } from '../../core/project-config-loader';
+import { getMergedConstraintsConfig } from '../../core/effective-constraints';
 import { buildConstraintContext } from '../../core/constraints/context-builder';
 import { detectInjectionDrift } from '../../core/constraints/injection-drift';
 import { DEFAULT_TRACE_FILE } from '../../types/trace';
@@ -37,18 +36,12 @@ export async function check(options: CheckOptions): Promise<void> {
   console.log(chalk.gray(`预设: ${options.preset}`));
 
   try {
-    // 加载项目级自定义约束
     const projectPath = options.projectPath || process.cwd();
-    const configLoader = new ProjectConfigLoader(projectPath);
-    configLoader.load();
-    constraintChecker.setTraceRecorder(getTraceCollector());
 
     // 生效约束集（ADR-0001）：内置 → preset → config.yml 禁用 → custom 追加 → scenes 过滤。
-    // --preset 仅在没有项目自定义配置时覆盖 config.yml 的 preset（保持工单 23 语义：
-    // 项目自定义配置优先于 CLI 预设）。
-    const merged = configLoader.hasCustomConfig()
-      ? configLoader.mergeConstraints()
-      : configLoader.mergeConstraints({ preset: options.preset || 'standard' });
+    // --preset 仅在没有项目自定义配置时覆盖 config.yml 的 preset（工单 23 语义：
+    // 项目自定义配置优先于 CLI 预设），优先级规则收在 getMergedConstraintsConfig 一处。
+    const merged = getMergedConstraintsConfig(projectPath, { preset: options.preset });
     if (merged.custom.length > 0) {
       console.log(chalk.gray(`自定义约束: ${merged.custom.length} 条`));
     }
@@ -130,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 版本不一致`));
         }
@@ -199,23 +192,7 @@ async function getSmartHint(projectPath: string): Promise<string | null> {
     hints.push('📊 记录已足够，运行 harness status 查看统计');
     state.shownHints.push('trace_50');
   }
-  
-  // 条件 2: 检查异常趋势（简单检查绕过率）
-  const bypassCount = lines.filter(line => {
-    try {
-      const trace = JSON.parse(line);
-      return trace.result === 'bypassed';
-    } catch {
-      return false;
-    }
-  }).length;
-  
-  const bypassRate = traceCount > 10 ? bypassCount / traceCount : 0;
-  if (bypassRate > 0.3 && !state.shownHints.includes('high_bypass')) {
-    hints.push('⚠️ 发现异常趋势，建议运行 harness status 查看详情');
-    state.shownHints.push('high_bypass');
-  }
-  
+
   // 保存状态
   if (hints.length > 0) {
     fs.mkdirSync(path.dirname(statePath), { recursive: true });
@@ -242,14 +219,11 @@ export function listLaws(): void {
   });
 
   // Guidelines
-  console.log(chalk.yellow('🟡 指导原则 (Guidelines) - 优先建议，有例外:\n'));
+  console.log(chalk.yellow('🟡 指导原则 (Guidelines) - 优先建议，违背发警告但不阻止:\n'));
   Object.values(GUIDELINES).forEach(constraint => {
     console.log(chalk.yellow(`  ${constraint.id}`));
     console.log(chalk.gray(`    ${constraint.rule}`));
     console.log(chalk.gray(`    ${constraint.message}`));
-    if (constraint.exceptions && constraint.exceptions.length > 0) {
-      console.log(chalk.gray(`    例外: ${constraint.exceptions.join(', ')}`));
-    }
     console.log();
   });
 

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');
     }