@dommaker/harness 1.3.0 → 1.4.0

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' };
 }

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

@@ -2,7 +2,7 @@
  * harness constraints retire —— 约束退役（ADR-0001 决策 2/5）
  *
  * 建议层全自动（候选诊断复用 report 数据层），执行层保留一次人确认。
- * 落盘形态（#82 D6 一处真相）：
+ * 落盘形态（studio#82 D6 一处真相）：
  *
  * - 内置约束 → config.yml `enabled: false` + `retired` 元数据：
  *
@@ -33,21 +33,24 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as readline from 'readline';
+import { log, logError, processIO, type CommandIO, type CommandResult } from '../command-contract';
 import * as yaml from 'js-yaml';
 import chalk from 'chalk';
 import { getConstraint } from '../../core/constraints/definitions';
-import { renderConstraintsSection, CONSTRAINTS_END_MARKER } from '../../core/constraints/injection-renderer';
-import { resolveInjectionTarget } from '../../core/constraints/injection-drift';
+import { renderConstraintsSection, CONSTRAINTS_START_MARKER, CONSTRAINTS_END_MARKER } from '../../core/constraints/injection-renderer';
+import { replaceStandaloneRange, resolveInjectionTarget } from '../../core/constraints/injection-writer';
 import { getEffectiveConstraints } from '../../core/effective-constraints';
 import { loadRawProjectConfig, ProjectConfigLoader } from '../../core/project-config-loader';
+import { getHarnessPackageVersion } from '../../utils/package-version';
 import { FileKnowledgeStore } from '../../knowledge/store';
 import type { KnowledgeEntry } from '../../knowledge/types';
 import type { Constraint } from '../../types/constraint';
 import {
   buildConstraintsUsageReport,
+  CANDIDATE_KIND_LABEL,
   collectUsageByConstraint,
   readProjectTraces,
-  type RetireCandidate,
+  readProjectTracesReport,
 } from '../../core/constraints/usage-report';
 
 export interface RetireExecuteOptions {
@@ -64,7 +67,7 @@ export interface RetireResult {
   status: RetireStatus;
   /** 是否 check 层 iron（交互模式据此追加确认） */
   isIronLaw: boolean;
-  /** 退役落点：custom 约束落 custom-constraints.yml（#82 D6），内置落 config.yml */
+  /** 退役落点：custom 约束落 custom-constraints.yml（studio#82 D6），内置落 config.yml */
   landing: 'config.yml' | 'custom-constraints.yml';
   stats: { total: number; fail: number; failRate: number };
   /** 治理注入段（CLAUDE.md / AGENTS.md）是否已同步 */
@@ -128,18 +131,6 @@ function findRetireTarget(projectRoot: string, id: string): RetireTargetInfo | u
   return undefined;
 }
 
-/**
- * 读取 harness 版本（与 init.ts 同路径策略）
- */
-function getHarnessVersion(): string {
-  try {
-    const pkgPath = path.join(__dirname, '..', '..', '..', 'package.json');
-    return JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version ?? 'unknown';
-  } catch {
-    return 'unknown';
-  }
-}
-
 /**
  * 写 config.yml 退役段（ADR-0001 决策 5）
  *
@@ -174,7 +165,7 @@ function writeRetireConfig(
 }
 
 /**
- * 写 custom-constraints.yml 退役段（#82 D6 统一落点）
+ * 写 custom-constraints.yml 退役段（studio#82 D6 统一落点）
  *
  * 在 custom_constraints.<id> 条目内追加 retired 元数据，保留规则原文。
  * js-yaml 不保留注释：原文件含注释行时重写会丢失，console 说明。
@@ -280,12 +271,10 @@ function syncGovernanceInjection(projectRoot: string): { synced: boolean; file?:
   const target = resolveInjectionTarget(projectRoot);
   if (!target) return { synced: false };
 
-  const filePath = path.join(projectRoot, target.file);
-  const body = renderConstraintsSection(getEffectiveConstraints(projectRoot), getHarnessVersion());
-  const after = target.content.slice(target.endIdx + CONSTRAINTS_END_MARKER.length).replace(/^\n+/, '');
-  const newContent = target.content.slice(0, target.startIdx) + body + (after ? '\n' + after : '');
-  if (newContent !== target.content) {
-    fs.writeFileSync(filePath, newContent, 'utf-8');
+  const body = renderConstraintsSection(getEffectiveConstraints(projectRoot), getHarnessPackageVersion());
+  const write = replaceStandaloneRange(target.content, CONSTRAINTS_START_MARKER, CONSTRAINTS_END_MARKER, body);
+  if (write.kind === 'updated' && write.content !== target.content) {
+    fs.writeFileSync(path.join(projectRoot, target.file), write.content, 'utf-8');
   }
   return { synced: true, file: target.file };
 }
@@ -327,6 +316,9 @@ export function retireConstraint(
   }
 
   // 历史统计（来自 traces.log）
+  // 计数去向：兼容包装 readProjectTraces() 丢计数（harness#100）——落盘的 retire stats 只计
+  // 合法记录，把坏行数写进 RetireResult.stats 属形状变更不在本票；本函数按契约「纯执行无交互」
+  // 不打印，告知由两条命令入口各自负责（runRetireInteractive 顶部 / constraintsRetire 的 --yes 分支）
   const usage = collectUsageByConstraint(readProjectTraces(projectRoot)).get(id);
   const evaluated = usage ? usage.total - usage.skip : 0;
   const stats = {
@@ -366,29 +358,30 @@ export function retireConstraint(
 /**
  * 打印单条退役结果（含回滚语义提示）
  */
-export function printRetireResult(result: RetireResult): void {
+export function printRetireResult(result: RetireResult, io: CommandIO = processIO): CommandResult {
   switch (result.status) {
     case 'unknown_id':
-      console.log(chalk.red(`❌ ${result.id}: 约束不存在（既非内置也非 custom-constraints），未做任何变更`));
-      return;
+      log(io, chalk.red(`❌ ${result.id}: 约束不存在（既非内置也非 custom-constraints），未做任何变更`));
+      return { kind: 'skip', reason: `${result.id}: 约束不存在，未做任何变更` };
     case 'already_retired':
-      console.log(chalk.yellow(`⚠️  ${result.id}: 已处于退役状态（config.yml 中 enabled: false），跳过`));
-      return;
+      log(io, chalk.yellow(`⚠️  ${result.id}: 已处于退役状态（config.yml 中 enabled: false），跳过`));
+      return { kind: 'skip', reason: `${result.id}: 已处于退役状态，跳过` };
     case 'retired': {
-      console.log(chalk.green(`✅ ${result.id}: 已退役`));
-      console.log(`   历史统计: total=${result.stats.total} fail=${result.stats.fail} fail率=${Math.round(result.stats.failRate * 100)}%`);
-      console.log(`   知识沉淀: ${result.knowledgeEntryId}（.harness/knowledge）`);
+      log(io, chalk.green(`✅ ${result.id}: 已退役`));
+      log(io, `   历史统计: total=${result.stats.total} fail=${result.stats.fail} fail率=${Math.round(result.stats.failRate * 100)}%`);
+      log(io, `   知识沉淀: ${result.knowledgeEntryId}（.harness/knowledge）`);
       if (result.injectionSynced) {
-        console.log(`   已同步 ${result.injectionFile ?? '治理文档'} 注入段`);
+        log(io, `   已同步 ${result.injectionFile ?? '治理文档'} 注入段`);
       }
       const recovery =
         result.landing === 'custom-constraints.yml'
           ? `删除 custom-constraints.yml 中 custom_constraints.${result.id}.retired 段`
           : `删除 config.yml 中 constraints.${result.id} 段`;
-      console.log(chalk.gray(`   retire 不是删除——恢复方法：${recovery}`));
+      log(io, chalk.gray(`   retire 不是删除——恢复方法：${recovery}`));
       break;
     }
   }
+  return { kind: 'ok' };
 }
 
 // ========================================
@@ -408,13 +401,6 @@ function createAsk(io: RetireIO): { ask: (q: string) => Promise<string>; close:
   };
 }
 
-const CANDIDATE_KIND_LABEL: Record<RetireCandidate['kind'], string> = {
-  zero_trigger: '零触发',
-  unevaluable: '不可评估',
-  high_noise: '高噪',
-  zero_intercept: '零拦截',
-};
-
 /**
  * 交互式退役（候选列表 → 编号多选 → 摘要 → 确认 → 执行）
  *
@@ -423,9 +409,16 @@ const CANDIDATE_KIND_LABEL: Record<RetireCandidate['kind'], string> = {
 export async function runRetireInteractive(
   projectRoot: string,
   io: RetireIO = { input: process.stdin, output: process.stdout }
-): Promise<void> {
+): Promise<CommandResult> {
   const report = buildConstraintsUsageReport(projectRoot);
+  // 候选诊断是退役决策的依据：数据不完整必须先说（harness#100，与 report 同一降级维度）；
+  // 告知行走 stderr，与 status / failure list / 直达分支同一去向（交互正文仍走 console.log）
+  if (report.skippedLines > 0) {
+    console.error(chalk.yellow(`⚠️  trace 文件有 ${report.skippedLines} 行损坏已跳过，候选只基于其余合法记录`));
+  }
   const { ask, close } = createAsk(io);
+  // 退役结果打印走注入流（与 readline 提示同一去向）
+  const out = { stdout: io.output, stderr: io.output } as unknown as CommandIO;
 
   try {
     let selectedIds: string[] = [];
@@ -435,7 +428,7 @@ export async function runRetireInteractive(
       const manual = await ask('可手动输入要退役的约束 id（留空取消）: ');
       if (!manual) {
         console.log('已取消');
-        return;
+        return { kind: 'skip', reason: '交互未确认，未做任何变更' };
       }
       selectedIds = [manual];
     } else {
@@ -447,7 +440,7 @@ export async function runRetireInteractive(
       const answer = await ask('输入编号（逗号分隔多选）或约束 id，留空取消: ');
       if (!answer) {
         console.log('已取消');
-        return;
+        return { kind: 'skip', reason: '交互未确认，未做任何变更' };
       }
 
       for (const token of answer.split(',').map(s => s.trim()).filter(Boolean)) {
@@ -482,7 +475,7 @@ export async function runRetireInteractive(
 
     if (plan.length === 0) {
       console.log('无可执行项，已取消');
-      return;
+      return { kind: 'skip', reason: '交互未确认，未做任何变更' };
     }
 
     // 变更摘要 → 最终确认
@@ -500,17 +493,18 @@ export async function runRetireInteractive(
     const finalConfirm = await ask('确认执行？(y/N) ');
     if (finalConfirm.toLowerCase() !== 'y' && finalConfirm.toLowerCase() !== 'yes') {
       console.log('已取消');
-      return;
+      return { kind: 'skip', reason: '交互未确认，未做任何变更' };
     }
 
     console.log();
     for (const p of plan) {
       const result = retireConstraint(projectRoot, p.id, { reason: p.reason });
-      printRetireResult(result);
+      printRetireResult(result, out);
     }
   } finally {
     close();
   }
+  return { kind: 'ok' };
 }
 
 /**
@@ -519,29 +513,38 @@ export async function runRetireInteractive(
  * 人确认闸门（#24，ADR-0001 决策 2）：带 id 的直达路径必须显式 `--yes`，
  * 无 `--yes` 报错 + 非零退出码，提示改用 `--yes` 或交互模式；不落盘任何文件。
  */
-export async function constraintsRetire(id?: string, options: ConstraintsRetireOptions = {}): Promise<void> {
+export async function constraintsRetire(
+  id?: string,
+  options: ConstraintsRetireOptions = {},
+  io: CommandIO = processIO,
+): Promise<CommandResult> {
   const projectRoot = options.projectPath || process.cwd();
 
   if (id) {
     // 非交互直达：执行层人确认对所有入口成立（含程序化调用方）
     if (!options.yes) {
-      console.error(
+      logError(io,
         chalk.red(`❌ 直达退役需要显式人确认（ADR-0001 决策 2：执行层保留一次人确认），未做任何变更\n`) +
           `   带 --yes 显式确认直达：harness constraints retire ${id} --yes` +
           `${options.reason ? ` --reason "${options.reason}"` : ''}\n` +
           `   或去掉 id 走交互确认：harness constraints retire`
       );
-      process.exitCode = 1;
-      return;
+      return { kind: 'usage-error', reason: `直达退役 ${id} 缺少显式 --yes 人确认，未做任何变更` };
+    }
+
+    // 落盘的 retire stats 只含合法记录：依据不完整要在执行前告知（harness#100，
+    // 直达路径不经过 runRetireInteractive，故两处各自告知）
+    const { skippedLines } = readProjectTracesReport(projectRoot);
+    if (skippedLines > 0) {
+      logError(io, chalk.yellow(`⚠️  trace 文件有 ${skippedLines} 行损坏已跳过，落盘的退役统计只基于其余合法记录`));
     }
 
     const result = retireConstraint(projectRoot, id, { reason: options.reason });
     if (result.status === 'retired' && result.isIronLaw) {
-      console.log(chalk.yellow(`⚠️  ${id} 是一条 Iron Law，已通过 --yes 直达退役（交互模式会要求二次确认）`));
+      log(io, chalk.yellow(`⚠️  ${id} 是一条 Iron Law，已通过 --yes 直达退役（交互模式会要求二次确认）`));
     }
-    printRetireResult(result);
-    return;
+    return printRetireResult(result, io);
   }
 
-  await runRetireInteractive(projectRoot);
+  return runRetireInteractive(projectRoot);
 }

package/src/cli/commands/constraints.ts

@@ -5,10 +5,10 @@
  * 供 Studio 等消费者获取约束的 hash、计数、文本大小等元数据。
  */
 
-import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
 import { createHash } from 'crypto';
 import { getAllConstraints } from '../../core/constraints/definitions';
+import { getHarnessPackageVersion } from '../../utils/package-version';
+import { log, processIO, type CommandIO, type CommandResult } from '../command-contract';
 
 export interface ConstraintsMeta {
   version: string;
@@ -17,24 +17,6 @@ export interface ConstraintsMeta {
   textSize: { total: number; perConstraint: number };
 }
 
-function getPackageVersion(): string {
-  // Try several common locations
-  const candidates = [
-    join(__dirname, '..', '..', '..', 'package.json'),
-    join(process.cwd(), 'package.json'),
-  ];
-  for (const p of candidates) {
-    if (existsSync(p)) {
-      try {
-        return JSON.parse(readFileSync(p, 'utf-8')).version;
-      } catch {
-        // continue to next candidate
-      }
-    }
-  }
-  return 'unknown';
-}
-
 export function getConstraintsMeta(): ConstraintsMeta {
   const constraints = getAllConstraints();
 
@@ -56,7 +38,7 @@ export function getConstraintsMeta(): ConstraintsMeta {
   const hash = createHash('sha256').update(hashInput).digest('hex');
 
   return {
-    version: getPackageVersion(),
+    version: getHarnessPackageVersion(),
     hash,
     counts: {
       ironLaws: ironLaws.length,
@@ -73,14 +55,15 @@ export function getConstraintsMeta(): ConstraintsMeta {
 /**
  * CLI handler: output --json
  */
-export async function constraints(options: { json?: boolean }): Promise<void> {
+export async function constraints(options: { json?: boolean }, io: CommandIO = processIO): Promise<CommandResult> {
   const meta = getConstraintsMeta();
   if (options.json) {
-    console.log(JSON.stringify(meta, null, 2));
+    log(io, JSON.stringify(meta, null, 2));
   } else {
-    console.log(`version: ${meta.version}`);
-    console.log(`hash: ${meta.hash}`);
-    console.log(`ironLaws: ${meta.counts.ironLaws}, guidelines: ${meta.counts.guidelines}, prompts: ${meta.counts.prompts}`);
-    console.log(`textSize: ${meta.textSize.total} chars total, ~${meta.textSize.perConstraint} chars/constraint`);
+    log(io, `version: ${meta.version}`);
+    log(io, `hash: ${meta.hash}`);
+    log(io, `ironLaws: ${meta.counts.ironLaws}, guidelines: ${meta.counts.guidelines}, prompts: ${meta.counts.prompts}`);
+    log(io, `textSize: ${meta.textSize.total} chars total, ~${meta.textSize.perConstraint} chars/constraint`);
   }
+  return { kind: 'ok' };
 }