@dommaker/harness 1.7.0 → 1.8.1

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'),
         }],
       },
       {

package/src/cli/commands/failure.ts

@@ -8,7 +8,8 @@ import chalk from 'chalk';
 import * as path from 'path';
 import { FailureRecorder } from '../../failure/recorder';
 import { DEFAULT_FAILURE_LOG_FILE } from '../../types/failure';
-import { log, processIO, type CommandIO, type CommandResult } from '../command-contract';
+import { log, logError, processIO, type CommandIO, type CommandResult } from '../command-contract';
+import { numericFlagMessage, parseNumericFlag } from '../../utils/numeric-flag';
 
 export interface FailureOptions {
   /** 项目路径 */
@@ -34,6 +35,20 @@ export async function failureList(
   options: FailureOptions & { limit?: number | string; type?: string; level?: string },
   io: CommandIO = processIO,
 ): Promise<CommandResult> {
+  // CLI 直传时 limit 为 commander 字符串值；程序内调用传 number（候选7：编组在命令函数）。
+  // 字符串形先过装配窄化（harness#154）：脏输入 fail-loud 且不构造 recorder（零落盘），
+  // 原先 parseInt 出 NaN → falsy → 静默不截断。
+  let limit: number | undefined;
+  if (typeof options.limit === 'string') {
+    const parsed = parseNumericFlag(options.limit, 'int');
+    if (!parsed.ok) {
+      logError(io, numericFlagMessage('--limit', parsed.raw, 'int'));
+      return { kind: 'usage-error', reason: `failure list --limit 非法限制: "${parsed.raw}"` };
+    }
+    limit = parsed.value;
+  } else {
+    limit = options.limit;
+  }
   const recorder = getRecorder(options.projectPath);
 
   let records = await recorder.getHistory();
@@ -44,8 +59,6 @@ export async function failureList(
   if (options.level) {
     records = records.filter(r => r.level === options.level);
   }
-  // CLI 直传时 limit 为 commander 字符串值；程序内调用传 number（候选7：编组在命令函数）
-  const limit = typeof options.limit === 'string' ? parseInt(options.limit, 10) : options.limit;
   if (limit && limit > 0) {
     records = records.slice(-limit);
   }