@dommaker/harness 1.3.0 → 1.5.0

package/src/cli/commands/check.ts

@@ -4,18 +4,51 @@
  * 检查约束是否满足（check 层：Iron Laws / Guidelines；prompt 层仅注入不检查）
  * 工单 23：触发条件与证据检测迁至 core/constraints/context-builder
  * ADR-0001：约束集统一走 getMergedConstraintsConfig 生效集链路（preset/config 禁用/custom/scenes）
+ * harness#88：本命令是 trace 记录器的组合根——core 不上行依赖 monitoring，
+ * 真实收集器在此经构造参数接线
  */
 
 import chalk from 'chalk';
 import * as fs from 'fs';
 import * as path from 'path';
-import { constraintChecker } from '../../core/constraints/checker';
+import { ConstraintChecker } from '../../core/constraints/checker';
 import { IRON_LAWS, GUIDELINES, PROMPTS } from '../../core/constraints/definitions';
 import { getMergedConstraintsConfig } from '../../core/effective-constraints';
 import { buildConstraintContext } from '../../core/constraints/context-builder';
+import { createGitEvidence, type GitEvidence } from '../../core/constraints/git-evidence';
 import { detectInjectionDrift } from '../../core/constraints/injection-drift';
+import { GOVERNANCE_HEADING } from '../../core/constraints/injection-writer';
+import { getTraceCollector } from '../../monitoring/traces';
+import { countJsonlLines } from '../../utils/jsonl';
 import { DEFAULT_TRACE_FILE } from '../../types/trace';
-import type { ConstraintTrigger } from '../../types/constraint';
+import type { ConstraintResult, ConstraintTrigger } from '../../types/constraint';
+import { log, processIO, type CommandIO, type CommandResult } from '../command-contract';
+
+/** 证据行着色（与调用处所属结论块一致） */
+const EVIDENCE_PAINT = {
+  red: chalk.red,
+  yellow: chalk.yellow,
+  gray: chalk.gray,
+} as const;
+
+/**
+ * 打印 checker 的判定证据行（harness#119）
+ *
+ * 文案由 checker 自行措辞（每行自描述），CLI 只负责缩进与着色——
+ * 不在这里解释内容，否则证据形状与措辞会两头漂移。
+ * 传 id 时首行挂上约束 id（提示块里没有父级结论行可依附）。
+ */
+function logEvidence(
+  io: CommandIO,
+  result: ConstraintResult,
+  color: keyof typeof EVIDENCE_PAINT,
+  id?: string
+): void {
+  const paint = EVIDENCE_PAINT[color];
+  (result.evidence ?? []).forEach((line, index) => {
+    log(io, paint(index === 0 && id ? `   - ${id}: ${line}` : `     ${line}`));
+  });
+}
 
 export interface CheckOptions {
   /** 预设名称 */
@@ -26,14 +59,24 @@ export interface CheckOptions {
   trigger?: ConstraintTrigger;
   /** 项目路径 */
   projectPath?: string;
+  /**
+   * git 证据 adapter（非 CLI flag；#87）
+   *
+   * 缺省 = 本 run 独占一份真 git 证据。注入则与调用方共用同一证据快照，
+   * 测试据此断言"同一 run 内每条 git 命令至多执行一次"。
+   */
+  evidence?: GitEvidence;
 }
 
 /**
  * 执行约束检查
  */
-export async function check(options: CheckOptions): Promise<void> {
-  console.log(chalk.blue('🔍 检查约束...'));
-  console.log(chalk.gray(`预设: ${options.preset}`));
+export async function check(
+  options: CheckOptions,
+  io: CommandIO = processIO,
+): Promise<CommandResult> {
+  log(io, chalk.blue('🔍 检查约束...'));
+  log(io, chalk.gray(`预设: ${options.preset}`));
 
   try {
     const projectPath = options.projectPath || process.cwd();
@@ -43,33 +86,38 @@ export async function check(options: CheckOptions): Promise<void> {
     // 项目自定义配置优先于 CLI 预设），优先级规则收在 getMergedConstraintsConfig 一处。
     const merged = getMergedConstraintsConfig(projectPath, { preset: options.preset });
     if (merged.custom.length > 0) {
-      console.log(chalk.gray(`自定义约束: ${merged.custom.length} 条`));
+      log(io, chalk.gray(`自定义约束: ${merged.custom.length} 条`));
     }
     if (merged.disabled.length > 0) {
-      console.log(chalk.gray(`已禁用约束: ${merged.disabled.join(', ')}`));
+      log(io, chalk.gray(`已禁用约束: ${merged.disabled.join(', ')}`));
     }
     const unknownIds = merged.unknownIds ?? [];
     if (unknownIds.length > 0) {
-      console.log(chalk.yellow(`⚠️  配置中存在未知约束 id（已忽略，可清理）: ${unknownIds.join(', ')}`));
+      log(io, chalk.yellow(`⚠️  配置中存在未知约束 id（已忽略，可清理）: ${unknownIds.join(', ')}`));
     }
 
     // 构建上下文（工单 23：触发条件与证据检测收敛至 core/constraints/context-builder）
+    // #87：一次 run 一份 git 证据——context-builder 与 checker 层共用同一实例
+    const evidence = options.evidence ?? createGitEvidence(projectPath);
     const context = await buildConstraintContext({
       projectPath: options.projectPath,
       staged: options.staged,
       trigger: options.trigger,
+      evidence,
     });
     const changedFiles = context.changedFiles ?? [];
     if (changedFiles.length > 0) {
-      console.log(chalk.gray(`变更文件: ${changedFiles.length} 个`));
+      log(io, chalk.gray(`变更文件: ${changedFiles.length} 个`));
     }
-    console.log(chalk.gray(`触发条件: ${[context.operation, ...(context.extraTriggers ?? [])].join(', ')}`));
+    log(io, chalk.gray(`触发条件: ${[context.operation, ...(context.extraTriggers ?? [])].join(', ')}`));
 
-    // 执行三层检查（per-request 传 customConfig，避免单例状态污染）
-    const result = await constraintChecker.checkConstraints(context, merged);
+    // 执行三层检查（per-request 传 customConfig，避免单例状态污染；证据同 run 同源）
+    // trace 记录器经构造参数接线（harness#88）：一次命令一个 checker 实例
+    const checker = new ConstraintChecker(getTraceCollector());
+    const result = await checker.checkConstraints(context, merged, evidence);
 
     // 输出结果
-    console.log();
+    log(io);
 
     // skipped（约定未采用/证据未接线）单独列示，不进 pass/fail 统计（ADR-0001）
     const skippedResults = [
@@ -81,39 +129,54 @@ export async function check(options: CheckOptions): Promise<void> {
     const evaluatedIronLaws = result.ironLaws.filter(r => !r.skipped);
     const ironLawViolations = evaluatedIronLaws.filter(r => !r.satisfied);
     if (ironLawViolations.length === 0 && evaluatedIronLaws.length > 0) {
-      console.log(chalk.green(`✅ 铁律: 全部通过 (${evaluatedIronLaws.length} 条)`));
+      log(io, chalk.green(`✅ 铁律: 全部通过 (${evaluatedIronLaws.length} 条)`));
     } else if (ironLawViolations.length > 0) {
-      console.log(chalk.red(`❌ 铁律违规: ${ironLawViolations.length} 条`));
+      log(io, chalk.red(`❌ 铁律违规: ${ironLawViolations.length} 条`));
       ironLawViolations.forEach(r => {
         if (r.constraint) {
-          console.log(chalk.red(`   - ${r.constraint.id}: ${r.constraint.message}`));
-          console.log(chalk.red(`     ${r.constraint.rule}`));
+          log(io, chalk.red(`   - ${r.constraint.id}: ${r.constraint.message}`));
+          log(io, chalk.red(`     ${r.constraint.rule}`));
+          logEvidence(io, r, 'red');
         }
       });
-      console.log();
-      console.log(chalk.red('🛑 铁律检查失败，请修复后再提交'));
-      process.exit(1);
+      log(io);
+      log(io, chalk.red('🛑 铁律检查失败，请修复后再提交'));
+      return {
+        kind: 'fail',
+        reason: `iron law violated: ${ironLawViolations.map(r => r.constraint?.id ?? 'unknown').join(', ')}`,
+      };
     }
 
     // Guidelines
     if (result.warningCount > 0) {
-      console.log(chalk.yellow(`⚠️  指导原则警告: ${result.warningCount} 条`));
+      log(io, chalk.yellow(`⚠️  指导原则警告: ${result.warningCount} 条`));
       result.guidelines.filter(r => !r.satisfied).forEach(r => {
         if (r.constraint) {
-          console.log(chalk.yellow(`   - ${r.constraint.id}: ${r.constraint.message}`));
+          log(io, chalk.yellow(`   - ${r.constraint.id}: ${r.constraint.message}`));
+          logEvidence(io, r, 'yellow');
         }
       });
     } else if (result.guidelines.length > 0) {
       const evaluatedGuidelines = result.guidelines.filter(r => !r.skipped);
       const passedGuidelines = evaluatedGuidelines.filter(r => r.satisfied).length;
-      console.log(chalk.green(`✅ 指导原则: ${passedGuidelines}/${evaluatedGuidelines.length} 通过`));
+      log(io, chalk.green(`✅ 指导原则: ${passedGuidelines}/${evaluatedGuidelines.length} 通过`));
+    }
+
+    // 提示：通过但带证据（harness#119）——与本次变更无因果的仓库级漂移在此露出，
+    // 不判违规、不改 exit code，只保证「看得见且能自己修」
+    const hints = [...result.ironLaws, ...result.guidelines].filter(
+      r => !r.skipped && r.satisfied && (r.evidence?.length ?? 0) > 0
+    );
+    if (hints.length > 0) {
+      log(io, chalk.gray(`💡 提示: ${hints.length} 条（不判违规，供参考）`));
+      hints.forEach(r => logEvidence(io, r, 'gray', r.id));
     }
 
     // Skipped：约定未采用 / 证据未接线，未评估（不计通过/失败）
     if (skippedResults.length > 0) {
-      console.log(chalk.gray(`⏭️  跳过评估: ${skippedResults.length} 条（约定未采用或证据未接线，不计通过/失败）`));
+      log(io, chalk.gray(`⏭️  跳过评估: ${skippedResults.length} 条（约定未采用或证据未接线，不计通过/失败）`));
       skippedResults.forEach(r => {
-        console.log(chalk.gray(`   - ${r.id}`));
+        log(io, chalk.gray(`   - ${r.id}`));
       });
     }
 
@@ -122,38 +185,39 @@ export async function check(options: CheckOptions): Promise<void> {
     try {
       const drift = detectInjectionDrift(projectPath);
       if (drift.hasDrift) {
-        console.log();
-        console.log(chalk.yellow(`⚠️  检测到 ${drift.injectionFile ?? '治理文档'} 约束注入漂移（仅警告，不阻断）:`));
+        log(io);
+        log(io, chalk.yellow(`⚠️  检测到 ${drift.injectionFile ?? '治理文档'} 约束注入漂移（仅警告，不阻断）:`));
         if (drift.versionDrift) {
-          console.log(chalk.yellow(`   ⚠️⚠️ 注入段版本 (${drift.versionDrift.actual}) ≠ 已安装 harness 版本 (${drift.versionDrift.expected})：agent 上下文中的规则与已安装 harness 版本不一致`));
+          log(io, chalk.yellow(`   ⚠️⚠️ 注入段版本 (${drift.versionDrift.actual}) ≠ 已安装 harness 版本 (${drift.versionDrift.expected})：agent 上下文中的规则与已安装 harness 版本不一致`));
         }
         if (drift.contentDrift) {
-          console.log(chalk.yellow(`   内容漂移: 缺失 ${drift.contentDrift.missing.length} 条 / 多余 ${drift.contentDrift.extra.length} 条（条目级差异见 harness constraints report）`));
+          log(io, chalk.yellow(`   内容漂移: 缺失 ${drift.contentDrift.missing.length} 条 / 多余 ${drift.contentDrift.extra.length} 条（条目级差异见 harness constraints report）`));
         }
         if (drift.duplicateHeading) {
-          console.log(chalk.yellow('   检测到重复的 "## Governance Rules" 章节'));
+          log(io, chalk.yellow(`   检测到重复的 "${GOVERNANCE_HEADING}" 章节`));
         }
-        console.log(chalk.yellow(`   修复: ${drift.fixHint}`));
+        log(io, chalk.yellow(`   修复: ${drift.fixHint}`));
       }
     } catch {
       // 漂移检测失败不影响 check 结果
     }
 
-    console.log();
-    console.log(chalk.green('✅ 约束检查通过'));
+    log(io);
+    log(io, chalk.green('✅ 约束检查通过'));
 
     // 智能提示
     const hint = await getSmartHint(projectPath);
     if (hint) {
-      console.log();
-      console.log(chalk.gray('────────────────────────────────────'));
-      console.log(hint);
-      console.log(chalk.gray('────────────────────────────────────'));
+      log(io);
+      log(io, chalk.gray('────────────────────────────────────'));
+      log(io, hint);
+      log(io, chalk.gray('────────────────────────────────────'));
     }
+    return { kind: 'ok' };
   } catch (error) {
-    console.log();
-    console.log(chalk.red(`❌ 约束检查异常: ${error instanceof Error ? error.message : String(error)}`));
-    process.exit(1);
+    log(io);
+    log(io, chalk.red(`❌ 约束检查异常: ${error instanceof Error ? error.message : String(error)}`));
+    return { kind: 'fail', reason: `check error: ${error instanceof Error ? error.message : String(error)}` };
   }
 }
 
@@ -163,17 +227,12 @@ export async function check(options: CheckOptions): Promise<void> {
 async function getSmartHint(projectPath: string): Promise<string | null> {
   const tracesPath = path.join(projectPath, DEFAULT_TRACE_FILE);
   const statePath = path.join(projectPath, '.harness', '.state.json');
-  
-  // 检查 trace 文件是否存在
-  if (!fs.existsSync(tracesPath)) {
+
+  // 只数非空行数（含坏行），零 parse——原语义不变，走 jsonl 正本（harness#82）
+  const traceCount = countJsonlLines(tracesPath);
+  if (traceCount === 0) {
     return null;
   }
-  
-  // 读取 trace 记录数
-  const tracesContent = fs.readFileSync(tracesPath, 'utf-8');
-  const lines = tracesContent.trim().split('\n').filter(Boolean);
-  const traceCount = lines.length;
-  
   // 读取状态
   let state: { 
     shownHints?: string[];
@@ -206,33 +265,35 @@ async function getSmartHint(projectPath: string): Promise<string | null> {
 /**
  * 列出所有约束
  */
-export function listLaws(): void {
-  console.log(chalk.blue('\n📜 所有约束:\n'));
+/** optionRoutes 一律以 (options) 调用；--list 不消费检查选项，形参仅占位 */
+export function listLaws(_options: Partial<CheckOptions> = {}, io: CommandIO = processIO): CommandResult {
+  log(io, chalk.blue('\n📜 所有约束:\n'));
 
   // Iron Laws
-  console.log(chalk.red('🔴 铁律 (Iron Laws) - 绝对禁止，无例外:\n'));
+  log(io, chalk.red('🔴 铁律 (Iron Laws) - 绝对禁止，无例外:\n'));
   Object.values(IRON_LAWS).forEach(constraint => {
-    console.log(chalk.red(`  ${constraint.id}`));
-    console.log(chalk.gray(`    ${constraint.rule}`));
-    console.log(chalk.gray(`    ${constraint.message}`));
-    console.log();
+    log(io, chalk.red(`  ${constraint.id}`));
+    log(io, chalk.gray(`    ${constraint.rule}`));
+    log(io, chalk.gray(`    ${constraint.message}`));
+    log(io);
   });
 
   // Guidelines
-  console.log(chalk.yellow('🟡 指导原则 (Guidelines) - 优先建议，违背发警告但不阻止:\n'));
+  log(io, chalk.yellow('🟡 指导原则 (Guidelines) - 优先建议，违背发警告但不阻止:\n'));
   Object.values(GUIDELINES).forEach(constraint => {
-    console.log(chalk.yellow(`  ${constraint.id}`));
-    console.log(chalk.gray(`    ${constraint.rule}`));
-    console.log(chalk.gray(`    ${constraint.message}`));
-    console.log();
+    log(io, chalk.yellow(`  ${constraint.id}`));
+    log(io, chalk.gray(`    ${constraint.rule}`));
+    log(io, chalk.gray(`    ${constraint.message}`));
+    log(io);
   });
 
   // Prompts（ADR-0001：纯注入层，不执行检查）
-  console.log(chalk.blue('🔵 提示 (Prompts) - 纯文本注入，不参与检查:\n'));
+  log(io, chalk.blue('🔵 提示 (Prompts) - 纯文本注入，不参与检查:\n'));
   Object.values(PROMPTS).forEach(constraint => {
-    console.log(chalk.blue(`  ${constraint.id}`));
-    console.log(chalk.gray(`    ${constraint.rule}`));
-    console.log(chalk.gray(`    ${constraint.message}`));
-    console.log();
+    log(io, chalk.blue(`  ${constraint.id}`));
+    log(io, chalk.gray(`    ${constraint.rule}`));
+    log(io, chalk.gray(`    ${constraint.message}`));
+    log(io);
   });
+  return { kind: 'ok' };
 }

package/src/cli/commands/command.ts

@@ -5,9 +5,13 @@
  *   harness command "rm -rf /"
  *   harness command --level "DROP TABLE users"
  *   harness command --list
+ *
+ * 判定经返回值外溢（架构评审候选7）：风险等级/黑名单裁决译成 kind，
+ * 退出码映射收敛在 bin 一处。
  */
 
 import { createCommandGate, getCommandRiskLevel, DEFAULT_COMMAND_BLACKLIST, type CommandBlacklistRule } from '../../gates';
+import { log, logError, processIO, type CommandIO, type CommandResult } from '../command-contract';
 
 export interface CommandCheckOptions {
   level?: boolean;
@@ -19,17 +23,21 @@ export interface CommandCheckOptions {
 /**
  * 执行命令黑名单检查（供 bin/harness.js 调用）
  */
-export async function executeCommand(cmd: string | undefined, options: CommandCheckOptions): Promise<void> {
+export async function executeCommand(
+  cmd: string | undefined,
+  options: CommandCheckOptions,
+  io: CommandIO = processIO,
+): Promise<CommandResult> {
   if (options.list) {
     if (options.json) {
-      console.log(JSON.stringify(DEFAULT_COMMAND_BLACKLIST.map((r: CommandBlacklistRule) => ({
+      log(io, JSON.stringify(DEFAULT_COMMAND_BLACKLIST.map((r: CommandBlacklistRule) => ({
         id: r.id,
         level: r.level,
         message: r.message,
         category: r.category,
       })), null, 2));
     } else {
-      console.log('\n命令黑名单规则：\n');
+      log(io, '\n命令黑名单规则：\n');
 
       const byCategory = DEFAULT_COMMAND_BLACKLIST.reduce((acc: Record<string, CommandBlacklistRule[]>, rule: CommandBlacklistRule) => {
         if (!acc[rule.category]) acc[rule.category] = [];
@@ -38,23 +46,23 @@ export async function executeCommand(cmd: string | undefined, options: CommandCh
       }, {});
 
       for (const [category, rules] of Object.entries(byCategory)) {
-        console.log(`[${category}]`);
+        log(io, `[${category}]`);
         for (const rule of rules as CommandBlacklistRule[]) {
           const levelIcon = rule.level === 'block' ? '🚫' : rule.level === 'warn' ? '⚠️' : '📋';
-          console.log(`  ${levelIcon} ${rule.id}: ${rule.message} (${rule.level})`);
+          log(io, `  ${levelIcon} ${rule.id}: ${rule.message} (${rule.level})`);
         }
-        console.log();
+        log(io);
       }
 
-      console.log(`共 ${DEFAULT_COMMAND_BLACKLIST.length} 条规则`);
+      log(io, `共 ${DEFAULT_COMMAND_BLACKLIST.length} 条规则`);
     }
-    return;
+    return { kind: 'ok' };
   }
 
   if (!cmd) {
-    console.error('错误：请提供要检查的命令');
-    console.error('用法：harness command "your command"');
-    process.exit(1);
+    logError(io, '错误：请提供要检查的命令');
+    logError(io, '用法：harness command "your command"');
+    return { kind: 'usage-error', reason: '缺少要检查的命令参数' };
   }
 
   const gate = createCommandGate({ strict: options.strict });
@@ -63,28 +71,33 @@ export async function executeCommand(cmd: string | undefined, options: CommandCh
   if (options.level) {
     const level = getCommandRiskLevel(cmd);
     if (options.json) {
-      console.log(JSON.stringify({ level, command: cmd }));
+      log(io, JSON.stringify({ level, command: cmd }));
     } else {
       const levelColors: Record<string, string> = {
         high: '\x1b[31m',
         medium: '\x1b[33m',
         low: '\x1b[32m',
       };
-      console.log(`${levelColors[level]}${level}\x1b[0m ${cmd}`);
+      log(io, `${levelColors[level]}${level}\x1b[0m ${cmd}`);
     }
-    process.exit(level === 'high' ? 1 : 0);
+    // 严重级闸门（历史条件式）：high → 非零退出
+    return level === 'high'
+      ? { kind: 'fail', reason: `command risk level is high: ${cmd}` }
+      : { kind: 'ok' };
   }
 
   if (options.json) {
-    console.log(JSON.stringify({
+    log(io, JSON.stringify({
       command: cmd,
       passed: result.passed,
       message: result.message,
       details: result.details,
     }, null, 2));
   } else {
-    console.log(result.passed ? `\x1b[32m✓\x1b[0m ${result.message}` : `\x1b[31m✗\x1b[0m ${result.message}`);
+    log(io, result.passed ? `\x1b[32m✓\x1b[0m ${result.message}` : `\x1b[31m✗\x1b[0m ${result.message}`);
   }
 
-  process.exit(result.passed ? 0 : 1);
+  return result.passed
+    ? { kind: 'ok' }
+    : { kind: 'fail', reason: `command gate denied: ${result.message}` };
 }

package/src/cli/commands/constraints-report.ts

@@ -14,14 +14,16 @@ import * as path from 'path';
 import chalk from 'chalk';
 import {
   buildConstraintsUsageReport,
+  CANDIDATE_KIND_LABEL,
   DEFAULT_DIAGNOSE_THRESHOLDS,
   type ConstraintsUsageReport,
   type ConstraintUsageStats,
   type DiagnoseThresholds,
-  type RetireCandidate,
 } from '../../core/constraints/usage-report';
 import { getConstraintsMeta } from './constraints';
 import { detectInjectionDrift, type InjectionDrift } from '../../core/constraints/injection-drift';
+import { GOVERNANCE_HEADING } from '../../core/constraints/injection-writer';
+import { log, processIO, type CommandIO, type CommandResult } from '../command-contract';
 
 export interface ConstraintsReportOptions {
   projectPath?: string;
@@ -36,13 +38,6 @@ export interface ConstraintsReportOptions {
   noiseMinTotal?: number;
 }
 
-const CANDIDATE_KIND_LABEL: Record<RetireCandidate['kind'], string> = {
-  zero_trigger: '零触发',
-  unevaluable: '不可评估',
-  high_noise: '高噪',
-  zero_intercept: '零拦截',
-};
-
 function formatTime(ts: number | undefined): string {
   return ts === undefined ? '-' : new Date(ts).toISOString().slice(0, 10);
 }
@@ -74,6 +69,10 @@ export function renderExportMarkdown(
   lines.push('');
   lines.push(`- harness 版本: ${version}`);
   lines.push(`- 日期: ${now.toISOString().slice(0, 10)}`);
+  if (report.skippedLines > 0) {
+    // 脱敏：只报条数，不报路径、不报坏行内容
+    lines.push(`- ⚠️ trace 文件有 ${report.skippedLines} 行损坏已跳过，下表统计只含其余合法记录`);
+  }
   lines.push('');
 
   lines.push('## 统计表（check 层）');
@@ -120,7 +119,7 @@ export function renderInjectionDriftLines(drift: InjectionDrift): string[] {
   if (drift.notInjected) {
     lines.push('  CLAUDE.md / AGENTS.md 均无约束注入标记段（未注入，不算漂移）；可运行 npx @dommaker/harness init 注入');
     if (drift.duplicateHeading) {
-      lines.push('  另检测到多个 "## Governance Rules" 标题（历史遗留重复章节），建议手工清理后重跑 npx @dommaker/harness init');
+      lines.push(`  另检测到多个 "${GOVERNANCE_HEADING}" 标题（历史遗留重复章节），建议手工清理后重跑 npx @dommaker/harness init`);
     }
     return lines;
   }
@@ -141,7 +140,7 @@ export function renderInjectionDriftLines(drift: InjectionDrift): string[] {
     }
   }
   if (drift.duplicateHeading) {
-    lines.push('  重复章节: 标记段之外还存在另一个 "## Governance Rules" 标题');
+    lines.push(`  重复章节: 标记段之外还存在另一个 "${GOVERNANCE_HEADING}" 标题`);
   }
   lines.push(`  修复: ${drift.fixHint}`);
   return lines;
@@ -150,7 +149,7 @@ export function renderInjectionDriftLines(drift: InjectionDrift): string[] {
 /**
  * CLI handler: harness constraints report
  */
-export async function constraintsReport(options: ConstraintsReportOptions = {}): Promise<void> {
+export async function constraintsReport(options: ConstraintsReportOptions = {}, io: CommandIO = processIO): Promise<CommandResult> {
   const projectRoot = options.projectPath || process.cwd();
   const thresholds: Partial<DiagnoseThresholds> = {};
   if (options.zeroInterceptMin !== undefined) thresholds.zeroInterceptMinEvaluated = options.zeroInterceptMin;
@@ -160,58 +159,61 @@ export async function constraintsReport(options: ConstraintsReportOptions = {}):
   const report = buildConstraintsUsageReport(projectRoot, thresholds);
 
   if (options.json) {
-    console.log(JSON.stringify(report, null, 2));
-    return;
+    log(io, JSON.stringify(report, null, 2));
+    return { kind: 'ok' };
   }
 
-  console.log(chalk.blue('📊 约束使用报告'));
+  log(io, chalk.blue('📊 约束使用报告'));
   if (!report.traceFileExists) {
-    console.log(chalk.gray('   （trace 文件不存在，全部按零触发统计）'));
+    log(io, chalk.gray('   （trace 文件不存在，全部按零触发统计）'));
+  }
+  if (report.skippedLines > 0) {
+    log(io, chalk.yellow(`   ⚠️  trace 文件有 ${report.skippedLines} 行损坏已跳过，统计只含其余合法记录（数据不完整）`));
   }
-  console.log();
+  log(io);
 
   // 统计表
-  console.log(chalk.bold('统计表（check 层）:'));
+  log(io, chalk.bold('统计表（check 层）:'));
   for (const s of report.stats) {
-    console.log(`  ${renderStatsRow(s)}`);
+    log(io, `  ${renderStatsRow(s)}`);
   }
-  console.log();
+  log(io);
 
   // 候选诊断
-  console.log(chalk.bold(`退役候选（${report.candidates.length} 条，阈值: 零拦截≥${thresholds.zeroInterceptMinEvaluated ?? DEFAULT_DIAGNOSE_THRESHOLDS.zeroInterceptMinEvaluated} 次评估, 高噪 fail率>${Math.round((thresholds.highNoiseFailRate ?? DEFAULT_DIAGNOSE_THRESHOLDS.highNoiseFailRate) * 100)}% 且 ≥${thresholds.highNoiseMinEvaluated ?? DEFAULT_DIAGNOSE_THRESHOLDS.highNoiseMinEvaluated} 次评估）:`));
+  log(io, chalk.bold(`退役候选（${report.candidates.length} 条，阈值: 零拦截≥${thresholds.zeroInterceptMinEvaluated ?? DEFAULT_DIAGNOSE_THRESHOLDS.zeroInterceptMinEvaluated} 次评估, 高噪 fail率>${Math.round((thresholds.highNoiseFailRate ?? DEFAULT_DIAGNOSE_THRESHOLDS.highNoiseFailRate) * 100)}% 且 ≥${thresholds.highNoiseMinEvaluated ?? DEFAULT_DIAGNOSE_THRESHOLDS.highNoiseMinEvaluated} 次评估）:`));
   if (report.candidates.length === 0) {
-    console.log(chalk.green('  （无候选）'));
+    log(io, chalk.green('  （无候选）'));
   } else {
     for (const c of report.candidates) {
-      console.log(`  [${CANDIDATE_KIND_LABEL[c.kind]}] ${c.id} — ${c.reason}`);
+      log(io, `  [${CANDIDATE_KIND_LABEL[c.kind]}] ${c.id} — ${c.reason}`);
     }
-    console.log(chalk.gray('  可运行 `harness constraints retire` 交互式处理候选'));
+    log(io, chalk.gray('  可运行 `harness constraints retire` 交互式处理候选'));
   }
-  console.log();
+  log(io);
 
   // 注入清单
-  console.log(chalk.bold(`当前生效 prompt 注入（${report.activePromptIds.length} 条）:`));
+  log(io, chalk.bold(`当前生效 prompt 注入（${report.activePromptIds.length} 条）:`));
   for (const id of report.activePromptIds) {
-    console.log(`  ${id}`);
+    log(io, `  ${id}`);
   }
-  console.log();
+  log(io);
 
   // 配置健康
   if (report.lint.unknownIds.length > 0) {
-    console.log(chalk.yellow('⚠️  配置健康:'));
+    log(io, chalk.yellow('⚠️  配置健康:'));
     for (const id of report.lint.unknownIds) {
-      console.log(chalk.yellow(`  config.yml 中禁用了不存在/已移除的约束 id: ${id}（残留配置，建议清理）`));
+      log(io, chalk.yellow(`  config.yml 中禁用了不存在/已移除的约束 id: ${id}（残留配置，建议清理）`));
     }
-    console.log();
+    log(io);
   }
 
   // 注入漂移（ADR-0001 决策 7：条目级差异 + 修复指引；--export 摘要不含本地漂移状态）
-  console.log(chalk.bold('注入漂移:'));
+  log(io, chalk.bold('注入漂移:'));
   const drift = detectInjectionDrift(projectRoot);
   for (const line of renderInjectionDriftLines(drift)) {
-    console.log(drift.hasDrift ? chalk.yellow(line) : line);
+    log(io, drift.hasDrift ? chalk.yellow(line) : line);
   }
-  console.log();
+  log(io);
 
   // --export
   if (options.export !== undefined && options.export !== false) {
@@ -229,6 +231,7 @@ export async function constraintsReport(options: ConstraintsReportOptions = {}):
 
     fs.mkdirSync(path.dirname(exportPath), { recursive: true });
     fs.writeFileSync(exportPath, markdown, 'utf-8');
-    console.log(chalk.green(`✅ 脱敏报告已导出: ${exportPath}`));
+    log(io, chalk.green(`✅ 脱敏报告已导出: ${exportPath}`));
   }
+  return { kind: 'ok' };
 }