@dommaker/harness 1.7.0 → 1.8.0

package/src/cli/commands/acceptance.ts

@@ -9,6 +9,7 @@ import * as fs from 'fs/promises';
 import * as path from 'path';
 import { SpecAcceptanceGate } from '../../gates/acceptance';
 import { log, processIO, type CommandIO, type CommandResult } from '../command-contract';
+import { reportGateDecision, reportGateError } from '../gate-command';
 
 
 export interface AcceptanceOptions {
@@ -43,38 +44,32 @@ export async function acceptance(
   });
 
   try {
-    // 执行检查
-    const context = {
+    const decision = await gate.evaluate({
       projectPath,
       taskId: options.taskId,
-    };
+    });
 
-    const result = await gate.check(context as any);
-
-    if (result.passed) {
-      log(io);
-      log(io, chalk.green('✅ 验收标准检查通过'));
-      if (result.details) {
-        log(io, chalk.gray(`   通过项: ${result.details.checkedCriteria ?? 0}`));
-        log(io, chalk.gray(`   总项数: ${result.details.totalCriteria ?? 0}`));
-      }
-    } else {
-      log(io);
-      log(io, chalk.red('❌ 验收标准检查失败'));
-      log(io, chalk.red(`   ${result.message}`));
-      if (result.details?.uncheckedCriteria) {
-        (result.details.uncheckedCriteria as string[]).forEach((criteria: string) => {
-          log(io, chalk.red(`   - ${criteria}`));
-        });
-      }
-      return { kind: 'fail', reason: `acceptance gate denied: ${result.message}` };
-    }
-    return { kind: 'ok' };
-  } catch (error: any) {
-    log(io);
-    log(io, chalk.red('❌ 验收标准检查出错'));
-    log(io, chalk.red(`   ${error.message}`));
-    return { kind: 'fail', reason: `acceptance gate error: ${error.message}` };
+    return reportGateDecision(
+      io,
+      {
+        gateId: 'acceptance',
+        label: '验收标准',
+        onPass: (r) =>
+          r.details
+            ? [
+                chalk.gray(`   通过项: ${r.details.checkedCriteria ?? 0}`),
+                chalk.gray(`   总项数: ${r.details.totalCriteria ?? 0}`),
+              ]
+            : [],
+        onFail: (r) =>
+          r.details?.uncheckedCriteria
+            ? (r.details.uncheckedCriteria as string[]).map((criteria: string) => chalk.red(`   - ${criteria}`))
+            : [],
+      },
+      decision
+    );
+  } catch (error) {
+    return reportGateError(io, 'acceptance', '验收标准', error);
   }
 }
 

package/src/cli/commands/check.ts

@@ -5,7 +5,7 @@
  * 工单 23：触发条件与证据检测迁至 core/constraints/context-builder
  * ADR-0001：约束集统一走 getMergedConstraintsConfig 生效集链路（preset/config 禁用/custom/scenes）
  * harness#88：本命令是 trace 记录器的组合根——core 不上行依赖 monitoring，
- * 真实收集器在此经构造参数接线
+ * 真实收集器在此经构造参数接线；#139：收集器锚根构造，trace 落点跟 --project-path 走
  */
 
 import chalk from 'chalk';
@@ -13,14 +13,15 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { ConstraintChecker } from '../../core/constraints/checker';
 import { IRON_LAWS, GUIDELINES, PROMPTS } from '../../core/constraints/definitions';
-import { getMergedConstraintsConfig } from '../../core/effective-constraints';
+import { getMergedConstraintsConfig, constraintsFromMerged } from '../../core/effective-constraints';
 import { buildConstraintContext } from '../../core/constraints/context-builder';
 import { createGitEvidence, type GitEvidence } from '../../core/constraints/git-evidence';
+import { createRunEnv, type RunEnv } from '../../core/constraints/run-env';
 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 { TraceCollector } from '../../monitoring/traces';
+import { readJsonl } from '../../utils/jsonl';
+import { DEFAULT_TRACE_FILE, type ExecutionTrace } from '../../types/trace';
 import type { ConstraintResult, ConstraintTrigger } from '../../types/constraint';
 import { log, processIO, type CommandIO, type CommandResult } from '../command-contract';
 
@@ -51,8 +52,8 @@ function logEvidence(
 }
 
 export interface CheckOptions {
-  /** 预设名称 */
-  preset: string;
+  /** 预设名称；**不传 = 按项目 `.harness/config.yml` 的 preset**（CLI 不给缺省值，见 commands/definitions.ts） */
+  preset?: string;
   /** 是否只检查暂存文件 */
   staged: boolean;
   /** 触发条件 */
@@ -66,6 +67,13 @@ export interface CheckOptions {
    * 测试据此断言"同一 run 内每条 git 命令至多执行一次"。
    */
   evidence?: GitEvidence;
+  /**
+   * 运行级观察面（非 CLI flag；ADR-0023）
+   *
+   * 缺省 = 本 run 独占一份。注入则与调用方共用同一份上行数据读取，
+   * 测试据此断言「同一次运行内同一项目文件至多读一次」。
+   */
+  runEnv?: RunEnv;
 }
 
 /**
@@ -76,15 +84,19 @@ export async function check(
   io: CommandIO = processIO,
 ): Promise<CommandResult> {
   log(io, chalk.blue('🔍 检查约束...'));
-  log(io, chalk.gray(`预设: ${options.preset}`));
+  log(io, chalk.gray(`预设: ${options.preset ?? '（按 config.yml，缺省 standard）'}`));
 
   try {
     const projectPath = options.projectPath || process.cwd();
+    // 一次 run 一份证据与观察面（#87 / ADR-0023）：入口构造，沿生效集、context、checker 向下传
+    const evidence = options.evidence ?? createGitEvidence(projectPath);
+    const runEnv = options.runEnv ?? createRunEnv(projectPath);
 
     // 生效约束集（ADR-0001）：内置 → preset → config.yml 禁用 → custom 追加 → scenes 过滤。
     // --preset 仅在没有项目自定义配置时覆盖 config.yml 的 preset（工单 23 语义：
     // 项目自定义配置优先于 CLI 预设），优先级规则收在 getMergedConstraintsConfig 一处。
-    const merged = getMergedConstraintsConfig(projectPath, { preset: options.preset });
+    // CLI 不给 -p 缺省值：没传 = 尊重 config.yml（ADR-0023 步骤 4.5，缺省值曾让两者不可区分）
+    const merged = getMergedConstraintsConfig(runEnv, { preset: options.preset });
     if (merged.custom.length > 0) {
       log(io, chalk.gray(`自定义约束: ${merged.custom.length} 条`));
     }
@@ -98,12 +110,13 @@ export async function check(
 
     // 构建上下文（工单 23：触发条件与证据检测收敛至 core/constraints/context-builder）
     // #87：一次 run 一份 git 证据——context-builder 与 checker 层共用同一实例
-    const evidence = options.evidence ?? createGitEvidence(projectPath);
+    // ADR-0023：一次 run 一份运行级观察面——配置、源根探测、trace 证据探测全部共用同一份读取
     const context = await buildConstraintContext({
       projectPath: options.projectPath,
       staged: options.staged,
       trigger: options.trigger,
       evidence,
+      runEnv,
     });
     const changedFiles = context.changedFiles ?? [];
     if (changedFiles.length > 0) {
@@ -113,8 +126,9 @@ export async function check(
 
     // 执行三层检查（per-request 传 customConfig，避免单例状态污染；证据同 run 同源）
     // trace 记录器经构造参数接线（harness#88）：一次命令一个 checker 实例
-    const checker = new ConstraintChecker(getTraceCollector());
-    const result = await checker.checkConstraints(context, merged, evidence);
+    // #139：收集器锚根构造——不传 projectPath 时 trace 会落进调用方 cwd，B 侧读不到
+    const checker = new ConstraintChecker(new TraceCollector({ projectPath }));
+    const result = await checker.checkConstraints(context, merged, evidence, runEnv);
 
     // 输出结果
     log(io);
@@ -183,7 +197,8 @@ export async function check(
     // 注入漂移校验（ADR-0001 决策 7）：黄色警告块，不改 exit code、不影响门禁结果。
     // 无漂移/未注入零输出；漂移检测自身异常静默吞掉，绝不影响 check。
     try {
-      const drift = detectInjectionDrift(projectPath);
+      // 生效集直接用本 run 那一份：一遍算完，且比对对象就是本次实际执法的规则集（ADR-0023 步骤 4.5）
+      const drift = detectInjectionDrift(runEnv, undefined, constraintsFromMerged(merged));
       if (drift.hasDrift) {
         log(io);
         log(io, chalk.yellow(`⚠️  检测到 ${drift.injectionFile ?? '治理文档'} 约束注入漂移（仅警告，不阻断）:`));
@@ -221,6 +236,9 @@ export async function check(
   }
 }
 
+/** 智能提示阈值：trace 累计条数首次达到此数才提示跑 status（判定只要「够不够」，不要总数） */
+const TRACE_HINT_THRESHOLD = 50;
+
 /**
  * 智能提示：检查是否需要提示用户下一步操作
  */
@@ -228,8 +246,13 @@ async function getSmartHint(projectPath: string): Promise<string | null> {
   const tracesPath = path.join(projectPath, DEFAULT_TRACE_FILE);
   const statePath = path.join(projectPath, '.harness', '.state.json');
 
-  // 只数非空行数（含坏行），零 parse——原语义不变，走 jsonl 正本（harness#82）
-  const traceCount = countJsonlLines(tracesPath);
+  // 只读够 TRACE_HINT_THRESHOLD 行即停（坏行照旧占位，条数口径与改前的纯计数逐字一致）——
+  // traces.log 是 append-only 无上限文件，为一个比较符整读不成立
+  // 计数去向：豁免（harness#100）——本消费面只输出「够不够」的提示行，没有可挂坏行计数的输出位
+  const { records, skippedLines } = readJsonl<ExecutionTrace>(tracesPath, 'skip', {
+    head: TRACE_HINT_THRESHOLD,
+  });
+  const traceCount = records.length + skippedLines;
   if (traceCount === 0) {
     return null;
   }
@@ -246,8 +269,8 @@ async function getSmartHint(projectPath: string): Promise<string | null> {
   
   const hints: string[] = [];
   
-  // 条件 1: 记录数首次达到 50
-  if (traceCount >= 50 && !state.shownHints.includes('trace_50')) {
+  // 条件 1: 记录数首次达到阈值
+  if (traceCount >= TRACE_HINT_THRESHOLD && !state.shownHints.includes('trace_50')) {
     hints.push('📊 记录已足够，运行 harness status 查看统计');
     state.shownHints.push('trace_50');
   }

package/src/cli/commands/command.ts

@@ -10,14 +10,14 @@
  * 退出码映射收敛在 bin 一处。
  */
 
-import { createCommandGate, getCommandRiskLevel, DEFAULT_COMMAND_BLACKLIST, type CommandBlacklistRule } from '../../gates';
+import { createCommandGate, DEFAULT_COMMAND_BLACKLIST, type CommandBlacklistRule } from '../../gates';
 import { log, logError, processIO, type CommandIO, type CommandResult } from '../command-contract';
+import { gateCommandResult } from '../gate-command';
 
 export interface CommandCheckOptions {
   level?: boolean;
   list?: boolean;
   json?: boolean;
-  strict?: boolean;
 }
 
 /**
@@ -65,11 +65,14 @@ export async function executeCommand(
     return { kind: 'usage-error', reason: '缺少要检查的命令参数' };
   }
 
-  const gate = createCommandGate({ strict: options.strict });
-  const result = await gate.check(cmd);
+  const gate = createCommandGate();
+  // 命令门禁只判命令串、不读项目根；GateContext 仍要求项目根——本命令无 -p 旗帜，取真实 cwd
+  const decision = await gate.evaluate({ projectPath: process.cwd(), command: cmd });
+  const result = decision.result;
 
   if (options.level) {
-    const level = getCommandRiskLevel(cmd);
+    // 等级取自本命令创建的这台实例：与默认分支同一来源，配置不再中途丢失（#135）
+    const level = gate.getRiskLevel(cmd);
     if (options.json) {
       log(io, JSON.stringify({ level, command: cmd }));
     } else {
@@ -97,7 +100,5 @@ export async function executeCommand(
     log(io, result.passed ? `\x1b[32m✓\x1b[0m ${result.message}` : `\x1b[31m✗\x1b[0m ${result.message}`);
   }
 
-  return result.passed
-    ? { kind: 'ok' }
-    : { kind: 'fail', reason: `command gate denied: ${result.message}` };
+  return gateCommandResult('command', decision);
 }

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

@@ -40,7 +40,7 @@ import { getConstraint } from '../../core/constraints/definitions';
 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 { isConstraintRetired, ProjectConfigLoader } from '../../core/project-config-loader';
 import { getHarnessPackageVersion } from '../../utils/package-version';
 import { FileKnowledgeStore } from '../../knowledge/store';
 import type { KnowledgeEntry } from '../../knowledge/types';
@@ -97,8 +97,14 @@ interface RetireTargetInfo {
 
 /**
  * 查找约束定义（内置 definitions + 项目 custom-constraints）
+ *
+ * loader 由调用方给（一次退役一份观察面，见 retireConstraint）：本函数只读它的装载结果，
+ * 不再自造 ProjectConfigLoader。
  */
-function findRetireTarget(projectRoot: string, id: string): RetireTargetInfo | undefined {
+function findRetireTarget(
+  loader: ProjectConfigLoader,
+  id: string
+): RetireTargetInfo | undefined {
   const builtIn = getConstraint(id);
   if (builtIn) {
     return {
@@ -112,8 +118,6 @@ function findRetireTarget(projectRoot: string, id: string): RetireTargetInfo | u
     };
   }
 
-  const loader = new ProjectConfigLoader(projectRoot);
-  loader.load();
   const custom = loader.getCustomConstraints()[id];
   if (custom) {
     const level = custom.level || 'guideline';
@@ -132,52 +136,20 @@ function findRetireTarget(projectRoot: string, id: string): RetireTargetInfo | u
 }
 
 /**
- * 写 config.yml 退役段（ADR-0001 决策 5）
+ * YAML 条目的读-改-写单点（harness#137）
  *
- * js-yaml 不保留注释：原文件含注释行时重写会丢失，console 说明。
+ * 内置与 custom 两处退役落点原本是两段同型的读-改-写，只差键路径与 patch 内容。
+ * js-yaml 不保留注释：原文件含注释行时重写会丢失，console 说明（`label` 是给用户看的
+ * 文件名，与合并前两处逐字一致）。落盘字节由 `__tests__/constraints-retire.test.ts`
+ * 的逐字节冻结用例钉住——合并属内部重构，对外产物不得漂移。
  */
-function writeRetireConfig(
-  projectRoot: string,
+function setYamlEntry(
+  filePath: string,
+  label: string,
+  section: string,
   id: string,
-  retiredMeta: { at: string; reason: string; stats: { total: number; fail: number; failRate: number } }
+  patch: Record<string, unknown>
 ): void {
-  const configPath = path.join(projectRoot, '.harness', 'config.yml');
-
-  let raw: Record<string, unknown> = {};
-  let hadComments = false;
-  if (fs.existsSync(configPath)) {
-    const original = fs.readFileSync(configPath, 'utf-8');
-    hadComments = original.split('\n').some(l => l.trimStart().startsWith('#'));
-    raw = (yaml.load(original) as Record<string, unknown>) ?? {};
-  }
-
-  const constraints = (raw.constraints ?? {}) as Record<string, unknown>;
-  const prev = (constraints[id] ?? {}) as Record<string, unknown>;
-  constraints[id] = { ...prev, enabled: false, retired: retiredMeta };
-  raw.constraints = constraints;
-
-  fs.mkdirSync(path.dirname(configPath), { recursive: true });
-  fs.writeFileSync(configPath, yaml.dump(raw, { lineWidth: 120 }), 'utf-8');
-
-  if (hadComments) {
-    console.log(chalk.yellow('   ⚠️  config.yml 已重写：js-yaml 不保留原文件注释'));
-  }
-}
-
-/**
- * 写 custom-constraints.yml 退役段（studio#82 D6 统一落点）
- *
- * 在 custom_constraints.<id> 条目内追加 retired 元数据，保留规则原文。
- * js-yaml 不保留注释：原文件含注释行时重写会丢失，console 说明。
- */
-function writeCustomRetireYml(
-  projectRoot: string,
-  fileName: string,
-  id: string,
-  retiredMeta: { at: string; reason: string; stats: { total: number; fail: number; failRate: number } }
-): void {
-  const filePath = path.join(projectRoot, '.harness', fileName);
-
   let raw: Record<string, unknown> = {};
   let hadComments = false;
   if (fs.existsSync(filePath)) {
@@ -186,16 +158,16 @@ function writeCustomRetireYml(
     raw = (yaml.load(original) as Record<string, unknown>) ?? {};
   }
 
-  const customs = (raw.custom_constraints ?? {}) as Record<string, Record<string, unknown>>;
-  const prev = customs[id] ?? {};
-  customs[id] = { ...prev, retired: retiredMeta };
-  raw.custom_constraints = customs;
+  const entries = (raw[section] ?? {}) as Record<string, unknown>;
+  const prev = (entries[id] ?? {}) as Record<string, unknown>;
+  entries[id] = { ...prev, ...patch };
+  raw[section] = entries;
 
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   fs.writeFileSync(filePath, yaml.dump(raw, { lineWidth: 120 }), 'utf-8');
 
   if (hadComments) {
-    console.log(chalk.yellow('   ⚠️  custom-constraints.yml 已重写：js-yaml 不保留原文件注释'));
+    console.log(chalk.yellow(`   ⚠️  ${label} 已重写：js-yaml 不保留原文件注释`));
   }
 }
 
@@ -293,7 +265,13 @@ export function retireConstraint(
   const iso = now.toISOString();
   const reason = options.reason ?? '';
 
-  const target = findRetireTarget(projectRoot, id);
+  // 一次退役一份观察面（ADR-0023 决策 2）：定义查找、already_retired 判定与 custom 文件名
+  // 解析共用这一份装载结果。此前同一次调用 new 了 2–3 枚加载器、各带一次 load()（harness#137）。
+  // 只覆盖写盘**之前**的读取：写盘后 syncGovernanceInjection 必须读到新状态，另起观察面。
+  const loader = new ProjectConfigLoader(projectRoot);
+  loader.load();
+
+  const target = findRetireTarget(loader, id);
   const emptyStats = { total: 0, fail: 0, failRate: 0 };
   const landing: RetireResult['landing'] =
     target?.source === 'custom' ? 'custom-constraints.yml' : 'config.yml';
@@ -301,17 +279,12 @@ export function retireConstraint(
     return { id, status: 'unknown_id', isIronLaw: false, landing, stats: emptyStats, injectionSynced: false };
   }
 
-  // 已退役保护：内置看 config.yml constraints.<id>.enabled === false；
-  // custom 看 yml 条目 retired 元数据（历史落点 config.yml enabled:false 同样保护）
-  const rawConfig = loadRawProjectConfig(projectRoot);
-  const existing = (rawConfig?.constraints as Record<string, { enabled?: boolean; retired?: unknown }> | undefined)?.[id];
-  if (target.source === 'custom') {
-    const loader = new ProjectConfigLoader(projectRoot);
-    loader.load();
-    if (loader.getCustomConstraints()[id]?.retired || existing?.enabled === false) {
-      return { id, status: 'already_retired', isIronLaw: target.isIronLaw, landing, stats: emptyStats, injectionSynced: false };
-    }
-  } else if (existing?.enabled === false) {
+  // 已退役保护：判定单点在 core/project-config-loader isConstraintRetired
+  // （内置看 config.yml enabled:false；custom 看 yml 条目 retired 元数据，
+  // 历史落点 config.yml enabled:false 同样保护）
+  const disabledInConfig = loader.getConfig().constraints?.[id]?.enabled === false;
+  const customDef = target.source === 'custom' ? loader.getCustomConstraints()[id] : undefined;
+  if (isConstraintRetired(customDef, disabledInConfig)) {
     return { id, status: 'already_retired', isIronLaw: target.isIronLaw, landing, stats: emptyStats, injectionSynced: false };
   }
 
@@ -327,14 +300,26 @@ export function retireConstraint(
     failRate: evaluated > 0 ? (usage!.fail / evaluated) : 0,
   };
 
-  // 1. 落盘退役（custom → yml 条目 retired 段；内置 → config.yml，原文均保留）
+  // 1. 落盘退役（custom → yml 条目 retired 段；内置 → config.yml enabled:false + retired 段，
+  // 两处原文均保留）
+  const retiredMeta = { at: iso, reason, stats };
   if (target.source === 'custom') {
-    const loader = new ProjectConfigLoader(projectRoot);
-    loader.load();
     const customFile = loader.getConfig().custom_constraints_file ?? 'custom-constraints.yml';
-    writeCustomRetireYml(projectRoot, customFile, id, { at: iso, reason, stats });
+    setYamlEntry(
+      path.join(projectRoot, '.harness', customFile),
+      'custom-constraints.yml',
+      'custom_constraints',
+      id,
+      { retired: retiredMeta }
+    );
   } else {
-    writeRetireConfig(projectRoot, id, { at: iso, reason, stats });
+    setYamlEntry(
+      path.join(projectRoot, '.harness', 'config.yml'),
+      'config.yml',
+      'constraints',
+      id,
+      { enabled: false, retired: retiredMeta }
+    );
   }
 
   // 2. KnowledgeStore
@@ -454,10 +439,12 @@ export async function runRetireInteractive(
       selectedIds = [...new Set(selectedIds)];
     }
 
-    // 逐条收集 reason + iron 二次确认
+    // 逐条收集 reason + iron 二次确认（一次交互一份装载结果：候选到确认之间不写盘）
+    const planLoader = new ProjectConfigLoader(projectRoot);
+    planLoader.load();
     const plan: { id: string; reason: string; source: RetireTargetInfo['source'] }[] = [];
     for (const id of selectedIds) {
-      const target = findRetireTarget(projectRoot, id);
+      const target = findRetireTarget(planLoader, id);
       if (!target) {
         console.log(chalk.red(`❌ ${id}: 约束不存在，跳过`));
         continue;

package/src/cli/commands/contract.ts

@@ -9,6 +9,7 @@ import * as fs from 'fs/promises';
 import * as path from 'path';
 import { ContractGate } from '../../gates/contract';
 import { log, processIO, type CommandIO, type CommandResult } from '../command-contract';
+import { reportGateDecision, reportGateError } from '../gate-command';
 
 export interface ContractOptions {
   /** 项目路径 */
@@ -52,55 +53,51 @@ export async function contract(
   });
 
   try {
-    const result = await gate.check({
-      projectPath,
-    } as any);
-
-    if (result.passed) {
-      log(io);
-      log(io, chalk.green('✅ 契约门控检查通过'));
-
-      if (result.details) {
-        log(io, chalk.gray(`   Schema 有效: ✅`));
-        if (result.details.endpoints) {
-          log(io, chalk.gray(`   端点数: ${result.details.endpoints}`));
-        }
-        if (result.details.breakingChanges === false) {
-          log(io, chalk.gray(`   破坏性变更: 无`));
-        }
-      }
-    } else {
-      log(io);
-      log(io, chalk.red('❌ 契约门控检查失败'));
-      log(io, chalk.red(`   ${result.message}`));
-
-      if (result.details?.errors) {
-        log(io);
-        log(io, chalk.red('验证错误:'));
-        (result.details.errors as string[]).forEach((error: string) => {
-          log(io, chalk.red(`  - ${error}`));
-        });
-      }
-
-      if (result.details?.breakingChanges) {
-        log(io);
-        log(io, chalk.red('破坏性变更:'));
-        (result.details.breakingChanges as any[]).forEach((change: any) => {
-          log(io, chalk.red(`  - ${change.type}: ${change.path}`));
-          if (change.description) {
-            log(io, chalk.gray(`    ${change.description}`));
+    const decision = await gate.evaluate({ projectPath });
+
+    return reportGateDecision(
+      io,
+      {
+        gateId: 'contract',
+        label: '契约门控',
+        onPass: (r) => {
+          if (!r.details) return [];
+          const lines = [chalk.gray(`   Schema 有效: ✅`)];
+          if (r.details.endpoints) {
+            lines.push(chalk.gray(`   端点数: ${r.details.endpoints}`));
+          }
+          if (r.details.breakingChanges === false) {
+            lines.push(chalk.gray(`   破坏性变更: 无`));
+          }
+          return lines;
+        },
+        onFail: (r) => {
+          const lines: string[] = [];
+
+          if (r.details?.errors) {
+            lines.push('', chalk.red('验证错误:'));
+            (r.details.errors as string[]).forEach((issue: string) => {
+              lines.push(chalk.red(`  - ${issue}`));
+            });
           }
-        });
-      }
 
-      return { kind: 'fail', reason: `contract gate denied: ${result.message}` };
-    }
-    return { kind: 'ok' };
-  } catch (error: any) {
-    log(io);
-    log(io, chalk.red('❌ 契约门控检查出错'));
-    log(io, chalk.red(`   ${error.message}`));
-    return { kind: 'fail', reason: `contract gate error: ${error.message}` };
+          if (r.details?.breakingChanges) {
+            lines.push('', chalk.red('破坏性变更:'));
+            (r.details.breakingChanges as any[]).forEach((change: any) => {
+              lines.push(chalk.red(`  - ${change.type}: ${change.path}`));
+              if (change.description) {
+                lines.push(chalk.gray(`    ${change.description}`));
+              }
+            });
+          }
+
+          return lines;
+        },
+      },
+      decision
+    );
+  } catch (error) {
+    return reportGateError(io, 'contract', '契约门控', error);
   }
 }
 

package/src/cli/commands/definitions.ts

@@ -11,8 +11,12 @@
  *   子命令别名是数据（aliases），实参编组归各命令模块的具名导出
  *   （那才是它的 interface/测试面）；保证 --help/--version 懒加载不被破坏；
  *   注册表完整性断言（引用实现可解析）在 __tests__/registry.test.ts 构建/测试期校验。
+ * - 唯一例外 import：`utils/numeric-flag` 纯函数解析器（harness#154 口径条目指名的
+ *   数值旗帜唯一解析器）——非命令实现、零 IO，不破坏懒加载。
  */
 
+import { requireNumericFlag } from '../../utils/numeric-flag';
+
 /**
  * 命令 CLI 选项元数据（直接映射 commander `.option()`）
  */
@@ -99,7 +103,9 @@ export const COMMAND_DEFINITIONS: CommandDefinition[] = [
     command: 'check',
     description: '检查铁律是否满足',
     options: [
-      { flags: '-p, --preset <preset>', description: '预设名称', defaultValue: 'standard' },
+      // 不给缺省值：「没传 -p」与「传了 standard」必须可区分，否则生效集侧的覆盖规则恒触发、
+      // config.yml 的 preset 静默失效（漂移检测侧按 config.yml 算，两边就会稳定对不上）
+      { flags: '-p, --preset <preset>', description: '预设名称（缺省按项目 config.yml）' },
       { flags: '-s, --staged', description: '只检查暂存文件', defaultValue: false },
       { flags: '-t, --trigger <trigger>', description: '触发条件' },
       { flags: '--project-path <path>', description: '项目路径' },
@@ -143,10 +149,10 @@ export const COMMAND_DEFINITIONS: CommandDefinition[] = [
     options: [
       { flags: '-p, --preset <preset>', description: '预设名称 (strict/standard/relaxed)', defaultValue: 'standard' },
       { flags: '-g, --governance <level>', description: '治理级别 (minimal/standard/strict)' },
-      { flags: '-t, --type <type>', description: '项目类型 (node-api/nextjs-app/python-api/custom)' },
       { flags: '--project-path <path>', description: '项目路径' },
       { flags: '--no-git-hooks', description: '不创建 Git hooks' },
-      { flags: '--no-github-actions', description: '不创建 GitHub Actions' },
+      { flags: '--ci <platform>', description: '服务端 CI 接线平台 (github/gitlab/none)；none = 不创建任何 CI 文件（治理 CI 面亦不建），缺省按 .harness/config.yml 的 ci.platform' },
+      { flags: '--no-github-actions', description: '不创建 GitHub Actions（已废弃：等价 --ci none）' },
       { flags: '--print-snippets', description: '只输出代码片段，不创建文件' },
     ],
     action: { module: 'init', export: 'init' },
@@ -331,9 +337,9 @@ export const COMMAND_DEFINITIONS: CommandDefinition[] = [
           projectPath: options.projectPath,
           export: options.export,
           json: options.json,
-          zeroInterceptMin: parseInt(String(options.zeroInterceptMin), 10),
-          noiseFailRate: parseFloat(String(options.noiseFailRate)),
-          noiseMinTotal: parseInt(String(options.noiseMinTotal), 10),
+          zeroInterceptMin: requireNumericFlag('--zero-intercept-min', options.zeroInterceptMin as string | undefined, 'int'),
+          noiseFailRate: requireNumericFlag('--noise-fail-rate', options.noiseFailRate as string | undefined, 'float'),
+          noiseMinTotal: requireNumericFlag('--noise-min-total', options.noiseMinTotal as string | undefined, 'int'),
         }],
       },
       {