@dommaker/harness 1.3.0 → 1.5.0

package/src/core/constraints/context-builder.ts

@@ -4,55 +4,25 @@
  * 从仓库状态（git diff / traces / 文档标记）推断 ConstraintContext：
  * 触发条件 + 各类证据标志。此前散落在 cli/commands/check.ts，
  * 迁入 core 供 CLI 与其他调用方共用。
+ *
+ * 架构评审 #87：本模块只做装配不做取证——git 证据一律经 git-evidence
+ * adapter 取（缺省真 git adapter，调用方可注入与 checker 层同源的那一份），
+ * 因此此处不再有 child_process / raw execSync。
  */
 
 import * as fs from 'fs';
 import * as path from 'path';
-import { execSync } from 'child_process';
-import { execAsync } from '../../utils/exec';
 import { detectSourceRoots } from '../../utils/detect-source-roots';
+import { readJsonl } from '../../utils/jsonl';
 import { DEFAULT_TRACE_FILE } from '../../types/trace';
+import type { ExecutionTrace } from '../../types/trace';
 import type { ConstraintContext, ConstraintTrigger } from '../../types/constraint';
-
-/**
- * 从 git diff 获取变更的文件
- */
-export async function getChangedFiles(staged: boolean, projectPath?: string): Promise<string[]> {
-  try {
-    const command = staged ? 'git diff --cached --name-only' : 'git diff --name-only';
-    const { stdout } = projectPath
-      ? await execAsync(command, { cwd: projectPath })
-      : await execAsync(command);
-    return String(stdout).trim().split('\n').filter(Boolean);
-  } catch {
-    return [];
-  }
-}
-
-/**
- * 一次性列出 HEAD 中存在的所有目录（工单 18：替代逐文件 git ls-tree）
- *
- * 返回 null 表示命令失败（按惯例视所有目录为"新"）。
- */
-export function listHeadDirs(projectPath: string): Set<string> | null {
-  try {
-    const output = execSync('git ls-tree -r --name-only HEAD', { cwd: projectPath, stdio: 'pipe', encoding: 'utf-8' });
-    const dirs = new Set<string>();
-    for (const file of String(output).split('\n')) {
-      if (!file) continue;
-      const parts = file.split('/');
-      for (let i = 1; i < parts.length; i++) {
-        dirs.add(parts.slice(0, i).join('/'));
-      }
-    }
-    return dirs;
-  } catch {
-    return null;
-  }
-}
+import { createGitEvidence, splitFileNames, type GitEvidence } from './git-evidence';
 
 /**
  * 检查文件所在目录是否在 git HEAD 中不存在（即新目录）
+ *
+ * headDirs 由 git-evidence adapter 取证（null = 命令失败，按惯例视所有目录为"新"）。
  */
 export function isNewDirectory(headDirs: Set<string> | null, filePath: string): boolean {
   if (headDirs === null) return true; // 命令失败 = 假定为新
@@ -71,10 +41,17 @@ const CODE_FILE_REGEX = /\.(?:ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|cs|c
  *
  * ADR-0001：变更包含代码文件时，在主推断之外附加 code_implementation
  * （返回数组 [主推断, 'code_implementation']；主推断逻辑保持不变）。
+ *
+ * 新目录判定所需的 HEAD 目录集经 git 证据 adapter 取（#87）：
+ * 调用方注入即与 checker 层同一份证据，缺省走真 git adapter。
  */
 export function detectTrigger(
   changedFiles: string[],
-  options: { trigger?: ConstraintTrigger; projectPath?: string }
+  options: {
+    trigger?: ConstraintTrigger;
+    projectPath?: string;
+    evidence?: GitEvidence;
+  }
 ): ConstraintTrigger | ConstraintTrigger[] {
   if (options.trigger) return options.trigger;
 
@@ -89,7 +66,10 @@ export function detectTrigger(
   const hasModuleChange = changedFiles.some(f =>
     sourceRoots.some(root => f.startsWith(root + '/') || f.startsWith(root + '\\')) && !f.includes('__tests__')
   );
-  const headDirs = hasModuleChange ? listHeadDirs(projectPath) : null;
+  // 工单 18 的批量语义保留在 adapter 层：一次 ls-tree，且仅在有模块变更时才取证
+  const headDirs = hasModuleChange
+    ? (options.evidence ?? createGitEvidence(projectPath)).headDirs()
+    : null;
   const hasModuleCreation = changedFiles.some(f =>
     sourceRoots.some(root => f.startsWith(root + '/') || f.startsWith(root + '\\')) &&
     isNewDirectory(headDirs, f)
@@ -111,22 +91,11 @@ export function detectTrigger(
 export async function detectFailingTest(projectPath: string): Promise<boolean> {
   try {
     const traceFile = path.join(projectPath, DEFAULT_TRACE_FILE);
-    if (!fs.existsSync(traceFile)) return false;
-
-    const content = fs.readFileSync(traceFile, 'utf-8');
-    const lines = content.trim().split('\n').filter(Boolean);
-    if (lines.length === 0) return false;
-
-    // 检查最近 20 条记录是否有 fail
-    const recent = lines.slice(-20);
-    return recent.some(line => {
-      try {
-        const trace = JSON.parse(line);
-        return trace.result === 'fail';
-      } catch {
-        return false;
-      }
-    });
+    // 坏行策略：skip（原逐行 catch→false 语义不变）；只 parse 最近 20 行
+    // 计数去向：豁免（harness#100）——布尔证据探测，坏行只会让证据变少（判定方向保守），
+    // 消费面是 check 的 pass/fail 判定，没有可挂计数的输出位
+    const { records } = readJsonl<ExecutionTrace>(traceFile, 'skip', { tail: 20 });
+    return records.some(trace => trace.result === 'fail');
   } catch {
     return false;
   }
@@ -161,22 +130,12 @@ export function detectRootCauseInvestigation(projectPath: string): boolean {
 export async function detectVerificationEvidence(projectPath: string): Promise<boolean> {
   try {
     const traceFile = path.join(projectPath, DEFAULT_TRACE_FILE);
-    if (!fs.existsSync(traceFile)) return false;
-
-    const content = fs.readFileSync(traceFile, 'utf-8');
-    const lines = content.trim().split('\n').filter(Boolean);
-    if (lines.length === 0) return false;
-
-    // 检查最近 10 条记录是否有 pass
-    const recent = lines.slice(-10);
-    return recent.some(line => {
-      try {
-        const trace = JSON.parse(line);
-        return trace.result === 'pass';
-      } catch {
-        return false;
-      }
-    });
+    // 坏行策略：skip（原逐行 catch→false 语义不变）；只 parse 最近 10 行
+    // tail 在 parse 之前截断 → 坏行会占用尾部槽位（#82 裁决范围外的既有口径，本票不改）
+    // 计数去向：豁免（harness#100）——同 detectFailingTest：布尔证据探测无计数输出位，
+    // 坏行只会让证据变少
+    const { records } = readJsonl<ExecutionTrace>(traceFile, 'skip', { tail: 10 });
+    return records.some(trace => trace.result === 'pass');
   } catch {
     return false;
   }
@@ -209,21 +168,6 @@ export function detectRequirement(projectPath: string): boolean {
   return indicators.some(f => fs.existsSync(path.join(projectPath, f)));
 }
 
-/**
- * 检测是否在 git worktree 中
- */
-export function detectWorktree(projectPath: string): boolean {
-  try {
-    const gitDir = path.join(projectPath, '.git');
-    if (fs.existsSync(gitDir)) {
-      const content = fs.readFileSync(gitDir, 'utf-8');
-      // 实际 worktree 的 .git 是文件（指向主 repo），不是目录
-      return content.startsWith('gitdir:');
-    }
-  } catch { /* ignore */ }
-  return false;
-}
-
 /**
  * 检测是否有复用检查
  * 检查 .harness/reuse/ 目录或相关文档
@@ -244,15 +188,20 @@ export function detectReuseCheck(projectPath: string): boolean {
 
 /**
  * 构建约束上下文：变更文件 + 触发条件推断 + 证据标志检测
+ *
+ * options.evidence（#87）：git 证据适配器。调用方（CLI check）注入同一实例给
+ * checkConstraints，即可让 context-builder 与 checker 层共用同一证据来源。
  */
 export async function buildConstraintContext(options: {
   projectPath?: string;
   staged: boolean;
   trigger?: ConstraintTrigger;
+  evidence?: GitEvidence;
 }): Promise<ConstraintContext> {
   const projectPath = options.projectPath || process.cwd();
-  const changedFiles = await getChangedFiles(options.staged, options.projectPath);
-  const inferred = detectTrigger(changedFiles, { trigger: options.trigger, projectPath });
+  const evidence = options.evidence ?? createGitEvidence(projectPath);
+  const changedFiles = splitFileNames(evidence.changedFileNames(options.staged));
+  const inferred = detectTrigger(changedFiles, { trigger: options.trigger, projectPath, evidence });
   const triggers = Array.isArray(inferred) ? inferred : [inferred];
 
   return {
@@ -266,6 +215,5 @@ export async function buildConstraintContext(options: {
     hasVerificationEvidence: await detectVerificationEvidence(projectPath),
     hasReuseCheck: detectReuseCheck(projectPath),
     hasRequirement: detectRequirement(projectPath),
-    hasWorktree: detectWorktree(projectPath),
   };
 }

package/src/core/constraints/doc-freshness/runner.ts

@@ -8,6 +8,7 @@
 import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { detectSourceRoots } from '../../../utils/detect-source-roots';
+import { DEFAULT_SKIP_DIRS } from '../../../utils/file-walk';
 import type {
   DocFreshnessCheck,
   DocFreshnessConfig,
@@ -238,7 +239,7 @@ export class FreshnessRunner {
       if (!check.skip_reverse_check) {
         // 从文档目录中推断要扫描的根目录集
         const rootDirs = this.inferRootDirs(docDirs, ctx.projectPath);
-        const excludeSet = new Set(check.exclude || ['__tests__', 'node_modules', 'dist']);
+        const excludeSet = new Set(check.exclude || DEFAULT_SKIP_DIRS);
 
         for (const rootDir of rootDirs) {
           const absRoot = join(ctx.projectPath, rootDir);

package/src/core/constraints/git-evidence.ts

@@ -0,0 +1,120 @@
+/**
+ * git 证据适配器（架构评审 #87）
+ *
+ * 全仓唯一的 git 取证点：context-builder（触发推断）与 checker 层（CheckEnv 证据）
+ * 共用同一实例 = 共用同一证据来源。此前两处各自抓真 git，一次 CLI check 里
+ * `git diff --cached --name-only` 实跑两遍。
+ *
+ * seam 上的两个真 adapter：
+ * - 缺省 realGitCommandRunner：真 git 子进程
+ * - 注入 runner：委托/计数/命令表（测试与定制场景）
+ *
+ * memo 落在实例层（命令 → 结果，含失败结果），实例生命周期 = 一次 check run，
+ * 因此不存在隐式全局（工单 18 的 run 级收益保留，形状改为显式传递）。
+ */
+
+import { execSync } from 'child_process';
+
+/**
+ * git 命令执行器：返回 trim 后的 stdout，失败抛错（由 adapter 归类为「无该证据」）
+ *
+ * command 恒为本模块内的固定字面量，cwd 来自调用方（非 shell 拼接），无注入面。
+ */
+export type GitCommandRunner = (command: string, cwd: string) => string;
+
+/**
+ * git 证据：一次 run 内的 git 事实快照，同类命令至多执行一次
+ *
+ * 判定语义与原 context-builder / checker 私有实现逐条对齐：
+ * - diff 类命令失败 → 空串（无变更证据）
+ * - ls-tree 失败 → null（调用方按「所有目录都是新目录」处理）
+ */
+export interface GitEvidence {
+  /** 取证基准目录（git 命令的 cwd） */
+  readonly projectPath: string;
+  /** staged 全量 diff（`git diff --cached`） */
+  stagedDiff(): string;
+  /** 变更文件名列表，\n 分隔（staged → `git diff --cached --name-only`） */
+  changedFileNames(staged: boolean): string;
+  /** HEAD 中存在的目录集合；命令失败 → null */
+  headDirs(): Set<string> | null;
+}
+
+/** 与 utils/exec.runCommand 同一缓冲上限（大 diff 不 ENOBUFS） */
+const GIT_MAX_BUFFER = 1024 * 1024;
+
+/**
+ * 真 git adapter：同步 spawn，失败抛错交由 memo 归类
+ *
+ * execSync 声明返回 string | Buffer（Buffer 无 trim），故显式归一为 string——
+ * 与迁移前 context-builder 的 `String(output)` 取值语义一致。
+ */
+export const realGitCommandRunner: GitCommandRunner = (command, cwd) =>
+  String(
+    execSync(command, { cwd, stdio: 'pipe', encoding: 'utf-8', maxBuffer: GIT_MAX_BUFFER })
+  ).trim();
+
+const STAGED_DIFF = 'git diff --cached';
+const STAGED_DIFF_NAMES = 'git diff --cached --name-only';
+const UNSTAGED_DIFF_NAMES = 'git diff --name-only';
+const HEAD_TREE = 'git ls-tree -r --name-only HEAD';
+
+/**
+ * 从 `git ls-tree -r --name-only HEAD` 输出提取 HEAD 中存在的所有目录
+ *
+ * 工单 18 批量语义：一次命令替代逐文件 ls-tree。
+ */
+export function parseHeadDirs(treeOutput: string): Set<string> {
+  const dirs = new Set<string>();
+  for (const file of treeOutput.split('\n')) {
+    if (!file) continue;
+    const parts = file.split('/');
+    for (let i = 1; i < parts.length; i++) {
+      dirs.add(parts.slice(0, i).join('/'));
+    }
+  }
+  return dirs;
+}
+
+/**
+ * 构造 git 证据 adapter（生产侧唯一构造点）
+ *
+ * @param projectPath 取证目录
+ * @param run 命令执行器，缺省真 git；测试注入计数/替身执行器即可脱离子进程
+ */
+export function createGitEvidence(
+  projectPath: string,
+  run: GitCommandRunner = realGitCommandRunner
+): GitEvidence {
+  type CommandResult = { ok: boolean; stdout: string };
+  const memo = new Map<string, CommandResult>();
+
+  const once = (command: string): CommandResult => {
+    let result = memo.get(command);
+    if (!result) {
+      try {
+        result = { ok: true, stdout: run(command, projectPath) };
+      } catch {
+        result = { ok: false, stdout: '' };
+      }
+      memo.set(command, result);
+    }
+    return result;
+  };
+
+  return {
+    projectPath,
+    stagedDiff: () => once(STAGED_DIFF).stdout,
+    changedFileNames: (staged: boolean) =>
+      once(staged ? STAGED_DIFF_NAMES : UNSTAGED_DIFF_NAMES).stdout,
+    headDirs: () => {
+      const result = once(HEAD_TREE);
+      return result.ok ? parseHeadDirs(result.stdout) : null;
+    },
+  };
+}
+
+/** 变更文件名列表 → 路径数组（git 无输出时为空集合） */
+export function splitFileNames(names: string): string[] {
+  return names.split('\n').filter(Boolean);
+}

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

@@ -17,18 +17,18 @@
  * 两处均无标记段 = 未注入，不算漂移（report 一句话提示，check 不警告）。
  */
 
-import * as fs from 'fs';
 import * as path from 'path';
 import { getEffectiveConstraints } from '../effective-constraints';
+import { getHarnessPackageVersion } from '../../utils/package-version';
+import { CONSTRAINTS_END_MARKER, renderConstraintsSection } from './injection-renderer';
 import {
-  CONSTRAINTS_START_MARKER,
-  CONSTRAINTS_END_MARKER,
-  renderConstraintsSection,
-} from './injection-renderer';
+  resolveInjectionTarget,
+  readIfExists,
+  countGovernanceHeadings,
+  type InjectionFile,
+} from './injection-writer';
 
-/** 注入段落点文件名（检测顺序即路由优先级：旧模型仓 CLAUDE.md 豁免优先） */
-const INJECTION_FILES = ['CLAUDE.md', 'AGENTS.md'] as const;
-export type InjectionFile = (typeof INJECTION_FILES)[number];
+export type { InjectionFile };
 
 /** 注入漂移检测结果 */
 export interface InjectionDrift {
@@ -57,20 +57,6 @@ export const INJECTION_DRIFT_FIX_HINT = '重跑 `npx @dommaker/harness init` 同
 const VERSION_LINE_RE = /<!-- version: ([^ ]+) -->/;
 const ENTRY_LINE_RE = /^- \*\*.+?\*\*: .+$/;
 const GROUP_HEADING_RE = /^### .+$/;
-const GOVERNANCE_HEADING_RE = /^## Governance Rules[ \t]*$/gm;
-
-/**
- * 读取当前 harness 包版本（与 init 注入时写入的版本同源）
- */
-function getPackageVersion(): string {
-  try {
-    const pkgPath = path.join(__dirname, '..', '..', '..', 'package.json');
-    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-    return pkg.version ?? 'unknown';
-  } catch {
-    return 'unknown';
-  }
-}
 
 /**
  * 提取参与条目级比对的"有效行"：注入条目（- **id**: text）与分组标题（### ...）。
@@ -83,48 +69,15 @@ 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;
-}
-
 /**
  * 检测约束注入段漂移
  *
  * @param projectRoot 项目根路径
- * @param currentVersion 当前 harness 版本（缺省读 package.json；测试可显式传入）
+ * @param currentVersion 当前 harness 版本（缺省经 getHarnessPackageVersion 正本读取；测试可显式传入）
  */
 export function detectInjectionDrift(
   projectRoot: string,
-  currentVersion: string = getPackageVersion()
+  currentVersion: string = getHarnessPackageVersion()
 ): InjectionDrift {
   const result: InjectionDrift = {
     hasDrift: false,
@@ -141,7 +94,7 @@ export function detectInjectionDrift(
       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.duplicateHeading = countGovernanceHeadings(legacy) > 1;
     }
     result.notInjected = true;
     return result;
@@ -150,8 +103,8 @@ export function detectInjectionDrift(
   result.injectionFile = target.file;
   const { content, startIdx, endIdx } = target;
 
-  // 重复章节：全文统计 `## Governance Rules` 标题数（含标记段所属的合法标题）
-  const headingCount = (content.match(GOVERNANCE_HEADING_RE) ?? []).length;
+  // 重复章节：全文统计治理标题数（严格计数 injection-writer.countGovernanceHeadings，#83）
+  const headingCount = countGovernanceHeadings(content);
   result.duplicateHeading = headingCount > 1;
 
   const actualSection = content.slice(startIdx, endIdx + CONSTRAINTS_END_MARKER.length);

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

@@ -0,0 +1,212 @@
+/**
+ * 治理注入段落点写入器（架构评审候选1，ADR-0011）
+ *
+ * 「按渲染 body 替换标记区间 + 尾换行规一」的切片数学此前手抄 4 份
+ * （init.ts 三个 writer / constraints-retire 一份），落点路由读写两侧各抄一份。
+ * 本模块是唯一 writer：init/retire 退化为「渲染 body + 调 writer」。
+ *
+ * 形状两种（排版约定不同，非"算哪些"的差异，故合法分叉）：
+ * - replaceStandaloneRange：区间独立成节，END 标记后折叠为恰好一个空行
+ *   （CLAUDE.md 约束段 / Output Style 段 / retire 注入段同步）
+ * - replaceEnclosedRange：区间后紧跟外层收口标记（AGENTS.md PRESERVE 段内
+ *   的 HARNESS_CONSTRAINTS 区间）——恰好剥一个换行，手写余文原样落回
+ *
+ * 半标记守护：单边缺失或顺序颠倒 → 'half'，拒写（旧实现此时或追加出双份
+ * 正本或产生乱序切片，属二次损坏路径，收紧为告警交人工，见 ADR-0011）。
+ *
+ * 落点路由同规则一份：
+ * - resolveInjectionTarget：读侧（漂移检测/retire 同步）——CLAUDE.md 有完整
+ *   标记段优先（旧模型仓豁免），否则 AGENTS.md（新模型仓住 PRESERVE 段内）
+ * - resolveGovernanceLanding：写侧（init 落点选择）——额外承认 CLAUDE.md
+ *   无标记的 `## Governance Rules` 旧块（续写不制造双份正本）
+ *
+ * 探测/判定同住本模块（#83，ADR-0011 补注：收口范围含探测器，不只写器）——
+ * 「这份文档里有没有治理契约 / 有几个正本标题」此前手抄 4 份且正则已漂移，
+ * 见文末 GOVERNANCE_HEADING / hasGovernanceContract / countGovernanceHeadings /
+ * hasPreserveBlock。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import {
+  CONSTRAINTS_START_MARKER,
+  CONSTRAINTS_END_MARKER,
+} from './injection-renderer';
+
+/** 注入段落点文件名（检测顺序即路由优先级：旧模型仓 CLAUDE.md 优先） */
+export const INJECTION_FILES = ['CLAUDE.md', 'AGENTS.md'] as const;
+export type InjectionFile = (typeof INJECTION_FILES)[number];
+
+/** 标记区间替换结果 */
+export type MarkerWrite =
+  | { kind: 'updated'; content: string }
+  | { kind: 'absent' }
+  | { kind: 'half' };
+
+/** 完整标记块的内容切分（inner 含首尾标记行外的全部文本，含原换行） */
+export interface MarkerBlock {
+  before: string;
+  inner: string;
+  /** 后标记之后的原文（未规一） */
+  after: string;
+}
+
+export function readIfExists(filePath: string): string | null {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return typeof content === 'string' ? content : null;
+  } catch {
+    return null;
+  }
+}
+
+/** 定位完整标记对：两标记俱在且顺序正确 */
+function findPair(content: string, begin: string, end: string): { startIdx: number; endIdx: number } | 'absent' | 'half' {
+  const startIdx = content.indexOf(begin);
+  const endIdx = content.indexOf(end);
+  if (startIdx === -1 && endIdx === -1) return 'absent';
+  if (startIdx === -1 || endIdx === -1 || endIdx < startIdx) return 'half';
+  return { startIdx, endIdx };
+}
+
+/**
+ * 切出完整标记块（before + begin + inner + end + after）。
+ * 'absent' = 两俱无；'half' = 残缺/乱序，拒切。
+ */
+export function cutMarkerBlock(content: string, begin: string, end: string): MarkerBlock | 'absent' | 'half' {
+  const pair = findPair(content, begin, end);
+  if (pair === 'absent' || pair === 'half') return pair;
+  return {
+    before: content.slice(0, pair.startIdx),
+    inner: content.slice(pair.startIdx + begin.length, pair.endIdx),
+    after: content.slice(pair.endIdx + end.length),
+  };
+}
+
+/**
+ * 替换独立成节的标记区间：body 为含首尾标记的完整替换文本（以换行结尾），
+ * 区间后文剥除全部前导换行、以恰好一个空行相接（幂等：重复替换结果稳定）。
+ */
+export function replaceStandaloneRange(content: string, begin: string, end: string, body: string): MarkerWrite {
+  const pair = findPair(content, begin, end);
+  if (pair === 'absent' || pair === 'half') return { kind: pair };
+  const after = content.slice(pair.endIdx + end.length).replace(/^\n+/, '');
+  return {
+    kind: 'updated',
+    content: content.slice(0, pair.startIdx) + body + (after ? '\n' + after : ''),
+  };
+}
+
+/**
+ * 替换后跟外层收口标记的区间：body 含首尾标记且以换行结尾（收口标记落自己行），
+ * 区间后文恰好剥一个换行（外层标记拼接位），其余手写余文原样保留。
+ */
+export function replaceEnclosedRange(content: string, begin: string, end: string, body: string): MarkerWrite {
+  const pair = findPair(content, begin, end);
+  if (pair === 'absent' || pair === 'half') return { kind: pair };
+  const tail = content.slice(pair.endIdx + end.length).replace(/^\n/, '');
+  return {
+    kind: 'updated',
+    content: content.slice(0, pair.startIdx) + body + tail,
+  };
+}
+
+/**
+ * 读侧路由：定位含完整 HARNESS_CONSTRAINTS 标记段的文件（studio #307）。
+ * detectInjectionDrift 与 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;
+}
+
+/**
+ * 写侧路由（init 落点选择，原 setupGovernanceConstraints 内联判定收于此）：
+ * CLAUDE.md 有约束标记段或有旧版 `## Governance Rules` 块 → 续写 CLAUDE.md
+ * （旧模型仓豁免，不制造双份正本）；否则 AGENTS.md PRESERVE:governance。
+ */
+export function resolveGovernanceLanding(
+  projectRoot: string
+): { target: 'claude-md' | 'agents-md'; claudeContent: string | null } {
+  const claudeContent = readIfExists(path.join(projectRoot, 'CLAUDE.md'));
+  if (claudeContent !== null && hasGovernanceContract(claudeContent)) {
+    return { target: 'claude-md', claudeContent };
+  }
+  return { target: 'agents-md', claudeContent };
+}
+
+/**
+ * 治理正本标题字面量（单一来源，#83）：init 的标题写点与下列两个判定谓词
+ * 都由它派生，仓内不再本地拼写。字面量无正则元字符，可直接拼入 RegExp。
+ *
+ * 两谓词回答两个问题，**共享字面量而非共享正则**（triage 裁决 2026-09-02）：
+ * 强行合一要么在场守护 fail-open 失效（取严格），要么重复计数引入无行尾
+ * 锚定的误报（取宽松）。
+ */
+export const GOVERNANCE_HEADING = '## Governance Rules';
+
+/** 标题文本（去 `## ` 前缀），宽松谓词按 `##` + 任意空白 + 此文本匹配 */
+const GOVERNANCE_HEADING_TEXT = GOVERNANCE_HEADING.replace(/^##\s+/, '');
+
+/** 宽松标题正则：容忍 `##  Governance Rules` 双空格等排版漂移 */
+const GOVERNANCE_HEADING_LOOSE_RE = new RegExp(`^##\\s+${GOVERNANCE_HEADING_TEXT}`, 'm');
+
+/** 严格标题正则：精确拼写 + 行尾锚定（行尾仅容忍空白） */
+const GOVERNANCE_HEADING_STRICT_RE = new RegExp(`^${GOVERNANCE_HEADING}[ \\t]*$`, 'gm');
+
+/** 约束标记裸文本（去注释壳），宽松谓词按「标记文本在场」判定，容忍壳残缺 */
+const CONSTRAINTS_START_TEXT = CONSTRAINTS_START_MARKER.replace(/^<!--\s*|\s*-->$/g, '');
+
+/**
+ * 宽松谓词：内容里是否有治理契约在场——标题宽松匹配或 HARNESS 约束标记
+ * 文本在场即算。fail-open 偏向：排版漂移宁可信其有，漏报「约束正本静默
+ * 丢失」的代价高于误报。消费方：governance_presence / sync-docs 治理计数 /
+ * init 落点路由（#83）。
+ */
+export function hasGovernanceContract(content: string): boolean {
+  return GOVERNANCE_HEADING_LOOSE_RE.test(content) || content.includes(CONSTRAINTS_START_TEXT);
+}
+
+/**
+ * 严格计数：全文统计治理标题数（精确拼写 + 行尾锚定），drift 重复章节
+ * 检测专用。宽松变体（如双空格）不计入——在场判定与正本计数是两个问题，
+ * 见 GOVERNANCE_HEADING。
+ */
+export function countGovernanceHeadings(content: string): number {
+  return (content.match(GOVERNANCE_HEADING_STRICT_RE) ?? []).length;
+}
+
+/**
+ * PRESERVE 标记块存在性判定：块存在且块体非空（governance_presence 在场
+ * 守护消费，#83 收编其手写切片）。标记契约与 sync-docs/preserve-block 一致：
+ * 首尾标记均须独占一行——开始标记行首锚定（行尾仅空白），结束标记行 trim
+ * 后等于标记文本。结束标记嵌在行中 / 缺失 / 乱序均为畸形块 → false，在场
+ * 守护按契约丢失报警（原 presence「行中结束标记也算在场」显式收紧，#83）。
+ * name 仅允许字母/数字/下划线/连字符（PRESERVE 命名约定，调用方传常量段名）。
+ */
+export function hasPreserveBlock(content: string, name: string): boolean {
+  const beginMarker = `<!-- PRESERVE:${name} -->`;
+  const endMarker = `<!-- /PRESERVE:${name} -->`;
+  const lines = content.split('\n');
+  const begin = lines.findIndex(line => line.trimEnd() === beginMarker);
+  if (begin === -1) return false;
+  let end = -1;
+  for (let j = begin + 1; j < lines.length; j++) {
+    if (lines[j].trim() === endMarker) {
+      end = j;
+      break;
+    }
+  }
+  if (end === -1) return false;
+  return lines.slice(begin + 1, end).join('\n').trim().length > 0;
+}