@dommaker/harness 1.3.0 → 1.4.0

package/src/cli/commands/init.ts

@@ -5,18 +5,27 @@
  */
 
 import chalk from 'chalk';
-import { readFileSync } from 'fs';
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
 import { createExampleCheckpoint, createExampleResolutions } from './validate';
 import { detectSourceRoots } from '../../utils/detect-source-roots';
+import { getHarnessPackageVersion } from '../../utils/package-version';
 import { getEffectiveConstraints } from '../../core/effective-constraints';
+import type { GovernanceConfig } from '../../types/project-config';
 import {
   CONSTRAINTS_START_MARKER,
   CONSTRAINTS_END_MARKER,
   renderConstraintsSection,
 } from '../../core/constraints/injection-renderer';
+import {
+  replaceStandaloneRange,
+  replaceEnclosedRange,
+  cutMarkerBlock,
+  resolveGovernanceLanding,
+  GOVERNANCE_HEADING,
+} from '../../core/constraints/injection-writer';
+import { log, processIO, type CommandIO, type CommandResult } from '../command-contract';
 
 export interface InitOptions {
   /** 项目路径 */
@@ -67,9 +76,9 @@ const PRESETS = {
 };
 
 /**
- * 治理预设
+ * 治理预设（形状 = 写入 config.yml 的 governance 段，直接用类型正本）
  */
-const GOVERNANCE_PRESETS: Record<string, Record<string, unknown>> = {
+const GOVERNANCE_PRESETS: Record<string, GovernanceConfig> = {
   minimal: {
     level: 'minimal',
     docs: {
@@ -135,117 +144,111 @@ const GOVERNANCE_PRESETS: Record<string, Record<string, unknown>> = {
 /**
  * 初始化项目
  */
-export async function init(options: InitOptions): Promise<void> {
+export async function init(options: InitOptions, io: CommandIO = processIO): Promise<CommandResult> {
   // 只输出代码片段
   if (options.printSnippets) {
-    printSnippets();
-    return;
+    printSnippets(io);
+    return { kind: 'ok' };
   }
 
-  console.log(chalk.blue('🚀 初始化 harness 配置...'));
+  log(io, chalk.blue('🚀 初始化 harness 配置...'));
 
   const projectPath = options.projectPath || process.cwd();
   const configDir = path.join(projectPath, '.harness');
 
   // 创建配置目录
   await fs.mkdir(configDir, { recursive: true });
-  console.log(chalk.gray(`配置目录: ${configDir}`));
+  log(io, chalk.gray(`配置目录: ${configDir}`));
 
   // 选择预设
   const preset = PRESETS[options.preset];
-  console.log(chalk.gray(`预设: ${options.preset}`));
+  log(io, chalk.gray(`预设: ${options.preset}`));
 
   // 合并治理配置
   const configData: Record<string, unknown> = { ...preset };
   if (options.governance) {
     configData.governance = GOVERNANCE_PRESETS[options.governance];
-    console.log(chalk.gray(`治理级别: ${options.governance}`));
+    log(io, chalk.gray(`治理级别: ${options.governance}`));
   }
 
   // 写入 harness 版本
-  const pkgVersion = getPackageVersion();
+  const pkgVersion = getHarnessPackageVersion();
   configData.harness = { version: pkgVersion };
 
   // 写入配置文件（harness 管理的配置，始终重新生成）
   const configPath = path.join(configDir, 'config.yml');
   const configContent = yaml.dump(configData, { indent: 2 });
   await fs.writeFile(configPath, configContent, 'utf-8');
-  console.log(chalk.green(`✅ 已创建配置文件: ${configPath} (v${pkgVersion})`));
+  log(io, chalk.green(`✅ 已创建配置文件: ${configPath} (v${pkgVersion})`));
 
   // 创建检查点示例
-  await createExampleCheckpoint(projectPath);
+  await createExampleCheckpoint(projectPath, io);
 
   // 创建 Resolutions（RKB 狗粮 — 约束 → 已知解法映射）
-  await createExampleResolutions(projectPath);
+  await createExampleResolutions(projectPath, io);
 
   // 创建自定义约束示例
-  await createCustomConstraintsExample(projectPath);
+  await createCustomConstraintsExample(projectPath, io);
 
   // CAPABILITIES.md / CHANGELOG.md 由 sync-docs（AI 治理）管理，init 不创建
 
   // 创建 Git hooks
   if (options.gitHooks !== false) {
-    await setupGitHooks(projectPath);
+    await setupGitHooks(projectPath, io);
   }
 
   // 创建 GitHub Actions
   if (options.githubActions !== false) {
-    await setupGitHubActions(projectPath);
+    await setupGitHubActions(projectPath, io);
   }
 
   // 治理相关文件生成
   if (options.governance) {
-    await setupGovernance(projectPath, options.governance);
-  }
-
-  console.log();
-  console.log(chalk.green('✅ harness 初始化完成！'));
-  console.log();
-  console.log(chalk.gray('下一步:'));
-  console.log(chalk.gray('  1. 编辑 .harness/config.yml 自定义配置'));
-  console.log(chalk.gray('  2. 编辑 .harness/custom-constraints.yml 添加项目约束'));
-  console.log(chalk.gray('  3. 正常开发，每次 git commit 会自动检查约束'));
-  console.log(chalk.gray('  4. 运行 harness status 查看状态'));
-  console.log();
-  console.log(chalk.blue('💡 提示: 使用 harness init --print-snippets 查看配置代码片段'));
-}
-
-/**
- * 获取 harness 包版本
- */
-function getPackageVersion(): string {
-  try {
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
-    return require('../../../package.json').version;
-  } catch {
-    return 'unknown';
-  }
+    await setupGovernance(projectPath, options.governance, io);
+  }
+
+  log(io);
+  log(io, chalk.green('✅ harness 初始化完成！'));
+  log(io);
+  log(io, chalk.gray('下一步:'));
+  log(io, chalk.gray('  1. 编辑 .harness/config.yml 自定义配置'));
+  log(io, chalk.gray('  2. 编辑 .harness/custom-constraints.yml 添加项目约束'));
+  log(io, chalk.gray('  3. 正常开发，每次 git commit 会自动检查约束'));
+  log(io, chalk.gray('  4. 运行 harness status 查看状态'));
+  log(io);
+  log(io, chalk.blue('💡 提示: 使用 harness init --print-snippets 查看配置代码片段'));
+  return { kind: 'ok' };
 }
 
 /**
  * 输出代码片段
  */
-function printSnippets(): void {
-  console.log(chalk.blue('📄 Harness 配置代码片段'));
-  console.log();
+function printSnippets(io: CommandIO): void {
+  log(io, chalk.blue('📄 Harness 配置代码片段'));
+  log(io);
   
-  console.log(chalk.yellow('Git pre-commit hook:'));
-  console.log(chalk.gray('添加到 .git/hooks/pre-commit'));
-  console.log();
-  console.log(chalk.cyan(PRE_COMMIT_SNIPPET));
+  log(io, chalk.yellow('Git pre-commit hook:'));
+  log(io, chalk.gray('添加到 .git/hooks/pre-commit'));
+  log(io);
+  log(io, chalk.cyan(PRE_COMMIT_SNIPPET));
   
-  console.log(chalk.yellow('GitHub Actions:'));
-  console.log(chalk.gray('添加到 .github/workflows/*.yml 的 jobs 中'));
-  console.log();
-  console.log(chalk.cyan(GITHUB_ACTIONS_SNIPPET));
+  log(io, chalk.yellow('GitHub Actions:'));
+  log(io, chalk.gray('添加到 .github/workflows/*.yml 的 jobs 中'));
+  log(io);
+  log(io, chalk.cyan(GITHUB_ACTIONS_SNIPPET));
   
-  console.log(chalk.blue('💡 提示: 运行 npx @dommaker/harness init 自动创建配置文件'));
+  log(io, chalk.blue('💡 提示: 运行 npx @dommaker/harness init 自动创建配置文件'));
 }
 
 /**
- * Git pre-commit 代码片段
+ * Git pre-commit 代码片段（#103：打印片段与落盘 hook 的唯一正本；
+ * 落盘 hook = `#!/bin/sh` 头 + 本常量，改钩子只改这里）
  */
 const PRE_COMMIT_SNIPPET = `
+echo "🔍 Running harness checks..."
+
+STAGED=$(git diff --cached --name-only --diff-filter=ACMR 2>/dev/null || true)
+
 # Harness 约束检查
 npx @dommaker/harness check --staged
 if [ $? -ne 0 ]; then
@@ -254,7 +257,6 @@ if [ $? -ne 0 ]; then
 fi
 
 # Plan coverage check (via PostEval)
-STAGED=$(git diff --cached --name-only --diff-filter=ACMR 2>/dev/null || true)
 if command -v npx > /dev/null 2>&1; then
   PLAN_FILES=$(echo "$STAGED" | grep -E 'plans/.*\\.md$|\\.plan\\.md$' || true)
   if [ -n "$PLAN_FILES" ]; then
@@ -267,6 +269,8 @@ if command -v npx > /dev/null 2>&1; then
     done
   fi
 fi
+
+echo "✅ All checks passed"
 `;
 
 /**
@@ -287,7 +291,7 @@ const GITHUB_ACTIONS_SNIPPET = `
 /**
  * 设置 Git hooks
  */
-async function setupGitHooks(projectPath: string): Promise<void> {
+async function setupGitHooks(projectPath: string, io: CommandIO): Promise<void> {
   const gitDir = path.join(projectPath, '.git');
   const hooksDir = path.join(gitDir, 'hooks');
   const preCommitPath = path.join(hooksDir, 'pre-commit');
@@ -295,8 +299,8 @@ async function setupGitHooks(projectPath: string): Promise<void> {
   try {
     await fs.access(gitDir);
   } catch {
-    console.log(chalk.yellow('⚠️  未检测到 Git 仓库，跳过 Git hooks'));
-    console.log(chalk.gray('💡 初始化 Git 后可运行 npx @dommaker/harness init --print-snippets 查看配置'));
+    log(io, chalk.yellow('⚠️  未检测到 Git 仓库，跳过 Git hooks'));
+    log(io, chalk.gray('💡 初始化 Git 后可运行 npx @dommaker/harness init --print-snippets 查看配置'));
     return;
   }
 
@@ -306,52 +310,25 @@ async function setupGitHooks(projectPath: string): Promise<void> {
   try {
     await fs.access(preCommitPath);
     // 已存在，输出代码片段
-    console.log(chalk.yellow('⚠️  .git/hooks/pre-commit 已存在'));
-    console.log(chalk.gray('💡 请手动添加以下内容到文件末尾：'));
-    console.log();
-    console.log(chalk.cyan(PRE_COMMIT_SNIPPET));
+    log(io, chalk.yellow('⚠️  .git/hooks/pre-commit 已存在'));
+    log(io, chalk.gray('💡 请手动添加以下内容到文件末尾：'));
+    log(io);
+    log(io, chalk.cyan(PRE_COMMIT_SNIPPET));
   } catch {
-    // 不存在，创建文件
+    // 不存在，创建文件：shebang 头 + 共享片段（#103 同源，无第二份文本）
     const preCommitContent = `#!/bin/sh
 # Harness pre-commit hook
-
-echo "🔍 Running harness checks..."
-
-STAGED=$(git diff --cached --name-only --diff-filter=ACMR 2>/dev/null || true)
-
-# 铁律检查
-npx @dommaker/harness check --staged
-if [ $? -ne 0 ]; then
-  echo "❌ Iron law check failed"
-  exit 1
-fi
-
-# Plan coverage check (via PostEval)
-if command -v npx > /dev/null 2>&1; then
-  PLAN_FILES=$(echo "$STAGED" | grep -E 'plans/.*\\.md$|\\.plan\\.md$' || true)
-  if [ -n "$PLAN_FILES" ]; then
-    echo "📋 Checking plan coverage..."
-    for plan in $PLAN_FILES; do
-      npx @dommaker/harness posteval-plan "$plan" || {
-        echo "🛑 Plan coverage incomplete. See above for missed items."
-        exit 1
-      }
-    done
-  fi
-fi
-
-echo "✅ All checks passed"
-`;
+${PRE_COMMIT_SNIPPET}`;
     await fs.writeFile(preCommitPath, preCommitContent, 'utf-8');
     await fs.chmod(preCommitPath, 0o755);
-    console.log(chalk.green(`✅ 已创建 .git/hooks/pre-commit`));
+    log(io, chalk.green(`✅ 已创建 .git/hooks/pre-commit`));
   }
 }
 
 /**
  * 设置 GitHub Actions
  */
-async function setupGitHubActions(projectPath: string): Promise<void> {
+async function setupGitHubActions(projectPath: string, io: CommandIO): Promise<void> {
   const workflowsDir = path.join(projectPath, '.github', 'workflows');
   const workflowPath = path.join(workflowsDir, 'harness-check.yml');
 
@@ -360,13 +337,13 @@ async function setupGitHubActions(projectPath: string): Promise<void> {
   
   if (existingFiles.length > 0) {
     // 已有 CI 配置，输出代码片段
-    console.log(chalk.yellow('⚠️  检测到已存在的 CI 配置：'));
+    log(io, chalk.yellow('⚠️  检测到已存在的 CI 配置：'));
     existingFiles.forEach(f => {
-      console.log(chalk.gray(`  - .github/workflows/${f}`));
+      log(io, chalk.gray(`  - .github/workflows/${f}`));
     });
-    console.log(chalk.gray('💡 请手动添加以下内容到 jobs 中：'));
-    console.log();
-    console.log(chalk.cyan(GITHUB_ACTIONS_SNIPPET));
+    log(io, chalk.gray('💡 请手动添加以下内容到 jobs 中：'));
+    log(io);
+    log(io, chalk.cyan(GITHUB_ACTIONS_SNIPPET));
     return;
   }
 
@@ -406,7 +383,7 @@ jobs:
 `;
 
   await fs.writeFile(workflowPath, workflowContent, 'utf-8');
-  console.log(chalk.green(`✅ 已创建 .github/workflows/harness-check.yml`));
+  log(io, chalk.green(`✅ 已创建 .github/workflows/harness-check.yml`));
 }
 
 /**
@@ -428,14 +405,14 @@ async function findCiWorkflows(workflowsDir: string): Promise<string[]> {
 /**
  * 创建自定义约束示例
  */
-async function createCustomConstraintsExample(projectPath: string): Promise<void> {
+async function createCustomConstraintsExample(projectPath: string, io: CommandIO): Promise<void> {
   const configDir = path.join(projectPath, '.harness');
   const customConstraintsPath = path.join(configDir, 'custom-constraints.yml');
 
   // 如果已存在，不覆盖
   try {
     await fs.access(customConstraintsPath);
-    console.log(chalk.gray(`custom-constraints.yml 已存在`));
+    log(io, chalk.gray(`custom-constraints.yml 已存在`));
     return;
   } catch {
     // 文件不存在，创建
@@ -477,7 +454,7 @@ custom_constraints:
 `;
 
   await fs.writeFile(customConstraintsPath, content, 'utf-8');
-  console.log(chalk.green(`✅ 已创建自定义约束示例: custom-constraints.yml`));
+  log(io, chalk.green(`✅ 已创建自定义约束示例: custom-constraints.yml`));
 }
 
 /**
@@ -513,7 +490,7 @@ function renderOutputStyleSection(): string {
  * - 无标记且 `## Output Style` 段为用户自写（特征串不匹配）：跳过并提示，不重复追加
  * - 完全没有该段：在文件顶部插入标记版
  */
-export async function setupClaudeMdOutputStyle(projectPath: string): Promise<void> {
+export async function setupClaudeMdOutputStyle(projectPath: string, io: CommandIO = processIO): Promise<void> {
   const claudeMdPath = path.join(projectPath, 'CLAUDE.md');
   let content: string;
   try {
@@ -524,20 +501,20 @@ export async function setupClaudeMdOutputStyle(projectPath: string): Promise<voi
   }
 
   const section = renderOutputStyleSection();
-  const startIdx = content.indexOf(OUTPUT_STYLE_START);
-  const endIdx = content.indexOf(OUTPUT_STYLE_END);
-
-  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
-    // 替换标记间内容（标记本身也替换，保持最新文本）。
-    // 尾部换行规范化：标记后恰好保留一个换行分隔，保证重复运行幂等。
-    const after = content.slice(endIdx + OUTPUT_STYLE_END.length).replace(/^\n+/, '');
-    const newContent = content.slice(0, startIdx) + section + (after ? '\n' + after : '');
-    if (newContent !== content) {
-      await fs.writeFile(claudeMdPath, newContent, 'utf-8');
-      console.log(chalk.green('✅ 已更新 CLAUDE.md Output Style 段'));
+  const write = replaceStandaloneRange(content, OUTPUT_STYLE_START, OUTPUT_STYLE_END, section);
+
+  if (write.kind === 'updated') {
+    // 尾部换行规范化在 writer 内（幂等）。
+    if (write.content !== content) {
+      await fs.writeFile(claudeMdPath, write.content, 'utf-8');
+      log(io, chalk.green('✅ 已更新 CLAUDE.md Output Style 段'));
     }
     return;
   }
+  if (write.kind === 'half') {
+    log(io, chalk.yellow('⚠️  CLAUDE.md 中 HARNESS_OUTPUT_STYLE 标记残缺（单边或乱序），跳过 Output Style 注入，请人工修复'));
+    return;
+  }
 
   // 检测旧版无标记 `## Output Style` 段
   const legacyMatch = /^## Output Style[ \t]*$/m.exec(content);
@@ -550,7 +527,7 @@ export async function setupClaudeMdOutputStyle(projectPath: string): Promise<voi
 
     if (!legacySection.includes(LEGACY_OUTPUT_STYLE_FINGERPRINT)) {
       // 用户自写的同名 section：不动，也不追加（避免重复）
-      console.log(chalk.yellow('⚠️  CLAUDE.md 已存在自定义 "## Output Style" 段，跳过 harness Output Style 注入'));
+      log(io, chalk.yellow('⚠️  CLAUDE.md 已存在自定义 "## Output Style" 段，跳过 harness Output Style 注入'));
       return;
     }
 
@@ -559,13 +536,13 @@ export async function setupClaudeMdOutputStyle(projectPath: string): Promise<voi
     const after = content.slice(sectionEnd);
     const newContent = before + section + (after.length > 0 ? '\n' + after : '');
     await fs.writeFile(claudeMdPath, newContent, 'utf-8');
-    console.log(chalk.green('✅ 已将 CLAUDE.md Output Style 段迁移为标记化管理'));
+    log(io, chalk.green('✅ 已将 CLAUDE.md Output Style 段迁移为标记化管理'));
     return;
   }
 
   // 完全没有该段：插入文件顶部
   await fs.writeFile(claudeMdPath, section + '\n' + content, 'utf-8');
-  console.log(chalk.green('✅ 已在 CLAUDE.md 顶部写入 Output Style 段'));
+  log(io, chalk.green('✅ 已在 CLAUDE.md 顶部写入 Output Style 段'));
 }
 
 /**
@@ -584,15 +561,15 @@ const GOVERNANCE_PRESERVE_END = '<!-- /PRESERVE:governance -->';
  *   有标记则只替换标记区间，段内其余手写内容（治理契约引言/流程/纪律等）原样保留；
  *   无标记（纯手写段）则在段尾追加注入段，不动手写内容
  * - 无该段：在文件末尾追加
- * - 段标记残缺（只有单边标记）：不写入，告警交由人工修复（防二次损坏）
+ * - 段标记残缺（外层或段内 HARNESS_CONSTRAINTS 单边/乱序）：不写入，告警交由人工修复（防二次损坏）
  */
-export async function setupAgentsMdConstraints(projectPath: string): Promise<void> {
+export async function setupAgentsMdConstraints(projectPath: string, io: CommandIO = processIO): Promise<void> {
   const agentsMdPath = path.join(projectPath, 'AGENTS.md');
-  const version = getPackageVersion();
+  const version = getHarnessPackageVersion();
 
   const constraints = getEffectiveConstraints(projectPath);
   const bodyOnly = renderConstraintsSection(constraints, version);
-  const block = `${GOVERNANCE_PRESERVE_BEGIN}\n## Governance Rules\n${bodyOnly}${GOVERNANCE_PRESERVE_END}\n`;
+  const block = `${GOVERNANCE_PRESERVE_BEGIN}\n${GOVERNANCE_HEADING}\n${bodyOnly}${GOVERNANCE_PRESERVE_END}\n`;
 
   let existingContent: string | null = null;
   try {
@@ -610,57 +587,47 @@ export async function setupAgentsMdConstraints(projectPath: string): Promise<voi
       block,
     ].join('\n');
     await fs.writeFile(agentsMdPath, skeleton, 'utf-8');
-    console.log(chalk.green(`✅ 已创建 AGENTS.md 并写入治理契约 PRESERVE:governance 段 (v${version})`));
+    log(io, chalk.green(`✅ 已创建 AGENTS.md 并写入治理契约 PRESERVE:governance 段 (v${version})`));
     return;
   }
 
-  const startIdx = existingContent.indexOf(GOVERNANCE_PRESERVE_BEGIN);
-  const endIdx = existingContent.indexOf(GOVERNANCE_PRESERVE_END);
+  const preserve = cutMarkerBlock(existingContent, GOVERNANCE_PRESERVE_BEGIN, GOVERNANCE_PRESERVE_END);
 
-  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
-    // 段内机器管理的只有 HARNESS_CONSTRAINTS 标记区间；其余手写内容原样保留
-    const before = existingContent.slice(0, startIdx);
-    const blockContent = existingContent.slice(startIdx + GOVERNANCE_PRESERVE_BEGIN.length, endIdx);
-    const after = existingContent.slice(endIdx + GOVERNANCE_PRESERVE_END.length).replace(/^\n+/, '');
-
-    const csIdx = blockContent.indexOf(CONSTRAINTS_START_MARKER);
-    const ceIdx = blockContent.indexOf(CONSTRAINTS_END_MARKER);
-    let newBlockContent: string;
-    if (csIdx !== -1 && ceIdx !== -1 && ceIdx > csIdx) {
-      // 只替换标记区间。bodyOnly 自带结尾换行，故剥掉尾部恰好一个前导换行
-      // （END 标记行的行尾换行），其余手写内容逐字保留，保证幂等。
-      newBlockContent =
-        blockContent.slice(0, csIdx) +
-        bodyOnly +
-        blockContent.slice(ceIdx + CONSTRAINTS_END_MARKER.length).replace(/^\n/, '');
-    } else {
-      // 纯手写段（无约束标记）：段尾追加注入段，手写内容不动
-      newBlockContent = blockContent.trimEnd() + '\n\n## Governance Rules\n' + bodyOnly;
-    }
-
-    const newContent =
-      before +
-      GOVERNANCE_PRESERVE_BEGIN +
-      newBlockContent +
-      GOVERNANCE_PRESERVE_END +
-      '\n' +
-      (after ? '\n' + after : '');
-    if (newContent !== existingContent) {
-      await fs.writeFile(agentsMdPath, newContent, 'utf-8');
-      console.log(chalk.green(`✅ 已更新 AGENTS.md 治理契约 PRESERVE:governance 段 (v${version})`));
-    }
+  if (preserve === 'half') {
+    log(io, chalk.yellow('⚠️  AGENTS.md 中 PRESERVE:governance 标记残缺（只有单边），跳过治理契约写入，请人工修复'));
     return;
   }
 
-  if (startIdx !== -1 || endIdx !== -1) {
-    console.log(chalk.yellow('⚠️  AGENTS.md 中 PRESERVE:governance 标记残缺（只有单边），跳过治理契约写入，请人工修复'));
+  if (preserve !== 'absent') {
+    // 段内机器管理的只有 HARNESS_CONSTRAINTS 标记区间；其余手写内容原样保留
+    const inner = replaceEnclosedRange(preserve.inner, CONSTRAINTS_START_MARKER, CONSTRAINTS_END_MARKER, bodyOnly);
+    if (inner.kind === 'half') {
+      log(io, chalk.yellow('⚠️  AGENTS.md PRESERVE:governance 段内 HARNESS_CONSTRAINTS 标记残缺（单边或乱序），跳过治理契约写入，请人工修复'));
+      return;
+    }
+    const newInner =
+      inner.kind === 'updated'
+        ? inner.content
+        : // 纯手写段（无约束标记）：段尾追加注入段，手写内容不动
+          preserve.inner.trimEnd() + '\n\n' + GOVERNANCE_HEADING + '\n' + bodyOnly;
+
+    const write = replaceStandaloneRange(
+      existingContent,
+      GOVERNANCE_PRESERVE_BEGIN,
+      GOVERNANCE_PRESERVE_END,
+      GOVERNANCE_PRESERVE_BEGIN + newInner + GOVERNANCE_PRESERVE_END + '\n'
+    );
+    if (write.kind === 'updated' && write.content !== existingContent) {
+      await fs.writeFile(agentsMdPath, write.content, 'utf-8');
+      log(io, chalk.green(`✅ 已更新 AGENTS.md 治理契约 PRESERVE:governance 段 (v${version})`));
+    }
     return;
   }
 
   // 无该段：文件末尾追加
   const newContent = existingContent.trimEnd() + '\n\n' + block;
   await fs.writeFile(agentsMdPath, newContent, 'utf-8');
-  console.log(chalk.green(`✅ 已追加治理契约 PRESERVE:governance 段到 AGENTS.md (v${version})`));
+  log(io, chalk.green(`✅ 已追加治理契约 PRESERVE:governance 段到 AGENTS.md (v${version})`));
 }
 
 /**
@@ -673,23 +640,15 @@ export async function setupAgentsMdConstraints(projectPath: string): Promise<voi
  * - 如果存在 HARNESS_CONSTRAINTS_START/END 标记，替换标记间内容
  * - 如果不存在标记，在文件末尾追加约束段
  */
-export async function setupClaudeMdConstraints(projectPath: string): Promise<void> {
+export async function setupClaudeMdConstraints(projectPath: string, io: CommandIO = processIO): Promise<void> {
   const claudeMdPath = path.join(projectPath, 'CLAUDE.md');
 
-  // 读取 harness 版本
-  let version = 'unknown';
-  try {
-    const pkgPath = path.join(__dirname, '../../../package.json');
-    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-    version = pkg.version;
-  } catch {
-    // fallback to 'unknown'
-  }
+  const version = getHarnessPackageVersion();
 
   // 生效约束集 → 渲染期望段（纯函数，与写文件分离）
   const constraints = getEffectiveConstraints(projectPath);
   const bodyOnly = renderConstraintsSection(constraints, version);
-  const fullSection = '## Governance Rules\n' + bodyOnly;
+  const fullSection = GOVERNANCE_HEADING + '\n' + bodyOnly;
 
   // 检查 CLAUDE.md 是否存在
   let existingContent: string;
@@ -704,65 +663,53 @@ export async function setupClaudeMdConstraints(projectPath: string): Promise<voi
   if (!fileExists) {
     // 创建新文件
     await fs.writeFile(claudeMdPath, fullSection, 'utf-8');
-    console.log(chalk.green(`✅ 已创建 CLAUDE.md 并写入治理约束 (v${version})`));
+    log(io, chalk.green(`✅ 已创建 CLAUDE.md 并写入治理约束 (v${version})`));
     return;
   }
 
-  const startIdx = existingContent.indexOf(CONSTRAINTS_START_MARKER);
-  const endIdx = existingContent.indexOf(CONSTRAINTS_END_MARKER);
+  const write = replaceStandaloneRange(existingContent, CONSTRAINTS_START_MARKER, CONSTRAINTS_END_MARKER, bodyOnly);
 
-  if (startIdx !== -1 && endIdx !== -1) {
-    // 替换标记间内容（标记本身也替换，保持包括最新版本号）。
-    // 尾部换行规范化：标记后恰好保留一个换行分隔，保证重复运行幂等。
-    const before = existingContent.slice(0, startIdx);
-    const after = existingContent.slice(endIdx + CONSTRAINTS_END_MARKER.length).replace(/^\n+/, '');
-    const newContent = before + bodyOnly + (after ? '\n' + after : '');
-    await fs.writeFile(claudeMdPath, newContent, 'utf-8');
-    console.log(chalk.green(`✅ 已更新 CLAUDE.md 治理约束 (v${version})`));
+  if (write.kind === 'updated') {
+    // 替换标记区间含标记本身（保持包括最新版本号），尾部换行规范化在 writer 内
+    await fs.writeFile(claudeMdPath, write.content, 'utf-8');
+    log(io, chalk.green(`✅ 已更新 CLAUDE.md 治理约束 (v${version})`));
+  } else if (write.kind === 'half') {
+    log(io, chalk.yellow('⚠️  CLAUDE.md 中 HARNESS_CONSTRAINTS 标记残缺（单边或乱序），跳过治理约束注入，请人工修复'));
   } else {
     // 在文件末尾追加完整段
     const newContent = existingContent.trimEnd() + '\n\n' + fullSection;
     await fs.writeFile(claudeMdPath, newContent, 'utf-8');
-    console.log(chalk.green(`✅ 已追加治理约束到 CLAUDE.md (v${version})`));
+    log(io, chalk.green(`✅ 已追加治理约束到 CLAUDE.md (v${version})`));
   }
 }
 
 /**
  * 治理约束段写入落点路由（studio #302，ADR 2026-08-21 落点模型）
  *
+ * 判定收口在 core/constraints/injection-writer resolveGovernanceLanding：
  * - 旧模型仓（CLAUDE.md 已有 HARNESS_CONSTRAINTS 标记或 `## Governance Rules` 块）：
  *   继续写 CLAUDE.md——init 幂等重跑不破坏既有仓，不制造双份约束正本
  * - 其余（新仓初始化）：写 AGENTS.md PRESERVE:governance 段（入库公共面正本）
  */
 export async function setupGovernanceConstraints(projectPath: string): Promise<void> {
-  let claudeContent: string | null = null;
-  try {
-    claudeContent = await fs.readFile(path.join(projectPath, 'CLAUDE.md'), 'utf-8');
-  } catch {
-    // CLAUDE.md 不存在 → 新仓
-  }
-
-  if (
-    claudeContent !== null &&
-    (claudeContent.includes(CONSTRAINTS_START_MARKER) || /^##\s+Governance Rules/m.test(claudeContent))
-  ) {
-    return setupClaudeMdConstraints(projectPath);
-  }
-  return setupAgentsMdConstraints(projectPath);
+  const { target } = resolveGovernanceLanding(projectPath);
+  return target === 'claude-md'
+    ? setupClaudeMdConstraints(projectPath)
+    : setupAgentsMdConstraints(projectPath);
 }
 
 /**
  * 设置治理相关文件
  */
-async function setupGovernance(projectPath: string, level: string): Promise<void> {
-  const governance = GOVERNANCE_PRESETS[level] as Record<string, unknown>;
+async function setupGovernance(projectPath: string, level: string, io: CommandIO): Promise<void> {
+  const governance = GOVERNANCE_PRESETS[level];
   if (!governance) return;
 
-  console.log();
-  console.log(chalk.blue('📋 设置治理文件...'));
+  log(io);
+  log(io, chalk.blue('📋 设置治理文件...'));
 
   // 1. 生成 CHANGELOG.md
-  await createChangelog(projectPath, governance);
+  await createChangelog(projectPath, governance, io);
 
   // 2. 在 CLAUDE.md 中写入 Output Style 段（仅在不存在时创建）
   await setupClaudeMdOutputStyle(projectPath);
@@ -771,38 +718,37 @@ async function setupGovernance(projectPath: string, level: string): Promise<void
   //    旧模型仓 → CLAUDE.md，落点路由见 setupGovernanceConstraints）
   await setupGovernanceConstraints(projectPath);
 
-  // 4. 生成 CONTEXT.md 文件
-  const contextConfig = governance.context_files as Record<string, unknown> | undefined;
+  // 4. 生成 CONTEXT.md 文件（预设形状即 GovernanceConfig，无需再 cast）
+  const contextConfig = governance.context_files;
   if (contextConfig?.enabled) {
-    let requiredDirs = (contextConfig.required_dirs as string[]) || [];
+    let requiredDirs = contextConfig.required_dirs ?? [];
     if (requiredDirs.length === 0) {
       requiredDirs = detectSourceRoots(projectPath);
     }
     for (const dir of requiredDirs) {
-      await createContextMd(projectPath, dir);
+      await createContextMd(projectPath, dir, io);
     }
   }
 
   // 4. 生成治理 CI workflow
-  await setupGovernanceWorkflow(projectPath, level);
+  await setupGovernanceWorkflow(projectPath, level, io);
 }
 
 /**
  * 创建 CHANGELOG.md
  */
-async function createChangelog(projectPath: string, governance: Record<string, unknown>): Promise<void> {
+async function createChangelog(projectPath: string, governance: GovernanceConfig, io: CommandIO): Promise<void> {
   const changelogPath = path.join(projectPath, 'CHANGELOG.md');
 
   try {
     await fs.access(changelogPath);
-    console.log(chalk.gray(`CHANGELOG.md 已存在`));
+    log(io, chalk.gray(`CHANGELOG.md 已存在`));
     return;
   } catch {
     // 文件不存在，创建
   }
 
-  const changelogConfig = governance.changelog as Record<string, unknown> | undefined;
-  const format = (changelogConfig?.format as string) || 'keep-a-changelog';
+  const format = governance.changelog?.format || 'keep-a-changelog';
 
   let content: string;
   if (format === 'keep-a-changelog') {
@@ -836,18 +782,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   }
 
   await fs.writeFile(changelogPath, content, 'utf-8');
-  console.log(chalk.green(`✅ 已创建 CHANGELOG.md`));
+  log(io, chalk.green(`✅ 已创建 CHANGELOG.md`));
 }
 
 /**
  * 在指定目录创建 CONTEXT.md
  */
-async function createContextMd(projectPath: string, dir: string): Promise<void> {
+async function createContextMd(projectPath: string, dir: string, io: CommandIO): Promise<void> {
   const contextPath = path.join(projectPath, dir, 'CONTEXT.md');
 
   try {
     await fs.access(contextPath);
-    console.log(chalk.gray(`${dir}/CONTEXT.md 已存在`));
+    log(io, chalk.gray(`${dir}/CONTEXT.md 已存在`));
     return;
   } catch {
     // 文件不存在，创建
@@ -858,7 +804,7 @@ async function createContextMd(projectPath: string, dir: string): Promise<void>
   try {
     await fs.access(dirPath);
   } catch {
-    console.log(chalk.yellow(`⚠️  目录 ${dir} 不存在，跳过 CONTEXT.md`));
+    log(io, chalk.yellow(`⚠️  目录 ${dir} 不存在，跳过 CONTEXT.md`));
     return;
   }
 
@@ -885,7 +831,7 @@ async function createContextMd(projectPath: string, dir: string): Promise<void>
 `;
 
   await fs.writeFile(contextPath, content, 'utf-8');
-  console.log(chalk.green(`✅ 已创建 ${dir}/CONTEXT.md`));
+  log(io, chalk.green(`✅ 已创建 ${dir}/CONTEXT.md`));
 }
 
 /**
@@ -911,14 +857,14 @@ async function findGovernanceCoverage(workflowsDir: string): Promise<string | un
 /**
  * 设置治理 CI workflow
  */
-async function setupGovernanceWorkflow(projectPath: string, level: string): Promise<void> {
+async function setupGovernanceWorkflow(projectPath: string, level: string, io: CommandIO): Promise<void> {
   const workflowsDir = path.join(projectPath, '.github', 'workflows');
   const workflowPath = path.join(workflowsDir, 'harness-governance.yml');
 
   // 检查是否已存在
   try {
     await fs.access(workflowPath);
-    console.log(chalk.gray(`harness-governance.yml 已存在`));
+    log(io, chalk.gray(`harness-governance.yml 已存在`));
     return;
   } catch {
     // 不存在，继续创建
@@ -927,7 +873,7 @@ async function setupGovernanceWorkflow(projectPath: string, level: string): Prom
   // 能力检测：已有 workflow 已跑 harness 治理命令时跳过，避免重复 CI 面
   const coveredBy = await findGovernanceCoverage(workflowsDir);
   if (coveredBy) {
-    console.log(chalk.gray(`治理检查已由 ${coveredBy} 覆盖，跳过创建 harness-governance.yml`));
+    log(io, chalk.gray(`治理检查已由 ${coveredBy} 覆盖，跳过创建 harness-governance.yml`));
     return;
   }
 
@@ -972,5 +918,5 @@ ${docsCheckStep}
 `;
 
   await fs.writeFile(workflowPath, workflowContent, 'utf-8');
-  console.log(chalk.green(`✅ 已创建 .github/workflows/harness-governance.yml`));
+  log(io, chalk.green(`✅ 已创建 .github/workflows/harness-governance.yml`));
 }