@dommaker/harness 1.1.1 → 1.2.1

package/src/core/project-config-loader.ts

@@ -16,7 +16,8 @@ import type {
   CapabilitiesConfig,
 } from '../types/project-config';
 import { IRON_LAWS, GUIDELINES, PROMPTS } from './constraints/definitions';
-import { applyPreset } from '../presets';
+import { PRESETS_BY_NAME, STANDARD_PRESET } from '../presets';
+import { filterEnabledEntries } from './effective-set';
 
 /**
  * 默认配置
@@ -156,47 +157,72 @@ export class ProjectConfigLoader {
    * 合并内置约束和自定义约束（ADR-0001 生效集完整链路）
    *
    * 合并顺序：内置 → preset 裁剪 → config.yml `constraints.<id>.enabled:false`
-   * 删除（对内置与 custom 同效）→ custom-constraints 追加/extend_exceptions
+   * 删除（对内置与 custom 同效）→ custom-constraints 追加
    * （禁用/已退役的 custom 不追加）→ scenes 过滤
    * （带 appliesTo 的 prompt 仅当 scenes 交集非空时保留）。
    *
    * config.yml 中未知约束 id（如已移除约束的禁用残留）静默忽略，
    * 记录在结果 unknownIds 中供诊断。
    *
-   * @param options.preset 覆盖 config.yml 的 preset（CLI --preset 用）
+   * @param options.preset 覆盖 config.yml 的 preset（CLI --preset 用）；
+   *   未知预设名回落 standard + stderr 警告
    */
   mergeConstraints(options?: { preset?: string }): MergedConstraintsConfig {
-    // 0. preset 裁剪（未知预设名由 applyPreset 回落 standard）
-    const presetMerged = applyPreset(options?.preset ?? this.config.preset ?? 'standard');
+    // 0. preset 裁剪（strict 是 standard 的别名；未知名回落 standard）
+    const presetName = options?.preset ?? this.config.preset ?? 'standard';
+    let preset = PRESETS_BY_NAME[presetName];
+    if (!preset) {
+      console.error(`[harness] 未知预设 "${presetName}"，已回落 standard`);
+      preset = STANDARD_PRESET;
+    }
+    const pick = (
+      source: Record<string, Constraint>,
+      ids: string[] | null
+    ): Record<string, Constraint> => {
+      if (ids === null) return { ...source };
+      const filtered: Record<string, Constraint> = {};
+      for (const id of ids) {
+        if (source[id]) filtered[id] = source[id];
+      }
+      return filtered;
+    };
+    const presetDisabled = (
+      source: Record<string, Constraint>,
+      ids: string[] | null
+    ): string[] => (ids === null ? [] : Object.keys(source).filter(id => !ids.includes(id)));
+
     const unknownIds: string[] = [];
     const result: MergedConstraintsConfig = {
-      ironLaws: presetMerged.ironLaws,
-      guidelines: presetMerged.guidelines,
-      prompts: presetMerged.prompts ?? {},
-      disabled: [...presetMerged.disabled],
+      ironLaws: pick(IRON_LAWS, preset.ironLaws),
+      guidelines: pick(GUIDELINES, preset.guidelines),
+      prompts: pick(PROMPTS, preset.prompts),
+      disabled: [
+        ...presetDisabled(IRON_LAWS, preset.ironLaws),
+        ...presetDisabled(GUIDELINES, preset.guidelines),
+        ...presetDisabled(PROMPTS, preset.prompts),
+      ],
       custom: [],
       unknownIds,
     };
 
-    // 1. 处理启用/禁用配置
+    // 1. 处理启用/禁用配置（未知 id 静默忽略，记录供诊断）
     if (this.config.constraints) {
-      for (const [constraintId, config] of Object.entries(this.config.constraints)) {
-        const isKnown =
-          !!IRON_LAWS[constraintId] ||
-          !!GUIDELINES[constraintId] ||
-          !!PROMPTS[constraintId] ||
-          !!this.customConstraints[constraintId];
-        if (!isKnown) {
-          // 未知 id（如已移除约束的禁用残留）：不报错，记录供诊断
-          unknownIds.push(constraintId);
-        }
-        if (config.enabled === false) {
-          result.disabled.push(constraintId);
-          // 从对应层级中移除
-          delete result.ironLaws[constraintId];
-          delete result.guidelines[constraintId];
-          delete result.prompts![constraintId];
-        }
+      const knownIds = new Set([
+        ...Object.keys(IRON_LAWS),
+        ...Object.keys(GUIDELINES),
+        ...Object.keys(PROMPTS),
+        ...Object.keys(this.customConstraints),
+      ]);
+      const filtered = filterEnabledEntries(knownIds, this.config.constraints, {
+        onUnknownId: 'collect',
+      });
+      unknownIds.push(...filtered.unknownIds);
+      for (const constraintId of filtered.disabledIds) {
+        result.disabled.push(constraintId);
+        // 从对应层级中移除
+        delete result.ironLaws[constraintId];
+        delete result.guidelines[constraintId];
+        delete result.prompts![constraintId];
       }
     }
 
@@ -207,38 +233,8 @@ export class ProjectConfigLoader {
       if (result.disabled.includes(id) || customDef.retired) {
         continue;
       }
-      const extendExceptions = customDef.extend_exceptions;
-      const isExtendOnly =
-        !!extendExceptions && extendExceptions.length > 0 &&
-        !customDef.rule &&
-        !customDef.exceptions;
-
-      if (isExtendOnly) {
-        const builtIn = this.findBuiltInConstraint(id, result);
-        if (builtIn) {
-          const constraint = { ...builtIn };
-          constraint.exceptions = [
-            ...(builtIn.exceptions || []),
-            ...extendExceptions!,
-          ];
-          if (result.ironLaws[id]) result.ironLaws[id] = constraint;
-          if (result.guidelines[id]) result.guidelines[id] = constraint;
-          if (result.prompts![id]) result.prompts![id] = constraint;
-          continue;
-        }
-      }
-
       const constraint = this.toConstraint(customDef, id);
 
-      if (extendExceptions && extendExceptions.length > 0) {
-        const builtIn = this.findBuiltInConstraint(id, result);
-        constraint.exceptions = [
-          ...(builtIn?.exceptions || []),
-          ...(customDef.exceptions || []),
-          ...extendExceptions,
-        ];
-      }
-
       result.custom.push(id);
 
       const level = customDef.level || 'guideline';
@@ -272,16 +268,6 @@ export class ProjectConfigLoader {
     return result;
   }
 
-  /**
-   * 在合并结果中查找内置约束
-   */
-  private findBuiltInConstraint(
-    id: string,
-    merged: MergedConstraintsConfig
-  ): Constraint | undefined {
-    return merged.ironLaws[id] || merged.guidelines[id] || merged.prompts?.[id];
-  }
-
   /**
    * 将自定义约束定义转换为 Constraint
    *
@@ -298,7 +284,6 @@ export class ProjectConfigLoader {
       rule: def.rule || '',
       message: def.message || '',
       trigger: (def.trigger || 'manual') as ConstraintTrigger | ConstraintTrigger[],
-      exceptions: def.exceptions,
       description: def.description,
       promptInjection: def.promptInjection,
       enabled: def.enabled !== false,

package/src/failure/CONTEXT.md

@@ -12,7 +12,7 @@
 ## 依赖关系
 - 依赖 `src/types/constraint` ConstraintViolationError
 - 依赖 `src/core/constraints/` 约束检查结果
-- 被 `src/core/constraints/interceptor.ts` 消费
+- 被 `src/cli/commands/report.ts` 消费（executeWithCollect），并经包根导出
 
 ## 约定
 - 分类规则可扩展(自定义 ErrorClassifierConfig)

package/src/failure/constraint-handler.ts

@@ -2,7 +2,7 @@
  * ConstraintViolationHandler — 约束违规统一处理（S4）
  *
  * 问题：ConstraintViolationError 在 4 个调用点有 4 种行为：
- *   1. 抛异常阻断（checker.ts / interceptor.ts）
+ *   1. 抛异常阻断（checker.ts）
  *   2. 返回 null（report.ts catch 后返回空数据）
  *   3. 返回 403 HTTP 状态
  *   4. console.warn 静默吞掉

package/src/gates/CONTEXT.md

@@ -6,10 +6,10 @@
 ## 核心导出
 - 统一协议：`Gate{id, order, evaluate(ctx)}` → `GateDecision{status: deny|abstain|ask, result: GateResult}`（`types.ts`；`decisionFromResult` 报告→决策映射，浅冻结）
 - 注册表：`gateRegistry`（`registry.ts`）——定义即注册 + 构建期双向闭环（定义无实现/实现无定义/重复 id → 加载期抛错）；`getGate`（未注册抛错）/`listRegisteredGates`/`registeredGateCount`
-- 定义表：`GATE_DEFINITIONS`（`definitions.ts`）——id/description/默认 order/CLI 元数据；bin/harness.js 注册表驱动生成 6 门禁命令（纯数据模块，禁 import 实现，保 --help 懒加载；CLI 实现引用为 module+export，per-command 懒加载，H5）
+- 定义表：`GATE_DEFINITIONS`（`definitions.ts`）——id/description/默认 order/CLI 元数据；CLI 元数据形状即 `CommandDefinition`（ADR-0007：门禁与非门禁共用同一命令定义形状，bin 单引擎单循环；门禁特有语义 = `subcommandStrict:false` 未知子命令落回默认 action + `bareRunsAction:true` 裸跑执行 action）；bin/harness.js 注册表驱动生成 6 门禁命令（纯数据模块，禁 import 实现，保 --help 懒加载；CLI 实现引用为 module+export，per-command 懒加载，H5）
 - 执行器：`runGates`（`runner.ts`）——按 order 升序；deny 单调（下游 abstain 不得改回 allow）+ ask 枚举预留 fail-closed = deny；决策浅冻结
-- 生效集：`getEffectiveGates(projectRoot)`（`effective-gates.ts`）——对齐 getEffectiveConstraints 裁剪模式：config.yml `gates.order` 重排 + `gates.<id>.enabled:false` 移除；引用未注册 id 抛错
-- checker-as-guard 接线点：`createCheckerGate(check)`（`checker-gate.ts`）——ConstraintCheck → Gate（studio #129 随动）；false→deny，true/'skip'→abstain
+- 生效集：`getEffectiveGates(projectRoot)`（`effective-gates.ts`）——对齐 getEffectiveConstraints 裁剪模式：config.yml `gates.order` 重排 + `gates.<id>.enabled:false` 移除；enabled 段未注册校验与裁剪走 core/effective-set 共享筛选器（throw 模式），order 重排与重复 id 检测留本侧
+- checker-as-guard 接线点：`createCheckerGate(check)`（`checker-gate.ts`）——ConstraintCheck → Gate（studio #129 随动）；false→deny，true/'skip'→abstain；env 经 `buildCheckEnv(..., 'none')` 构造（显式不接证据，语义见 core/constraints/checkers/types.ts 工厂 doc）
 - 门禁类：`ReviewGate` / `SecurityGate` / `PerformanceGate` / `ContractGate` / `SpecAcceptanceGate` / `CommandGate`（各自执行细节私有，保留 `check()`/`scan()` 报告方法）
 - `types.ts` — GateResult（报告结构，保留）/ GateContext / GateDecision 等公共类型
 - 便捷工厂函数：createReviewGate / createSecurityGate / createPerformanceGate / createContractGate / createSpecAcceptanceGate / createCommandGate

package/src/gates/checker-gate.ts

@@ -4,13 +4,11 @@
  * 把已注册的 ConstraintCheck 适配为统一 Gate，供守卫链（如 studio
  * runCompletionGuards）复用 runGates 的 deny 单调 / ask fail-closed 语义。
  *
- * 证据语义：本接线点构造的 CheckEnv 不带 git staged diff / 源码扫描证据
- * （stagedDiff 空、srcScan 空）——证据 flag 未接线的 checker 按契约返回
- * 'skip'（不阻断，映射为 abstain）；纯上下文判断的 checker 照常判定。
- * studio 侧若需 git 证据，在 #129 接线时扩展 CheckEnv 构造。
+ * env 经 buildCheckEnv(..., 'none') 构造（显式不接证据），语义见工厂 doc。
  */
 
-import type { CheckEnv, ConstraintCheck } from '../core/constraints/checkers';
+import type { ConstraintCheck } from '../core/constraints/checkers';
+import { buildCheckEnv } from '../core/constraints/checkers';
 import type { Gate, GateContext, GateDecision } from './types';
 import { decisionFromResult } from './decision';
 
@@ -29,13 +27,7 @@ export function createCheckerGate(check: ConstraintCheck, order = 0): Gate {
     async evaluate(ctx: GateContext): Promise<GateDecision> {
       const startTime = Date.now();
       const projectPath = ctx.projectPath || process.cwd();
-      const env: CheckEnv = {
-        context: { operation: 'manual', projectPath },
-        projectPath,
-        stagedDiff: async () => '',
-        stagedDiffNames: async () => '',
-        srcScan: () => [],
-      };
+      const env = buildCheckEnv({ operation: 'manual', projectPath }, 'none');
       const outcome = await check.evaluate(env);
       return decisionFromResult({
         gate: check.id,

package/src/gates/definitions.ts

@@ -3,49 +3,18 @@
  *
  * - 每个门禁在此声明 id / description / 默认 order / CLI 元数据；
  *   registry.ts 按此表做「定义↔实现」双向闭环校验（复制 checker 闭环模式）。
- * - CLI 元数据被 bin/harness.js 消费，注册表驱动生成 6 个门禁命令：
- *   命令名/别名/选项/子命令路由与历史手工块完全兼容；实现引用为
- *   module+export（CommandImplRef），bin 按需 per-command 懒加载（H5/O2）。
+ * - CLI 元数据即 CommandDefinition（架构评审候选8，ADR-0007：形状对齐通用
+ *   命令定义，bin/harness.js 单引擎单循环生成全部命令）：命令名/别名/选项/
+ *   子命令路由与历史手工块完全兼容；实现引用为 module+export（CommandImplRef），
+ *   bin 按需 per-command 懒加载（H5/O2）。门禁特有语义由两个标志表达：
+ *   subcommandStrict:false（未知位置参数落回默认 action）+
+ *   bareRunsAction:true（无位置参数时跑默认 action 而非显示帮助）。
  * - 本模块禁止 import 任何门禁/命令实现（仅 type import，运行时零依赖）——
  *   bin 启动期只加载本纯数据模块（保持 --help/--version 懒加载，
  *   闭环校验在 registry 加载期执行）。
  */
 
-import type { CommandImplRef } from '../cli/commands/definitions';
-
-/**
- * 门禁 CLI 选项元数据（直接映射 commander `.option()`）
- */
-export interface GateCliOption {
-  /** commander option flags，如 '-p, --project-path <path>' */
-  flags: string;
-  /** 选项描述 */
-  description: string;
-  /** commander 缺省值；negated option（如 --no-strict）不设，由 commander 默认 true */
-  defaultValue?: string | boolean;
-}
-
-/**
- * 门禁 CLI 命令元数据（bin/harness.js 注册表驱动生成）
- */
-export interface GateCliDefinition {
-  /** 命令名（历史命令名兼容保留） */
-  command: string;
-  /** 命令别名 */
-  alias?: string;
-  /** 位置参数声明，如 '[subcommand]' / '[cmd]' */
-  argument?: string;
-  /** 命令描述 */
-  description: string;
-  /** 命令选项 */
-  options: GateCliOption[];
-  /** 子命令名 → 命令实现引用（module+export）；命中后按 [options] 透传 */
-  subcommands?: Record<string, CommandImplRef>;
-  /** 默认 action 命令实现引用（module+export） */
-  action: CommandImplRef;
-  /** 默认 action 实参构造：arg = 位置参数（无位置参数时为 undefined），options = commander 选项对象 */
-  mapActionArgs: (arg: string | undefined, options: Record<string, unknown>) => unknown[];
-}
+import type { CommandDefinition } from '../cli/commands/definitions';
 
 /**
  * 门禁定义
@@ -57,8 +26,8 @@ export interface GateDefinition {
   description: string;
   /** 默认顺序（config.yml `gates.order` 可覆盖），小者先执行 */
   order: number;
-  /** CLI 元数据（bin/harness.js 注册表驱动生成） */
-  cli: GateCliDefinition;
+  /** CLI 元数据（形状 = CommandDefinition，bin/harness.js 通用引擎驱动生成） */
+  cli: CommandDefinition;
 }
 
 /**
@@ -81,9 +50,11 @@ export const GATE_DEFINITIONS: GateDefinition[] = [
         { flags: '--check-all', description: '检查所有任务', defaultValue: false },
         { flags: '--run-e2e', description: '运行 E2E 测试', defaultValue: false },
       ],
-      subcommands: { list: { module: 'acceptance', export: 'listAcceptanceCriteria' } },
+      subcommands: { list: { impl: { module: 'acceptance', export: 'listAcceptanceCriteria' } } },
+      subcommandStrict: false,
+      bareRunsAction: true,
       action: { module: 'acceptance', export: 'acceptance' },
-      mapActionArgs: (_arg, options) => [options],
+      mapActionArgs: (_positionals, options) => [options],
     },
   },
   {
@@ -102,7 +73,7 @@ export const GATE_DEFINITIONS: GateDefinition[] = [
         { flags: '--strict', description: '严格模式（warn 也阻止）' },
       ],
       action: { module: 'command', export: 'executeCommand' },
-      mapActionArgs: (arg, options) => [arg, options],
+      mapActionArgs: (positionals, options) => [positionals[0], options],
     },
   },
   {
@@ -119,9 +90,11 @@ export const GATE_DEFINITIONS: GateDefinition[] = [
         { flags: '--no-strict', description: '关闭严格模式' },
         { flags: '--allow-breaking', description: '允许破坏性变更', defaultValue: false },
       ],
-      subcommands: { validate: { module: 'contract', export: 'validateSchema' } },
+      subcommands: { validate: { impl: { module: 'contract', export: 'validateSchema' } } },
+      subcommandStrict: false,
+      bareRunsAction: true,
       action: { module: 'contract', export: 'contract' },
-      mapActionArgs: (_arg, options) => [options],
+      mapActionArgs: (_positionals, options) => [options],
     },
   },
   {
@@ -142,7 +115,7 @@ export const GATE_DEFINITIONS: GateDefinition[] = [
         { flags: '--benchmark-timeout <n>', description: '基准测试超时（秒）', defaultValue: '60' },
       ],
       action: { module: 'performance', export: 'performance' },
-      mapActionArgs: (_arg, options) => [
+      mapActionArgs: (_positionals, options) => [
         {
           projectPath: options.projectPath,
           coverage: options.coverage,
@@ -170,9 +143,11 @@ export const GATE_DEFINITIONS: GateDefinition[] = [
         { flags: '--no-block-on-changes', description: '不阻止变更请求' },
         { flags: '--allowed-reviewers <list>', description: '允许的审查者（逗号分隔）' },
       ],
-      subcommands: { status: { module: 'review', export: 'reviewStatus' } },
+      subcommands: { status: { impl: { module: 'review', export: 'reviewStatus' } } },
+      subcommandStrict: false,
+      bareRunsAction: true,
       action: { module: 'review', export: 'review' },
-      mapActionArgs: (_arg, options) => [
+      mapActionArgs: (_positionals, options) => [
         {
           projectPath: options.projectPath,
           minReviewers: parseInt(String(options.minReviewers), 10),
@@ -199,9 +174,11 @@ export const GATE_DEFINITIONS: GateDefinition[] = [
         { flags: '--ignore-dev-deps', description: '忽略开发依赖', defaultValue: false },
         { flags: '--scan-command <cmd>', description: '自定义扫描命令' },
       ],
-      subcommands: { audit: { module: 'security', export: 'auditDetails' } },
+      subcommands: { audit: { impl: { module: 'security', export: 'auditDetails' } } },
+      subcommandStrict: false,
+      bareRunsAction: true,
       action: { module: 'security', export: 'security' },
-      mapActionArgs: (_arg, options) => [options],
+      mapActionArgs: (_positionals, options) => [options],
     },
   },
 ];

package/src/gates/effective-gates.ts

@@ -12,6 +12,7 @@
 import type { Gate } from './types';
 import { listRegisteredGates } from './registry';
 import { loadRawProjectConfig } from '../core/project-config-loader';
+import { filterEnabledEntries } from '../core/effective-set';
 
 /**
  * config.yml `gates` 段
@@ -40,7 +41,8 @@ export function getEffectiveGates(projectRoot: string = process.cwd()): Gate[] {
   }
 
   // ========================================
-  // 闭环校验：引用未注册 → 抛错
+  // 闭环校验（order 重排与重复 id 检测留门禁侧；
+  // enabled 段的未注册校验走共享筛选器 throw 模式）
   // ========================================
   const orderIds = Array.isArray(config.order) ? (config.order as string[]) : undefined;
   if (orderIds) {
@@ -60,31 +62,22 @@ export function getEffectiveGates(projectRoot: string = process.cwd()): Gate[] {
       seen.add(id);
     }
   }
-  for (const key of Object.keys(config)) {
-    if (key === 'order') continue;
-    if (!known.has(key)) {
-      throw new Error(
-        `[harness] config.yml gates.${key} 引用了未注册的门禁。` +
-        `可用门禁: ${[...known].join(', ')}。`
-      );
-    }
-  }
 
   // ========================================
   // enabled 裁剪（与 getEffectiveConstraints 的 enabled:false 删除同效）
   // ========================================
-  const disabled = new Set<string>();
-  for (const gate of gates) {
-    const entry = config[gate.id];
-    if (
-      entry &&
-      typeof entry === 'object' &&
-      !Array.isArray(entry) &&
-      entry.enabled === false
-    ) {
-      disabled.add(gate.id);
-    }
+  const enabledEntries: Record<string, { enabled?: boolean } | undefined> = {};
+  for (const [key, value] of Object.entries(config)) {
+    if (key === 'order') continue;
+    enabledEntries[key] = value as { enabled?: boolean } | undefined;
   }
+  const { disabledIds } = filterEnabledEntries(known, enabledEntries, {
+    onUnknownId: 'throw',
+    unknownIdError: id =>
+      `[harness] config.yml gates.${id} 引用了未注册的门禁。` +
+      `可用门禁: ${[...known].join(', ')}。`,
+  });
+  const disabled = new Set(disabledIds);
   const effective = gates.filter(g => !disabled.has(g.id));
 
   // ========================================

package/src/gates/index.ts

@@ -35,7 +35,7 @@ export { decisionFromResult } from './decision';
 /**
  * 门禁定义表（定义即注册的单一定义源；bin/harness.js 注册表驱动生成 CLI）
  */
-export { GATE_DEFINITIONS, type GateDefinition, type GateCliDefinition, type GateCliOption } from './definitions';
+export { GATE_DEFINITIONS, type GateDefinition } from './definitions';
 
 /**
  * 门禁注册表（定义↔实现双向闭环，加载期抛错）+ getGate 引用闭环

package/src/hooks/bootstrap.ts

@@ -13,7 +13,6 @@
  */
 
 import { ConstraintChecker } from '../core/constraints/checker';
-import { getTraceCollector } from '../monitoring/traces';
 import { SessionManager } from '../context/session-manager';
 import { ProjectConfigLoader } from '../core/project-config-loader';
 import { HookRegistry } from './registry';
@@ -74,7 +73,6 @@ export async function bootstrapHarness(
 
   // 2. 初始化核心组件
   const checker = ConstraintChecker.getInstance();
-  checker.setTraceRecorder(getTraceCollector());
 
   const sessions = new SessionManager(resolvedPath);
   const hooks = new HookRegistry();
@@ -111,7 +109,6 @@ export function bootstrapHarnessSync(
   const mergedConstraints = loader.mergeConstraints();
 
   const checker = ConstraintChecker.getInstance();
-  checker.setTraceRecorder(getTraceCollector());
 
   const sessions = new SessionManager(resolvedPath);
   const hooks = new HookRegistry();