@dommaker/harness 1.3.0 → 1.5.0

package/dist/cli/commands/init.js

@@ -47,14 +47,16 @@ exports.setupAgentsMdConstraints = setupAgentsMdConstraints;
 exports.setupClaudeMdConstraints = setupClaudeMdConstraints;
 exports.setupGovernanceConstraints = setupGovernanceConstraints;
 const chalk_1 = __importDefault(require("chalk"));
-const fs_1 = require("fs");
 const fs = __importStar(require("fs/promises"));
 const path = __importStar(require("path"));
 const yaml = __importStar(require("js-yaml"));
 const validate_1 = require("./validate");
 const detect_source_roots_1 = require("../../utils/detect-source-roots");
+const package_version_1 = require("../../utils/package-version");
 const effective_constraints_1 = require("../../core/effective-constraints");
 const injection_renderer_1 = require("../../core/constraints/injection-renderer");
+const injection_writer_1 = require("../../core/constraints/injection-writer");
+const command_contract_1 = require("../command-contract");
 /**
  * 默认配置
  *
@@ -85,7 +87,7 @@ const PRESETS = {
     },
 };
 /**
- * 治理预设
+ * 治理预设（形状 = 写入 config.yml 的 governance 段，直接用类型正本）
  */
 const GOVERNANCE_PRESETS = {
     minimal: {
@@ -152,97 +154,91 @@ const GOVERNANCE_PRESETS = {
 /**
  * 初始化项目
  */
-async function init(options) {
+async function init(options, io = command_contract_1.processIO) {
     // 只输出代码片段
     if (options.printSnippets) {
-        printSnippets();
-        return;
+        printSnippets(io);
+        return { kind: 'ok' };
     }
-    console.log(chalk_1.default.blue('🚀 初始化 harness 配置...'));
+    (0, command_contract_1.log)(io, chalk_1.default.blue('🚀 初始化 harness 配置...'));
     const projectPath = options.projectPath || process.cwd();
     const configDir = path.join(projectPath, '.harness');
     // 创建配置目录
     await fs.mkdir(configDir, { recursive: true });
-    console.log(chalk_1.default.gray(`配置目录: ${configDir}`));
+    (0, command_contract_1.log)(io, chalk_1.default.gray(`配置目录: ${configDir}`));
     // 选择预设
     const preset = PRESETS[options.preset];
-    console.log(chalk_1.default.gray(`预设: ${options.preset}`));
+    (0, command_contract_1.log)(io, chalk_1.default.gray(`预设: ${options.preset}`));
     // 合并治理配置
     const configData = { ...preset };
     if (options.governance) {
         configData.governance = GOVERNANCE_PRESETS[options.governance];
-        console.log(chalk_1.default.gray(`治理级别: ${options.governance}`));
+        (0, command_contract_1.log)(io, chalk_1.default.gray(`治理级别: ${options.governance}`));
     }
     // 写入 harness 版本
-    const pkgVersion = getPackageVersion();
+    const pkgVersion = (0, package_version_1.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_1.default.green(`✅ 已创建配置文件: ${configPath} (v${pkgVersion})`));
+    (0, command_contract_1.log)(io, chalk_1.default.green(`✅ 已创建配置文件: ${configPath} (v${pkgVersion})`));
     // 创建检查点示例
-    await (0, validate_1.createExampleCheckpoint)(projectPath);
+    await (0, validate_1.createExampleCheckpoint)(projectPath, io);
     // 创建 Resolutions（RKB 狗粮 — 约束 → 已知解法映射）
-    await (0, validate_1.createExampleResolutions)(projectPath);
+    await (0, validate_1.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_1.default.green('✅ harness 初始化完成！'));
-    console.log();
-    console.log(chalk_1.default.gray('下一步:'));
-    console.log(chalk_1.default.gray('  1. 编辑 .harness/config.yml 自定义配置'));
-    console.log(chalk_1.default.gray('  2. 编辑 .harness/custom-constraints.yml 添加项目约束'));
-    console.log(chalk_1.default.gray('  3. 正常开发，每次 git commit 会自动检查约束'));
-    console.log(chalk_1.default.gray('  4. 运行 harness status 查看状态'));
-    console.log();
-    console.log(chalk_1.default.blue('💡 提示: 使用 harness init --print-snippets 查看配置代码片段'));
-}
-/**
- * 获取 harness 包版本
- */
-function getPackageVersion() {
-    try {
-        // eslint-disable-next-line @typescript-eslint/no-var-requires
-        return require('../../../package.json').version;
-    }
-    catch {
-        return 'unknown';
-    }
+        await setupGovernance(projectPath, options.governance, io);
+    }
+    (0, command_contract_1.log)(io);
+    (0, command_contract_1.log)(io, chalk_1.default.green('✅ harness 初始化完成！'));
+    (0, command_contract_1.log)(io);
+    (0, command_contract_1.log)(io, chalk_1.default.gray('下一步:'));
+    (0, command_contract_1.log)(io, chalk_1.default.gray('  1. 编辑 .harness/config.yml 自定义配置'));
+    (0, command_contract_1.log)(io, chalk_1.default.gray('  2. 编辑 .harness/custom-constraints.yml 添加项目约束'));
+    (0, command_contract_1.log)(io, chalk_1.default.gray('  3. 正常开发，每次 git commit 会自动检查约束'));
+    (0, command_contract_1.log)(io, chalk_1.default.gray('  4. 运行 harness status 查看状态'));
+    (0, command_contract_1.log)(io);
+    (0, command_contract_1.log)(io, chalk_1.default.blue('💡 提示: 使用 harness init --print-snippets 查看配置代码片段'));
+    return { kind: 'ok' };
 }
 /**
  * 输出代码片段
  */
-function printSnippets() {
-    console.log(chalk_1.default.blue('📄 Harness 配置代码片段'));
-    console.log();
-    console.log(chalk_1.default.yellow('Git pre-commit hook:'));
-    console.log(chalk_1.default.gray('添加到 .git/hooks/pre-commit'));
-    console.log();
-    console.log(chalk_1.default.cyan(PRE_COMMIT_SNIPPET));
-    console.log(chalk_1.default.yellow('GitHub Actions:'));
-    console.log(chalk_1.default.gray('添加到 .github/workflows/*.yml 的 jobs 中'));
-    console.log();
-    console.log(chalk_1.default.cyan(GITHUB_ACTIONS_SNIPPET));
-    console.log(chalk_1.default.blue('💡 提示: 运行 npx @dommaker/harness init 自动创建配置文件'));
+function printSnippets(io) {
+    (0, command_contract_1.log)(io, chalk_1.default.blue('📄 Harness 配置代码片段'));
+    (0, command_contract_1.log)(io);
+    (0, command_contract_1.log)(io, chalk_1.default.yellow('Git pre-commit hook:'));
+    (0, command_contract_1.log)(io, chalk_1.default.gray('添加到 .git/hooks/pre-commit'));
+    (0, command_contract_1.log)(io);
+    (0, command_contract_1.log)(io, chalk_1.default.cyan(PRE_COMMIT_SNIPPET));
+    (0, command_contract_1.log)(io, chalk_1.default.yellow('GitHub Actions:'));
+    (0, command_contract_1.log)(io, chalk_1.default.gray('添加到 .github/workflows/*.yml 的 jobs 中'));
+    (0, command_contract_1.log)(io);
+    (0, command_contract_1.log)(io, chalk_1.default.cyan(GITHUB_ACTIONS_SNIPPET));
+    (0, command_contract_1.log)(io, chalk_1.default.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
@@ -251,7 +247,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
@@ -264,6 +259,8 @@ if command -v npx > /dev/null 2>&1; then
     done
   fi
 fi
+
+echo "✅ All checks passed"
 `;
 /**
  * GitHub Actions 代码片段
@@ -282,7 +279,7 @@ const GITHUB_ACTIONS_SNIPPET = `
 /**
  * 设置 Git hooks
  */
-async function setupGitHooks(projectPath) {
+async function setupGitHooks(projectPath, io) {
     const gitDir = path.join(projectPath, '.git');
     const hooksDir = path.join(gitDir, 'hooks');
     const preCommitPath = path.join(hooksDir, 'pre-commit');
@@ -290,8 +287,8 @@ async function setupGitHooks(projectPath) {
         await fs.access(gitDir);
     }
     catch {
-        console.log(chalk_1.default.yellow('⚠️  未检测到 Git 仓库，跳过 Git hooks'));
-        console.log(chalk_1.default.gray('💡 初始化 Git 后可运行 npx @dommaker/harness init --print-snippets 查看配置'));
+        (0, command_contract_1.log)(io, chalk_1.default.yellow('⚠️  未检测到 Git 仓库，跳过 Git hooks'));
+        (0, command_contract_1.log)(io, chalk_1.default.gray('💡 初始化 Git 后可运行 npx @dommaker/harness init --print-snippets 查看配置'));
         return;
     }
     await fs.mkdir(hooksDir, { recursive: true });
@@ -299,65 +296,38 @@ async function setupGitHooks(projectPath) {
     try {
         await fs.access(preCommitPath);
         // 已存在，输出代码片段
-        console.log(chalk_1.default.yellow('⚠️  .git/hooks/pre-commit 已存在'));
-        console.log(chalk_1.default.gray('💡 请手动添加以下内容到文件末尾：'));
-        console.log();
-        console.log(chalk_1.default.cyan(PRE_COMMIT_SNIPPET));
+        (0, command_contract_1.log)(io, chalk_1.default.yellow('⚠️  .git/hooks/pre-commit 已存在'));
+        (0, command_contract_1.log)(io, chalk_1.default.gray('💡 请手动添加以下内容到文件末尾：'));
+        (0, command_contract_1.log)(io);
+        (0, command_contract_1.log)(io, chalk_1.default.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_1.default.green(`✅ 已创建 .git/hooks/pre-commit`));
+        (0, command_contract_1.log)(io, chalk_1.default.green(`✅ 已创建 .git/hooks/pre-commit`));
     }
 }
 /**
  * 设置 GitHub Actions
  */
-async function setupGitHubActions(projectPath) {
+async function setupGitHubActions(projectPath, io) {
     const workflowsDir = path.join(projectPath, '.github', 'workflows');
     const workflowPath = path.join(workflowsDir, 'harness-check.yml');
     // 检查是否已有 CI 配置
     const existingFiles = await findCiWorkflows(workflowsDir);
     if (existingFiles.length > 0) {
         // 已有 CI 配置，输出代码片段
-        console.log(chalk_1.default.yellow('⚠️  检测到已存在的 CI 配置：'));
+        (0, command_contract_1.log)(io, chalk_1.default.yellow('⚠️  检测到已存在的 CI 配置：'));
         existingFiles.forEach(f => {
-            console.log(chalk_1.default.gray(`  - .github/workflows/${f}`));
+            (0, command_contract_1.log)(io, chalk_1.default.gray(`  - .github/workflows/${f}`));
         });
-        console.log(chalk_1.default.gray('💡 请手动添加以下内容到 jobs 中：'));
-        console.log();
-        console.log(chalk_1.default.cyan(GITHUB_ACTIONS_SNIPPET));
+        (0, command_contract_1.log)(io, chalk_1.default.gray('💡 请手动添加以下内容到 jobs 中：'));
+        (0, command_contract_1.log)(io);
+        (0, command_contract_1.log)(io, chalk_1.default.cyan(GITHUB_ACTIONS_SNIPPET));
         return;
     }
     // 没有现有 CI 配置，创建文件
@@ -395,7 +365,7 @@ jobs:
         run: npx @dommaker/harness passes-gate
 `;
     await fs.writeFile(workflowPath, workflowContent, 'utf-8');
-    console.log(chalk_1.default.green(`✅ 已创建 .github/workflows/harness-check.yml`));
+    (0, command_contract_1.log)(io, chalk_1.default.green(`✅ 已创建 .github/workflows/harness-check.yml`));
 }
 /**
  * 查找已存在的 CI 工作流文件
@@ -414,13 +384,13 @@ async function findCiWorkflows(workflowsDir) {
 /**
  * 创建自定义约束示例
  */
-async function createCustomConstraintsExample(projectPath) {
+async function createCustomConstraintsExample(projectPath, io) {
     const configDir = path.join(projectPath, '.harness');
     const customConstraintsPath = path.join(configDir, 'custom-constraints.yml');
     // 如果已存在，不覆盖
     try {
         await fs.access(customConstraintsPath);
-        console.log(chalk_1.default.gray(`custom-constraints.yml 已存在`));
+        (0, command_contract_1.log)(io, chalk_1.default.gray(`custom-constraints.yml 已存在`));
         return;
     }
     catch {
@@ -461,7 +431,7 @@ custom_constraints:
   #   trigger: ["file_creation"]
 `;
     await fs.writeFile(customConstraintsPath, content, 'utf-8');
-    console.log(chalk_1.default.green(`✅ 已创建自定义约束示例: custom-constraints.yml`));
+    (0, command_contract_1.log)(io, chalk_1.default.green(`✅ 已创建自定义约束示例: custom-constraints.yml`));
 }
 /**
  * Output Style 段标记（ADR-0001：init 只写标记区间内，标记外只读）
@@ -492,7 +462,7 @@ function renderOutputStyleSection() {
  * - 无标记且 `## Output Style` 段为用户自写（特征串不匹配）：跳过并提示，不重复追加
  * - 完全没有该段：在文件顶部插入标记版
  */
-async function setupClaudeMdOutputStyle(projectPath) {
+async function setupClaudeMdOutputStyle(projectPath, io = command_contract_1.processIO) {
     const claudeMdPath = path.join(projectPath, 'CLAUDE.md');
     let content;
     try {
@@ -503,19 +473,19 @@ async function setupClaudeMdOutputStyle(projectPath) {
         return;
     }
     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_1.default.green('✅ 已更新 CLAUDE.md Output Style 段'));
+    const write = (0, injection_writer_1.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');
+            (0, command_contract_1.log)(io, chalk_1.default.green('✅ 已更新 CLAUDE.md Output Style 段'));
         }
         return;
     }
+    if (write.kind === 'half') {
+        (0, command_contract_1.log)(io, chalk_1.default.yellow('⚠️  CLAUDE.md 中 HARNESS_OUTPUT_STYLE 标记残缺（单边或乱序），跳过 Output Style 注入，请人工修复'));
+        return;
+    }
     // 检测旧版无标记 `## Output Style` 段
     const legacyMatch = /^## Output Style[ \t]*$/m.exec(content);
     if (legacyMatch) {
@@ -526,7 +496,7 @@ async function setupClaudeMdOutputStyle(projectPath) {
         const legacySection = content.slice(sectionStart, sectionEnd);
         if (!legacySection.includes(LEGACY_OUTPUT_STYLE_FINGERPRINT)) {
             // 用户自写的同名 section：不动，也不追加（避免重复）
-            console.log(chalk_1.default.yellow('⚠️  CLAUDE.md 已存在自定义 "## Output Style" 段，跳过 harness Output Style 注入'));
+            (0, command_contract_1.log)(io, chalk_1.default.yellow('⚠️  CLAUDE.md 已存在自定义 "## Output Style" 段，跳过 harness Output Style 注入'));
             return;
         }
         // 旧版 harness 写入：原位置换为标记版
@@ -534,12 +504,12 @@ async function setupClaudeMdOutputStyle(projectPath) {
         const after = content.slice(sectionEnd);
         const newContent = before + section + (after.length > 0 ? '\n' + after : '');
         await fs.writeFile(claudeMdPath, newContent, 'utf-8');
-        console.log(chalk_1.default.green('✅ 已将 CLAUDE.md Output Style 段迁移为标记化管理'));
+        (0, command_contract_1.log)(io, chalk_1.default.green('✅ 已将 CLAUDE.md Output Style 段迁移为标记化管理'));
         return;
     }
     // 完全没有该段：插入文件顶部
     await fs.writeFile(claudeMdPath, section + '\n' + content, 'utf-8');
-    console.log(chalk_1.default.green('✅ 已在 CLAUDE.md 顶部写入 Output Style 段'));
+    (0, command_contract_1.log)(io, chalk_1.default.green('✅ 已在 CLAUDE.md 顶部写入 Output Style 段'));
 }
 /**
  * 治理契约 PRESERVE 段标记（studio #302，ADR 2026-08-21 落点模型：
@@ -556,14 +526,14 @@ const GOVERNANCE_PRESERVE_END = '<!-- /PRESERVE:governance -->';
  *   有标记则只替换标记区间，段内其余手写内容（治理契约引言/流程/纪律等）原样保留；
  *   无标记（纯手写段）则在段尾追加注入段，不动手写内容
  * - 无该段：在文件末尾追加
- * - 段标记残缺（只有单边标记）：不写入，告警交由人工修复（防二次损坏）
+ * - 段标记残缺（外层或段内 HARNESS_CONSTRAINTS 单边/乱序）：不写入，告警交由人工修复（防二次损坏）
  */
-async function setupAgentsMdConstraints(projectPath) {
+async function setupAgentsMdConstraints(projectPath, io = command_contract_1.processIO) {
     const agentsMdPath = path.join(projectPath, 'AGENTS.md');
-    const version = getPackageVersion();
+    const version = (0, package_version_1.getHarnessPackageVersion)();
     const constraints = (0, effective_constraints_1.getEffectiveConstraints)(projectPath);
     const bodyOnly = (0, injection_renderer_1.renderConstraintsSection)(constraints, version);
-    const block = `${GOVERNANCE_PRESERVE_BEGIN}\n## Governance Rules\n${bodyOnly}${GOVERNANCE_PRESERVE_END}\n`;
+    const block = `${GOVERNANCE_PRESERVE_BEGIN}\n${injection_writer_1.GOVERNANCE_HEADING}\n${bodyOnly}${GOVERNANCE_PRESERVE_END}\n`;
     let existingContent = null;
     try {
         existingContent = await fs.readFile(agentsMdPath, 'utf-8');
@@ -580,51 +550,36 @@ async function setupAgentsMdConstraints(projectPath) {
             block,
         ].join('\n');
         await fs.writeFile(agentsMdPath, skeleton, 'utf-8');
-        console.log(chalk_1.default.green(`✅ 已创建 AGENTS.md 并写入治理契约 PRESERVE:governance 段 (v${version})`));
+        (0, command_contract_1.log)(io, chalk_1.default.green(`✅ 已创建 AGENTS.md 并写入治理契约 PRESERVE:governance 段 (v${version})`));
+        return;
+    }
+    const preserve = (0, injection_writer_1.cutMarkerBlock)(existingContent, GOVERNANCE_PRESERVE_BEGIN, GOVERNANCE_PRESERVE_END);
+    if (preserve === 'half') {
+        (0, command_contract_1.log)(io, chalk_1.default.yellow('⚠️  AGENTS.md 中 PRESERVE:governance 标记残缺（只有单边），跳过治理契约写入，请人工修复'));
         return;
     }
-    const startIdx = existingContent.indexOf(GOVERNANCE_PRESERVE_BEGIN);
-    const endIdx = existingContent.indexOf(GOVERNANCE_PRESERVE_END);
-    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    if (preserve !== 'absent') {
         // 段内机器管理的只有 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(injection_renderer_1.CONSTRAINTS_START_MARKER);
-        const ceIdx = blockContent.indexOf(injection_renderer_1.CONSTRAINTS_END_MARKER);
-        let newBlockContent;
-        if (csIdx !== -1 && ceIdx !== -1 && ceIdx > csIdx) {
-            // 只替换标记区间。bodyOnly 自带结尾换行，故剥掉尾部恰好一个前导换行
-            // （END 标记行的行尾换行），其余手写内容逐字保留，保证幂等。
-            newBlockContent =
-                blockContent.slice(0, csIdx) +
-                    bodyOnly +
-                    blockContent.slice(ceIdx + injection_renderer_1.CONSTRAINTS_END_MARKER.length).replace(/^\n/, '');
-        }
-        else {
-            // 纯手写段（无约束标记）：段尾追加注入段，手写内容不动
-            newBlockContent = blockContent.trimEnd() + '\n\n## Governance Rules\n' + bodyOnly;
+        const inner = (0, injection_writer_1.replaceEnclosedRange)(preserve.inner, injection_renderer_1.CONSTRAINTS_START_MARKER, injection_renderer_1.CONSTRAINTS_END_MARKER, bodyOnly);
+        if (inner.kind === 'half') {
+            (0, command_contract_1.log)(io, chalk_1.default.yellow('⚠️  AGENTS.md PRESERVE:governance 段内 HARNESS_CONSTRAINTS 标记残缺（单边或乱序），跳过治理契约写入，请人工修复'));
+            return;
         }
-        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_1.default.green(`✅ 已更新 AGENTS.md 治理契约 PRESERVE:governance 段 (v${version})`));
+        const newInner = inner.kind === 'updated'
+            ? inner.content
+            : // 纯手写段（无约束标记）：段尾追加注入段，手写内容不动
+                preserve.inner.trimEnd() + '\n\n' + injection_writer_1.GOVERNANCE_HEADING + '\n' + bodyOnly;
+        const write = (0, injection_writer_1.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');
+            (0, command_contract_1.log)(io, chalk_1.default.green(`✅ 已更新 AGENTS.md 治理契约 PRESERVE:governance 段 (v${version})`));
         }
         return;
     }
-    if (startIdx !== -1 || endIdx !== -1) {
-        console.log(chalk_1.default.yellow('⚠️  AGENTS.md 中 PRESERVE:governance 标记残缺（只有单边），跳过治理契约写入，请人工修复'));
-        return;
-    }
     // 无该段：文件末尾追加
     const newContent = existingContent.trimEnd() + '\n\n' + block;
     await fs.writeFile(agentsMdPath, newContent, 'utf-8');
-    console.log(chalk_1.default.green(`✅ 已追加治理契约 PRESERVE:governance 段到 AGENTS.md (v${version})`));
+    (0, command_contract_1.log)(io, chalk_1.default.green(`✅ 已追加治理契约 PRESERVE:governance 段到 AGENTS.md (v${version})`));
 }
 /**
  * 在 CLAUDE.md 中写入/更新 Governance Rules 约束段（旧落点模型，向后兼容保留）
@@ -636,22 +591,13 @@ async function setupAgentsMdConstraints(projectPath) {
  * - 如果存在 HARNESS_CONSTRAINTS_START/END 标记，替换标记间内容
  * - 如果不存在标记，在文件末尾追加约束段
  */
-async function setupClaudeMdConstraints(projectPath) {
+async function setupClaudeMdConstraints(projectPath, io = command_contract_1.processIO) {
     const claudeMdPath = path.join(projectPath, 'CLAUDE.md');
-    // 读取 harness 版本
-    let version = 'unknown';
-    try {
-        const pkgPath = path.join(__dirname, '../../../package.json');
-        const pkg = JSON.parse((0, fs_1.readFileSync)(pkgPath, 'utf-8'));
-        version = pkg.version;
-    }
-    catch {
-        // fallback to 'unknown'
-    }
+    const version = (0, package_version_1.getHarnessPackageVersion)();
     // 生效约束集 → 渲染期望段（纯函数，与写文件分离）
     const constraints = (0, effective_constraints_1.getEffectiveConstraints)(projectPath);
     const bodyOnly = (0, injection_renderer_1.renderConstraintsSection)(constraints, version);
-    const fullSection = '## Governance Rules\n' + bodyOnly;
+    const fullSection = injection_writer_1.GOVERNANCE_HEADING + '\n' + bodyOnly;
     // 检查 CLAUDE.md 是否存在
     let existingContent;
     let fileExists = false;
@@ -665,93 +611,83 @@ async function setupClaudeMdConstraints(projectPath) {
     if (!fileExists) {
         // 创建新文件
         await fs.writeFile(claudeMdPath, fullSection, 'utf-8');
-        console.log(chalk_1.default.green(`✅ 已创建 CLAUDE.md 并写入治理约束 (v${version})`));
+        (0, command_contract_1.log)(io, chalk_1.default.green(`✅ 已创建 CLAUDE.md 并写入治理约束 (v${version})`));
         return;
     }
-    const startIdx = existingContent.indexOf(injection_renderer_1.CONSTRAINTS_START_MARKER);
-    const endIdx = existingContent.indexOf(injection_renderer_1.CONSTRAINTS_END_MARKER);
-    if (startIdx !== -1 && endIdx !== -1) {
-        // 替换标记间内容（标记本身也替换，保持包括最新版本号）。
-        // 尾部换行规范化：标记后恰好保留一个换行分隔，保证重复运行幂等。
-        const before = existingContent.slice(0, startIdx);
-        const after = existingContent.slice(endIdx + injection_renderer_1.CONSTRAINTS_END_MARKER.length).replace(/^\n+/, '');
-        const newContent = before + bodyOnly + (after ? '\n' + after : '');
-        await fs.writeFile(claudeMdPath, newContent, 'utf-8');
-        console.log(chalk_1.default.green(`✅ 已更新 CLAUDE.md 治理约束 (v${version})`));
+    const write = (0, injection_writer_1.replaceStandaloneRange)(existingContent, injection_renderer_1.CONSTRAINTS_START_MARKER, injection_renderer_1.CONSTRAINTS_END_MARKER, bodyOnly);
+    if (write.kind === 'updated') {
+        // 替换标记区间含标记本身（保持包括最新版本号），尾部换行规范化在 writer 内
+        await fs.writeFile(claudeMdPath, write.content, 'utf-8');
+        (0, command_contract_1.log)(io, chalk_1.default.green(`✅ 已更新 CLAUDE.md 治理约束 (v${version})`));
+    }
+    else if (write.kind === 'half') {
+        (0, command_contract_1.log)(io, chalk_1.default.yellow('⚠️  CLAUDE.md 中 HARNESS_CONSTRAINTS 标记残缺（单边或乱序），跳过治理约束注入，请人工修复'));
     }
     else {
         // 在文件末尾追加完整段
         const newContent = existingContent.trimEnd() + '\n\n' + fullSection;
         await fs.writeFile(claudeMdPath, newContent, 'utf-8');
-        console.log(chalk_1.default.green(`✅ 已追加治理约束到 CLAUDE.md (v${version})`));
+        (0, command_contract_1.log)(io, chalk_1.default.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 段（入库公共面正本）
  */
 async function setupGovernanceConstraints(projectPath) {
-    let claudeContent = null;
-    try {
-        claudeContent = await fs.readFile(path.join(projectPath, 'CLAUDE.md'), 'utf-8');
-    }
-    catch {
-        // CLAUDE.md 不存在 → 新仓
-    }
-    if (claudeContent !== null &&
-        (claudeContent.includes(injection_renderer_1.CONSTRAINTS_START_MARKER) || /^##\s+Governance Rules/m.test(claudeContent))) {
-        return setupClaudeMdConstraints(projectPath);
-    }
-    return setupAgentsMdConstraints(projectPath);
+    const { target } = (0, injection_writer_1.resolveGovernanceLanding)(projectPath);
+    return target === 'claude-md'
+        ? setupClaudeMdConstraints(projectPath)
+        : setupAgentsMdConstraints(projectPath);
 }
 /**
  * 设置治理相关文件
  */
-async function setupGovernance(projectPath, level) {
+async function setupGovernance(projectPath, level, io) {
     const governance = GOVERNANCE_PRESETS[level];
     if (!governance)
         return;
-    console.log();
-    console.log(chalk_1.default.blue('📋 设置治理文件...'));
+    (0, command_contract_1.log)(io);
+    (0, command_contract_1.log)(io, chalk_1.default.blue('📋 设置治理文件...'));
     // 1. 生成 CHANGELOG.md
-    await createChangelog(projectPath, governance);
+    await createChangelog(projectPath, governance, io);
     // 2. 在 CLAUDE.md 中写入 Output Style 段（仅在不存在时创建）
     await setupClaudeMdOutputStyle(projectPath);
     // 3. 写入/更新 Governance Rules 约束段（新仓 → AGENTS.md PRESERVE:governance；
     //    旧模型仓 → CLAUDE.md，落点路由见 setupGovernanceConstraints）
     await setupGovernanceConstraints(projectPath);
-    // 4. 生成 CONTEXT.md 文件
+    // 4. 生成 CONTEXT.md 文件（预设形状即 GovernanceConfig，无需再 cast）
     const contextConfig = governance.context_files;
     if (contextConfig?.enabled) {
-        let requiredDirs = contextConfig.required_dirs || [];
+        let requiredDirs = contextConfig.required_dirs ?? [];
         if (requiredDirs.length === 0) {
             requiredDirs = (0, detect_source_roots_1.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, governance) {
+async function createChangelog(projectPath, governance, io) {
     const changelogPath = path.join(projectPath, 'CHANGELOG.md');
     try {
         await fs.access(changelogPath);
-        console.log(chalk_1.default.gray(`CHANGELOG.md 已存在`));
+        (0, command_contract_1.log)(io, chalk_1.default.gray(`CHANGELOG.md 已存在`));
         return;
     }
     catch {
         // 文件不存在，创建
     }
-    const changelogConfig = governance.changelog;
-    const format = changelogConfig?.format || 'keep-a-changelog';
+    const format = governance.changelog?.format || 'keep-a-changelog';
     let content;
     if (format === 'keep-a-changelog') {
         content = `# Changelog
@@ -784,16 +720,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 `;
     }
     await fs.writeFile(changelogPath, content, 'utf-8');
-    console.log(chalk_1.default.green(`✅ 已创建 CHANGELOG.md`));
+    (0, command_contract_1.log)(io, chalk_1.default.green(`✅ 已创建 CHANGELOG.md`));
 }
 /**
  * 在指定目录创建 CONTEXT.md
  */
-async function createContextMd(projectPath, dir) {
+async function createContextMd(projectPath, dir, io) {
     const contextPath = path.join(projectPath, dir, 'CONTEXT.md');
     try {
         await fs.access(contextPath);
-        console.log(chalk_1.default.gray(`${dir}/CONTEXT.md 已存在`));
+        (0, command_contract_1.log)(io, chalk_1.default.gray(`${dir}/CONTEXT.md 已存在`));
         return;
     }
     catch {
@@ -805,7 +741,7 @@ async function createContextMd(projectPath, dir) {
         await fs.access(dirPath);
     }
     catch {
-        console.log(chalk_1.default.yellow(`⚠️  目录 ${dir} 不存在，跳过 CONTEXT.md`));
+        (0, command_contract_1.log)(io, chalk_1.default.yellow(`⚠️  目录 ${dir} 不存在，跳过 CONTEXT.md`));
         return;
     }
     const dirName = path.basename(dir);
@@ -830,7 +766,7 @@ async function createContextMd(projectPath, dir) {
 <!-- 开发时需要注意的约束或约定 -->
 `;
     await fs.writeFile(contextPath, content, 'utf-8');
-    console.log(chalk_1.default.green(`✅ 已创建 ${dir}/CONTEXT.md`));
+    (0, command_contract_1.log)(io, chalk_1.default.green(`✅ 已创建 ${dir}/CONTEXT.md`));
 }
 /**
  * 检测已有 workflow 是否已覆盖 harness 治理命令
@@ -854,13 +790,13 @@ async function findGovernanceCoverage(workflowsDir) {
 /**
  * 设置治理 CI workflow
  */
-async function setupGovernanceWorkflow(projectPath, level) {
+async function setupGovernanceWorkflow(projectPath, level, io) {
     const workflowsDir = path.join(projectPath, '.github', 'workflows');
     const workflowPath = path.join(workflowsDir, 'harness-governance.yml');
     // 检查是否已存在
     try {
         await fs.access(workflowPath);
-        console.log(chalk_1.default.gray(`harness-governance.yml 已存在`));
+        (0, command_contract_1.log)(io, chalk_1.default.gray(`harness-governance.yml 已存在`));
         return;
     }
     catch {
@@ -869,7 +805,7 @@ async function setupGovernanceWorkflow(projectPath, level) {
     // 能力检测：已有 workflow 已跑 harness 治理命令时跳过，避免重复 CI 面
     const coveredBy = await findGovernanceCoverage(workflowsDir);
     if (coveredBy) {
-        console.log(chalk_1.default.gray(`治理检查已由 ${coveredBy} 覆盖，跳过创建 harness-governance.yml`));
+        (0, command_contract_1.log)(io, chalk_1.default.gray(`治理检查已由 ${coveredBy} 覆盖，跳过创建 harness-governance.yml`));
         return;
     }
     await fs.mkdir(workflowsDir, { recursive: true });
@@ -910,6 +846,6 @@ jobs:
 ${docsCheckStep}
 `;
     await fs.writeFile(workflowPath, workflowContent, 'utf-8');
-    console.log(chalk_1.default.green(`✅ 已创建 .github/workflows/harness-governance.yml`));
+    (0, command_contract_1.log)(io, chalk_1.default.green(`✅ 已创建 .github/workflows/harness-governance.yml`));
 }
 //# sourceMappingURL=init.js.map