@dommaker/harness 1.2.0 → 1.2.1

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

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

package/src/core/constraints/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. 版本漂移