@dommaker/harness 1.7.0 → 1.8.0

package/src/failure/recorder.ts

@@ -7,7 +7,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { readJsonl, appendJsonl } from '../utils/jsonl';
-import type { FailureRecord } from './types';
+import type { FailureRecord } from '../types/failure';
 
 /**
  * 失败记录器配置

package/src/gates/CONTEXT.md

@@ -5,25 +5,30 @@
 
 ## 核心导出
 - 统一协议：`Gate{id, order, evaluate(ctx)}` → `GateDecision{status: deny|abstain|ask, result: GateResult}`（`types.ts`；`decisionFromResult` 报告→决策映射，浅冻结）
-- 注册表：`gateRegistry`（`registry.ts`）——定义即注册 + 构建期双向闭环（定义无实现/实现无定义/重复 id → 加载期抛错）；`getGate`（未注册抛错）/`listRegisteredGates`/`registeredGateCount`
+- 注册表：`gateRegistry`（`registry.ts`）——定义即注册 + 构建期双向闭环（定义无实现/实现无定义/重复 id → 加载期抛错）；`getGate`（未注册抛错）/`listRegisteredGates`/`registeredGateCount`；闭环校验本体是 `assertGateRegistryClosed(definitions, implementations)`（本模块加载时对 `GATE_DEFINITIONS` × `IMPLEMENTATIONS` 自跑一次，消费方亦可自带两张表调用）
 - 定义表：`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` 移除；enabled 段未注册校验与裁剪走 core/effective-set 共享筛选器（throw 模式），order 重排与重复 id 检测留本侧
-- checker-as-guard 接线点：`createCheckerGate(check)`（`checker-gate.ts`）——ConstraintCheck → Gate（studio #129 随动）；判定经唯一归一点 `normalizeCheckOutcome`（harness#119/ADR-0016）：`false` 或 `CheckDetail.pass=false` → deny（证据行随理由带出），`true`（含 pass+提示）/'skip' → abstain；env 经 `buildCheckEnv(..., 'none')` 构造（显式不接证据，语义见 core/constraints/checkers/types.ts 工厂 doc）
+- 生效集（已删除）：原 `getEffectiveGates` + config.yml `gates.order` / `gates.<id>.enabled` 三重空——无调用方、无任何项目配置过该段、README 无示例且加载器对顶层键名拼错静默通过。`order` 字段与 `runGates` 保留（链内默认序 + 复开点），裁决理由记在 ADR-0002 文末「后续变更」
+- checker-as-guard 接线点：`createCheckerGate(check)`（`checker-gate.ts`）——ConstraintCheck → Gate（studio #129 随动）；判定经唯一归一点 `normalizeCheckOutcome`（harness#119/ADR-0016）：`false` 或 `CheckDetail.pass=false` → deny（证据行随理由带出），`true`（含 pass+提示）/'skip' → abstain；env 经 `buildCheckEnv(..., 'none')` 构造（显式不接证据，语义见 core/constraints/checkers/types.ts 工厂 doc）；`ctx.runEnv` 传入即整条守卫链共用一枚运行级观察面——项目配置文件整链至多读一次，不传则每道门禁自造一枚一次性观察面（判定不变，ADR-0023）
 - 门禁类：`ReviewGate` / `SecurityGate` / `PerformanceGate` / `ContractGate` / `SpecAcceptanceGate` / `CommandGate`（各自执行细节私有，保留 `check()`/`scan()` 报告方法）；SpecAcceptanceGate 的 runner 输出解读与 e2e 判负都从 `core/validators/test-output.ts` 的 `judgeTestRun` 取（解析收口 ADR-0012、判定依据 ADR-0014，本层既不自带正则也不自写判定 `if`）
-- `types.ts` — GateResult（报告结构，保留）/ GateContext / GateDecision 等公共类型 + 报告构造器 `pass` / `fail` / `fromError`（动态 passed 走 `gateResult`）：timestamp 与 duration 口径唯一落点，门禁实现禁止手写 GateResult 字面量（duration 是可选字段，漏写无编译期报错）
+- 命令黑名单的模块级出口（`command.ts`）：规则表正本 `DEFAULT_COMMAND_BLACKLIST`（每台 `CommandGate` 实例构造时拷它作基线，运行时扩展点是 `addRule()`）、默认实例单例出口 `getCommandGate()`、快捷判定 `isCommandAllowed(command)` → boolean 与 `getCommandRiskLevel(command)` → `'high' | 'medium' | 'low'`（后三者都经包根对下游公开，ADR-0003 显式清单）。仓内不靠它们做判定：CLI `command` 用带配置的那台实例（#135/ADR-0024，`command-gate-dead-options.test.ts` 钉住 CLI 源码零引用 `getCommandGate(`/`getCommandRiskLevel`），hook 恒裸构造（见「约定」）；`DEFAULT_COMMAND_BLACKLIST` 的仓内消费者是 `harness command --list` 的展示
+- `types.ts` — GateResult（报告结构，保留）/ GateContext / GateDecision 等公共类型 + 报告构造器 `pass` / `fail` / `fromError`（动态 passed 走 `gateResult`）：timestamp 与 duration 口径唯一落点，门禁实现禁止手写 GateResult 字面量（duration 是可选字段，漏写无编译期报错）。**`GateContext` 只带运行信息（在哪跑 / 跑什么），配置一律走构造器**——曾有 6 个与构造器平行的配置型字段（`projectId` 等），填了不生效，已删（架构评审候选1）
 - 便捷工厂函数：createReviewGate / createSecurityGate / createPerformanceGate / createContractGate / createSpecAcceptanceGate / createCommandGate
 
 ## 依赖关系
-- 依赖 `src/core/`（effective-gates 读 project-config-loader；checker-gate 适配 checkers 注册表类型）
+- 依赖 `src/core/`（checker-gate 适配 checkers 注册表类型并经 `buildCheckEnv` 构造执行环境）
 - 依赖 `src/types/` 公共类型
 
 ## 约定
 - 新门禁必须：① 在 `definitions.ts` 补 GateDefinition（含 CLI 元数据）② 在 `registry.ts` IMPLEMENTATIONS 注册实现（缺一 → 加载期抛错）③ 实现统一 Gate 接口（evaluate 产三态决策，报告由 `types.ts` 的 `pass`/`fail`/`fromError`/`gateResult` 构造，不手写字面量）④ 配 CLI 命令（命令实现文件 + CLI 元数据的 module+export 引用，bin 由定义表驱动生成，不再手写块）+ 测试文件
 - deny 单调是接口契约：决策浅冻结，下游不得改写上游决策
-- `runGates` 是 Gate 链语义的**参考实现**（deny 单调 / ask fail-closed / 全决策浅冻结）：仓内暂无生产调用方（harness CLI 文件驱动逐命令执行，studio `runCompletionGuards` 经 checker-gate 复用语义但不 import），消费方只有测试。「deny 后短路跳过剩余门禁」类优化在出现真实消费者前不做——它与「按执行顺序的全部决策」报告契约直接冲突，短路等于改 GateResult 语义（harness#115 裁决，防后续评审重复提议）
+- **统一接口 `evaluate()` 的生产消费者 = 6 个门禁 CLI 命令**（架构评审候选1 步骤 2）：命令一律穿过 `evaluate()`，`GateDecision → CommandResult` 的映射与失败措辞收在 `src/cli/gate-command.ts` 一处，不再各写一遍（此前是 6 份 `<id> gate denied` + 4 份 `<id> gate error`）。报告面 `check()`/`scan()` 仍是各门禁私有实现，只展示不判断的子命令（`security audit` 等）直读它
+- `runGates` 是 Gate **链**语义的参考实现（deny 单调 / ask fail-closed / 全决策浅冻结）：链级无生产调用方——6 个命令各跑一项（CLI 文件驱动逐命令执行），studio `runCompletionGuards` 是自己的三个 checker、不 import 本层，故消费方只有测试。「deny 后短路跳过剩余门禁」类优化在出现真实链消费者前不做——它与「按执行顺序的全部决策」报告契约直接冲突，短路等于改 GateResult 语义（harness#115 裁决，防后续评审重复提议）；`order` 字段与本执行器即为该复开点保留（config.yml 的声明式顺序/开关面按 ADR-0022 口径收缩，理由记在 ADR-0002 文末「后续变更」）
 - ask 枚举预留：暂无实现，runGates fail-closed 按 deny 计
-- **收到的根要传到自己每个 IO/执行点（harness#95）**：门禁只认 `context.projectPath`，内部相对子路径一律锚到它（`SpecAcceptanceGate` 的 tasksPath、`ContractGate` 的 contractPath、e2e/scan 的 `cwd`），禁止「根已传入却又取 cwd」、禁止 `xxxPath: './…'` 相对默认值——否则 `-p` 半失效且表现为假绿（acceptance 的「无 tasks.yml 即跳过」= passed:true）。本层唯一保留的 cwd 站点是 `checker-gate` 对 `ctx.projectPath` 的缺省兜底（豁免理由见守护表）。约定正本与两道机器可检的闸见 `src/cli/commands/CONTEXT.md`
+- **收到的根要传到自己每个 IO/执行点（harness#95）**：门禁只认 `context.projectPath`，内部相对子路径一律锚到它（`SpecAcceptanceGate` 的 tasksPath、`ContractGate` 的 contractPath、e2e/scan 的 `cwd`），禁止「根已传入却又取 cwd」、禁止 `xxxPath: './…'` 相对默认值——否则 `-p` 半失效且表现为假绿（acceptance 的「无 tasks.yml 即跳过」= passed:true）。本层唯一保留的 cwd 站点是 `checker-gate` 对 `ctx.projectPath` 的缺省兜底（豁免理由见守护表）。适用域自 #139 起覆盖到 monitoring 侧的落点默认值：约定正本是「相对片段（`DEFAULT_TRACE_FILE`）必须由消费点锚根」，闸 3 的键名后缀由 `Path` 扩到 `Path|File|Log` 并新增 `xxxFile: SOME_CONSTANT` 常量引用臂（本层曾漏检的形状正是它）。约定正本与四道机器可检的闸见 `src/cli/commands/CONTEXT.md`
+- **CommandGate 的匹配语义只有一个落点（#135/ADR-0024）**：谓词 `matchCommand`（规则表遍历 + 类别忽略 + 模式测试）与折裁点 `judge`（级别 → 三桶 + `allowed` + `riskLevel`）同为私有，`check()` / `isAllowed()` / `getRiskLevel()` 是这份裁决的三个投影——禁止在投影里再写匹配循环。等级取命中集合里的最高档而非首条命中，不变式「存在阻断级命中 ⟺ `check` 不通过 ⟺ `isAllowed` false ⟺ 等级 high」由 `__tests__/command-single-predicate.test.ts` 的源形状闸（`pattern.test(` / `ignoreCategories.includes(` / 遍历规则表的循环体各恰好一处）+ 三投影一致性闸钉住
+- **hook 只用出厂规则（#135 裁决，不是疏漏）**：`src/pretool-use-hook.ts` 恒裸构造 `new CommandGate()`，不装项目配置——hook 是 fail-open 的纵深防御一道，阻断级之外的命中同样放行（`isAllowed` 只看阻断级）；配置装载只属于 CLI 侧（`harness command`，判定与 `--level` 共用它创建的那台实例）。两条入口是同一决策模块的两个 adapter，不得在 hook 路径另起一套判定
+- **本入口的值面（24 项运行时导出）逐字冻结在 `src/__tests__/public-value-surface.test.ts`**（ADR-0022 追记第 5 条收口）：删掉或新增任一值导出——含上面 6 个 `create*Gate` 工厂（其中 5 个是本入口内联声明）——即红且指名 `./gates` 与符号，「这个函数不在公开面上、删它非 breaking」不再靠人 grep。本入口的值导出恰好全数是包根 `.` 的子集，删除会连带撞 `public-exports.test.ts`，但那个套件报的是 `.`、分不清入口归属；类型面另归 `public-type-surface.test.ts`。增删属公共面 breaking，须走发布级别裁决（ADR-0003/0022）
 
 ## 注意事项
 - 门禁系统不包含业务逻辑，只提供检查能力
@@ -32,3 +37,4 @@
 - `PerformanceGate` 只执法有真实现的维度（coverage 走 json-summary、bundleSize 走 dist 测量）；responseTime/memoryUsage/throughput 三维无真实现（原 Math.random 伪造 + 未接线的 runBenchmark）已随 benchmark 机制整体删除（ADR-0018，架构评审候选2）
 - config.yml gates 段为新增面：引用未注册 id 直接抛错（无历史残留配置需兼容）
 - CommandGate 为命令黑名单检查(SEC-006)
+- `SecurityGate` 的扫描命令是**三级优先级**（`scan()` 内 `??` 链，自上而下取第一个已提供值）：① `context.securityScanCommand` ② 构造时传入的 `scanCommand` ③ `detectScanCommand()` 自动探测（现为常量 `npm audit --json`）。缺省「未提供」的唯一表示是 `undefined`——构造器把 `''` 归一成 `undefined`（`getConfig()`/`this.config` 因此是 `SecurityGateConfig` 而非 `Required<…>`，`scanCommand` 保持可选）；曾因兜成空串令 `??` 链恒停在第二级、第三级探测不可达，`harness security` 不带 `--scan-command` 必抛 `The argument 'file' cannot be empty`（#138）。按包管理器探测（读 lock 选 pnpm/yarn）与 `auditDetails` 的吞错各另开票，本层不改 `detectScanCommand` 常量返回

package/src/gates/__tests__/checker-gate.test.ts

@@ -6,7 +6,7 @@ import { createCheckerGate } from '../checker-gate';
 import { contextFlag, contextEvidenceFlag } from '../../core/constraints/checkers/types';
 
 describe('createCheckerGate', () => {
-  const ctx = { projectId: 'p', projectPath: '/tmp/project' };
+  const ctx = {projectPath: '/tmp/project' };
 
   it('checker 通过（true）→ abstain', async () => {
     const gate = createCheckerGate(contextFlag('flag-pass', () => true), 7);

package/src/gates/__tests__/command-single-predicate.test.ts

@@ -0,0 +1,135 @@
+/**
+ * CommandGate 单一匹配谓词闸（#135，架构评审候选 6）
+ *
+ * 三条逐行同构的匹配循环（`check()` 经 `checkBlacklist()` / `isAllowed()` / `getRiskLevel()`）
+ * 收成一个谓词「命令串 → 命中规则集合」，三个入口退化成它之上的投影。本文件钉两件事：
+ * ① 源形状闸——匹配语义（模式测试 / 类别忽略）在文件内只有一处落点，grep 可证；
+ * ② 一致性闸——同一条目经三个投影得到的裁决互相自洽。
+ *
+ * ② 用 `addRule()` 挂的合成规则跑，不涉出厂规则表内容（对外措辞纪律 PIT-021）。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { CommandGate } from '../command';
+import type { CommandBlacklistRule } from '../types';
+
+const source = fs.readFileSync(path.join(__dirname, '..', 'command.ts'), 'utf-8');
+
+/** 数一个针脚在源文件里出现几次（`split` 计数，不做正则解释） */
+function count(needle: string): number {
+  return source.split(needle).length - 1;
+}
+
+/** 合成规则：三条各自只匹配自己的记号，级别覆盖 block/warn/audit 三档 */
+const SYN_BLOCK: CommandBlacklistRule = {
+  id: 'syn-block',
+  pattern: /\bSYN_BLOCK\b/,
+  level: 'block',
+  message: '合成阻断',
+  category: 'syn-a',
+};
+const SYN_WARN: CommandBlacklistRule = {
+  id: 'syn-warn',
+  pattern: /\bSYN_WARN\b/,
+  level: 'warn',
+  message: '合成警告',
+  category: 'syn-b',
+};
+const SYN_AUDIT: CommandBlacklistRule = {
+  id: 'syn-audit',
+  pattern: /\bSYN_AUDIT\b/,
+  level: 'audit',
+  message: '合成审计',
+  category: 'syn-c',
+};
+const SYN_IGNORED: CommandBlacklistRule = {
+  id: 'syn-ignored',
+  pattern: /\bSYN_IGNORED\b/,
+  level: 'block',
+  message: '合成阻断（类别被忽略）',
+  category: 'syn-d',
+};
+
+/** 装配一台只认合成规则的门禁：出厂规则整体移除，投影一致性判定的输入面因此可控 */
+function syntheticGate(): CommandGate {
+  const gate = new CommandGate();
+  for (const rule of gate.getBlacklist()) gate.removeRule(rule.id);
+  gate.addRule(SYN_WARN);
+  gate.addRule(SYN_BLOCK);
+  gate.addRule(SYN_AUDIT);
+  gate.addRule(SYN_IGNORED);
+  return gate;
+}
+
+describe('CommandGate 匹配循环唯一化（#135）', () => {
+  describe('源形状闸：匹配语义只有一处落点', () => {
+    it('规则模式测试恰好一处（此前三条循环各写一遍）', () => {
+      expect(count('pattern.test(')).toBe(1);
+    });
+
+    it('类别忽略判定恰好一处', () => {
+      expect(count('ignoreCategories.includes(')).toBe(1);
+    });
+
+    it('遍历规则表的循环体恰好一处，且不再有逐条 switch 分派', () => {
+      expect(count('for (const rule of this.blacklist')).toBe(1);
+      expect(count('switch (rule.level)')).toBe(0);
+    });
+  });
+
+  describe('三投影对同一输入互相自洽', () => {
+    it('单条命中：check 的裁决 / isAllowed 的布尔 / getRiskLevel 的等级三者一致', async () => {
+      const gate = syntheticGate();
+      const cases: Array<{ command: string; passed: boolean; allowed: boolean; level: string }> = [
+        { command: 'SYN_BLOCK', passed: false, allowed: false, level: 'high' },
+        { command: 'SYN_WARN', passed: true, allowed: true, level: 'medium' },
+        { command: 'SYN_AUDIT', passed: true, allowed: true, level: 'low' },
+        { command: 'nothing matches', passed: true, allowed: true, level: 'low' },
+      ];
+
+      for (const { command, passed, allowed, level } of cases) {
+        const result = await gate.check(command);
+        expect(result.passed).toBe(passed);
+        expect(gate.isAllowed(command)).toBe(allowed);
+        expect(gate.getRiskLevel(command)).toBe(level);
+      }
+    });
+
+    it('不变式：blocked 级命中 ⟺ check 不通过 ⟺ isAllowed false ⟺ 等级 high', async () => {
+      const gate = syntheticGate();
+      const corpus = ['SYN_BLOCK', 'SYN_WARN', 'SYN_AUDIT', 'SYN_WARN SYN_AUDIT', 'clean'];
+
+      for (const command of corpus) {
+        const result = await gate.check(command);
+        const allowed = gate.isAllowed(command);
+        const level = gate.getRiskLevel(command);
+        const blocked = (result.details?.blocked ?? []).length > 0;
+
+        expect(allowed).toBe(!blocked);
+        expect(result.passed).toBe(!blocked);
+        expect(level === 'high').toBe(blocked);
+      }
+    });
+
+    it('等级取命中集合里的最高档，与规则表次序无关（首条命中即返回的旧语义不再存在）', async () => {
+      const gate = syntheticGate();
+      // 合成装配里 warn 排在 block 之前：只取首条命中会报 medium 而 check/isAllowed 判阻断
+      const command = 'SYN_WARN SYN_BLOCK';
+
+      expect(gate.getRiskLevel(command)).toBe('high');
+      expect(gate.isAllowed(command)).toBe(false);
+      expect((await gate.check(command)).passed).toBe(false);
+    });
+
+    it('忽略类别对三投影同样生效（同一谓词，不会一处忽略一处不忽略）', async () => {
+      const gate = new CommandGate({ ignoreCategories: ['syn-d'] });
+      for (const rule of gate.getBlacklist()) gate.removeRule(rule.id);
+      gate.addRule(SYN_IGNORED);
+
+      expect(gate.isAllowed('SYN_IGNORED')).toBe(true);
+      expect(gate.getRiskLevel('SYN_IGNORED')).toBe('low');
+      expect((await gate.check('SYN_IGNORED')).passed).toBe(true);
+    });
+  });
+});

package/src/gates/__tests__/command.test.ts

@@ -87,21 +87,14 @@ describe('CommandGate', () => {
       }
     });
 
-    it('should respect enabled=false', async () => {
-      const gate = new CommandGate({ enabled: false });
-      const result = await gate.check('rm -rf /');
-      expect(result.passed).toBe(true);
-    });
-
-    it('should support custom blacklist', async () => {
-      const gate = new CommandGate({
-        customBlacklist: [{
-          id: 'custom-block',
-          pattern: /\bmy-custom-dangerous-command\b/i,
-          level: 'block',
-          message: 'Custom dangerous command',
-          category: 'custom',
-        }],
+    it('should support runtime rules via addRule（配置位 customBlacklist 已删，见 ADR-0024）', async () => {
+      const gate = new CommandGate();
+      gate.addRule({
+        id: 'custom-block',
+        pattern: /\bmy-custom-dangerous-command\b/i,
+        level: 'block',
+        message: 'Custom dangerous command',
+        category: 'custom',
       });
       const result = await gate.check('my-custom-dangerous-command --run');
       expect(result.passed).toBe(false);

package/src/gates/__tests__/contract.test.ts

@@ -32,18 +32,18 @@ describe('ContractGate', () => {
 
   it('有效 OpenAPI → check 通过', async () => {
     fs.writeFileSync(path.join(dir, 'openapi.yaml'), VALID_SPEC);
-    const result = await new ContractGate().check({ projectId: 'p', projectPath: dir });
+    const result = await new ContractGate().check({projectPath: dir });
     expect(result.passed).toBe(true);
   });
 
   it('缺 openapi 版本 → check 失败', async () => {
     fs.writeFileSync(path.join(dir, 'openapi.yaml'), INVALID_SPEC);
-    const result = await new ContractGate().check({ projectId: 'p', projectPath: dir });
+    const result = await new ContractGate().check({projectPath: dir });
     expect(result.passed).toBe(false);
   });
 
   it('契约文件缺失 → 跳过（passed）', async () => {
-    const result = await new ContractGate().check({ projectId: 'p', projectPath: dir });
+    const result = await new ContractGate().check({projectPath: dir });
     expect(result.passed).toBe(true);
     expect(result.message).toContain('未找到契约文件');
   });
@@ -51,7 +51,7 @@ describe('ContractGate', () => {
   describe('统一接口 evaluate', () => {
     it('有效契约 → abstain（冻结决策）', async () => {
       fs.writeFileSync(path.join(dir, 'openapi.yaml'), VALID_SPEC);
-      const decision = await new ContractGate().evaluate({ projectId: 'p', projectPath: dir });
+      const decision = await new ContractGate().evaluate({projectPath: dir });
       expect(decision.status).toBe('abstain');
       expect(decision.result.gate).toBe('contract');
       expect(Object.isFrozen(decision)).toBe(true);
@@ -59,7 +59,7 @@ describe('ContractGate', () => {
 
     it('无效契约 → deny', async () => {
       fs.writeFileSync(path.join(dir, 'openapi.yaml'), INVALID_SPEC);
-      const decision = await new ContractGate().evaluate({ projectId: 'p', projectPath: dir });
+      const decision = await new ContractGate().evaluate({projectPath: dir });
       expect(decision.status).toBe('deny');
       expect(decision.result.passed).toBe(false);
     });

package/src/gates/__tests__/gate-interface.test.ts

@@ -33,7 +33,6 @@ describe('ReviewGate 统一接口', () => {
   it('本地模式 requireApproval=true → deny（三态映射 + 冻结）', async () => {
     mockExec.mockImplementation(callExec);
     const decision = await new ReviewGate().evaluate({
-      projectId: 'p',
       projectPath: '/test/project',
     });
     expect(decision.status).toBe('deny');
@@ -45,7 +44,6 @@ describe('ReviewGate 统一接口', () => {
   it('本地模式 requireApproval=false → abstain', async () => {
     mockExec.mockImplementation(callExec);
     const decision = await new ReviewGate({ requireApproval: false }).evaluate({
-      projectId: 'p',
       projectPath: '/test/project',
     });
     expect(decision.status).toBe('abstain');
@@ -67,7 +65,6 @@ describe('SecurityGate 统一接口', () => {
       callback(null, { stdout: JSON.stringify({ audit: { advisories: {} } }) })
     );
     const decision = await new SecurityGate().evaluate({
-      projectId: 'p',
       projectPath: '/test/project',
     });
     expect(decision.status).toBe('abstain');
@@ -87,7 +84,6 @@ describe('SecurityGate 统一接口', () => {
       })
     );
     const decision = await new SecurityGate().evaluate({
-      projectId: 'p',
       projectPath: '/test/project',
     });
     expect(decision.status).toBe('deny');
@@ -102,15 +98,6 @@ describe('SecurityGate 统一接口', () => {
 });
 
 describe('PerformanceGate 统一接口', () => {
-  it('enabled=false → abstain（禁用即放行）', async () => {
-    const decision = await new PerformanceGate({ enabled: false }).evaluate({
-      projectId: 'p',
-      projectPath: '/test/project',
-    });
-    expect(decision.status).toBe('abstain');
-    expect(decision.result.passed).toBe(true);
-  });
-
   it('id/order 字段齐备', () => {
     const gate = new PerformanceGate();
     expect(gate.id).toBe('performance');
@@ -131,7 +118,6 @@ describe('SpecAcceptanceGate 统一接口', () => {
 
   it('tasks.yml 不存在 → abstain（跳过）', async () => {
     const decision = await new SpecAcceptanceGate().evaluate({
-      projectId: 'p',
       projectPath: dir,
       tasksPath: path.join(dir, 'no-such-tasks.yml'),
     });
@@ -157,7 +143,6 @@ describe('SpecAcceptanceGate 统一接口', () => {
       ].join('\n')
     );
     const decision = await new SpecAcceptanceGate().evaluate({
-      projectId: 'p',
       projectPath: dir,
       tasksPath,
     });
@@ -176,7 +161,6 @@ describe('SpecAcceptanceGate 统一接口', () => {
 describe('CommandGate 统一接口', () => {
   it('黑名单命令 → deny', async () => {
     const decision = await new CommandGate().evaluate({
-      projectId: 'p',
       projectPath: '/test/project',
       command: 'rm -rf /',
     });
@@ -186,7 +170,6 @@ describe('CommandGate 统一接口', () => {
 
   it('安全命令 → abstain', async () => {
     const decision = await new CommandGate().evaluate({
-      projectId: 'p',
       projectPath: '/test/project',
       command: 'echo hello',
     });

package/src/gates/__tests__/performance.test.ts

@@ -23,7 +23,6 @@ const mockFs = fs as jest.Mocked<typeof fs>;
 describe('PerformanceGate', () => {
   let gate: PerformanceGate;
   const baseContext = {
-    projectId: 'test-project',
     projectPath: '/test/project',
   };
 
@@ -36,31 +35,19 @@ describe('PerformanceGate', () => {
     it('should use default config', () => {
       const defaultGate = new PerformanceGate();
       const config = defaultGate.getConfig();
-      expect(config.enabled).toBe(true);
       expect(config.thresholds).toEqual({});
     });
 
     it('should accept custom config', () => {
       const customGate = new PerformanceGate({
-        enabled: false,
         coverageTimeout: 60000,
       });
       const config = customGate.getConfig();
-      expect(config.enabled).toBe(false);
       expect(config.coverageTimeout).toBe(60000);
     });
   });
 
   describe('check()', () => {
-    it('should pass when gate is disabled', async () => {
-      const disabledGate = new PerformanceGate({ enabled: false });
-
-      const result = await disabledGate.check(baseContext);
-
-      expect(result.passed).toBe(true);
-      expect(result.message).toContain('已禁用');
-    });
-
     it('should pass when no thresholds defined', async () => {
       const result = await gate.check(baseContext);
 

package/src/gates/__tests__/review.test.ts

@@ -15,7 +15,6 @@ const mockExec = exec as unknown as jest.Mock;
 describe('ReviewGate', () => {
   let gate: ReviewGate;
   const baseContext = {
-    projectId: 'test-project',
     projectPath: '/test/project',
   };
 

package/src/gates/__tests__/runner.test.ts

@@ -23,7 +23,7 @@ function fakeGate(id: string, order: number, status: GateDecisionStatus): Gate {
   };
 }
 
-const ctx: GateContext = { projectId: 'p', projectPath: '/tmp/project' };
+const ctx: GateContext = {projectPath: '/tmp/project' };
 
 describe('runGates', () => {
   it('deny 单调：先 deny 后 abstain，终态 deny（下游不得改回 allow）', async () => {

package/src/gates/__tests__/security-default-scan.test.ts

@@ -0,0 +1,97 @@
+/**
+ * #138 缺省扫描命令断链回归测试
+ *
+ * 断点：SecurityGate 构造器曾把缺省 scanCommand 兜成空串，判定链用 `??`
+ * （空串非 nullish），三级兜底恒停在第二级 → runScan('') 抛
+ * 「The argument 'file' cannot be empty」，detectScanCommand() 全仓不可达。
+ *
+ * 替身落点：这里【不 mock 整个 child_process】——那正是缺省路径一直亮绿灯的机制
+ * （`security.test.ts` 顶层 jest.mock('child_process') 后，exec('') 照样回调桩数据、
+ * 永不抛错，把断点盖住了）。改用 exec 的唯一出口 `src/utils/exec` 的 `execAsync` 作缝：
+ * 记录门禁「实际下发去执行的那条命令字符串」，据此断言链真的落到第三级
+ * （detectScanCommand 的返回值），并对空串复现真实的 exec 抛错（保持红/绿的分界诚实）。
+ * CLI 命令级的缺省路径覆盖见 `src/cli/commands/__tests__/security-default-scan.test.ts`。
+ */
+
+import { execAsync } from '../../utils/exec';
+import { SecurityGate } from '../security';
+
+// 缝替身：只替换 execAsync，模块其余导出保持真实
+jest.mock('../../utils/exec', () => {
+  const actual = jest.requireActual('../../utils/exec');
+  return { ...actual, execAsync: jest.fn() };
+});
+
+const mockExecAsync = execAsync as unknown as jest.Mock;
+
+/** detectScanCommand() 现返回值——链落到第三级的唯一判据 */
+const DETECTED = 'npm audit --json';
+const projectPath = '/probe/project';
+
+describe('SecurityGate 缺省扫描命令（#138 断链）', () => {
+  /** 门禁本轮实际下发执行的命令（按调用顺序） */
+  const issued = (): string[] => mockExecAsync.mock.calls.map((c) => String(c[0]));
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    // 缝替身：空命令复现真实 exec 抛错；非空则回零漏洞 JSON（判定为通过）
+    mockExecAsync.mockImplementation((cmd: string) => {
+      if (!cmd || !cmd.trim()) {
+        return Promise.reject(
+          new TypeError("The argument 'file' cannot be empty. Received ''")
+        );
+      }
+      return Promise.resolve({ stdout: JSON.stringify({ vulnerabilities: {} }), stderr: '' });
+    });
+  });
+
+  describe('三级兜底链可达性', () => {
+    it('不给任何扫描命令 → 下发的是 detectScanCommand() 的返回值而非空串', async () => {
+      const result = await new SecurityGate().scan({ projectPath });
+
+      expect(issued()).toEqual([DETECTED]); // 链走到第三级并把它交给 exec
+      expect(result.details?.scanCommand).toBe(DETECTED);
+      expect(result.passed).toBe(true);
+    });
+
+    it('evaluate() 缺省路径 → abstain 判定，不再报错（harness security 复现路径）', async () => {
+      const decision = await new SecurityGate().evaluate({ projectPath });
+
+      expect(issued()).toEqual([DETECTED]);
+      expect(decision.status).toBe('abstain');
+    });
+
+    it('context.securityScanCommand 优先级最高，不触达探测', async () => {
+      const result = await new SecurityGate().scan({
+        projectPath,
+        securityScanCommand: 'yarn audit --json',
+      });
+
+      expect(issued()).toEqual(['yarn audit --json']);
+      expect(result.details?.scanCommand).toBe('yarn audit --json');
+    });
+
+    it('构造时显式 scanCommand 优先于探测，不触达第三级', async () => {
+      const result = await new SecurityGate({ scanCommand: 'pnpm audit --json' }).scan({
+        projectPath,
+      });
+
+      expect(issued()).toEqual(['pnpm audit --json']);
+      expect(result.details?.scanCommand).toBe('pnpm audit --json');
+    });
+  });
+
+  describe('空串归一（--scan-command ""）', () => {
+    it('显式空串视为未提供 → 归一为 undefined 并落到探测', async () => {
+      const result = await new SecurityGate({ scanCommand: '' }).scan({ projectPath });
+
+      expect(issued()).toEqual([DETECTED]);
+      expect(result.details?.scanCommand).toBe(DETECTED);
+    });
+
+    it('构造器不再出现 scanCommand 的空串缺省', () => {
+      expect(new SecurityGate().getConfig().scanCommand).toBeUndefined();
+      expect(new SecurityGate({ scanCommand: '' }).getConfig().scanCommand).toBeUndefined();
+    });
+  });
+});

package/src/gates/__tests__/security.test.ts

@@ -15,7 +15,6 @@ const mockExec = exec as unknown as jest.Mock;
 describe('SecurityGate', () => {
   let gate: SecurityGate;
   const baseContext = {
-    projectId: 'test-project',
     projectPath: '/test/project',
   };
 
@@ -28,7 +27,6 @@ describe('SecurityGate', () => {
     it('should use default config', () => {
       const defaultGate = new SecurityGate();
       const config = defaultGate.getConfig();
-      expect(config.enabled).toBe(true);
       expect(config.severityThreshold).toBe('high');
       expect(config.ignoreWarnings).toBe(false);
       expect(config.ignoreDevDependencies).toBe(false);
@@ -36,27 +34,16 @@ describe('SecurityGate', () => {
 
     it('should accept custom config', () => {
       const customGate = new SecurityGate({
-        enabled: false,
         severityThreshold: 'critical',
         ignoreWarnings: true,
       });
       const config = customGate.getConfig();
-      expect(config.enabled).toBe(false);
       expect(config.severityThreshold).toBe('critical');
       expect(config.ignoreWarnings).toBe(true);
     });
   });
 
   describe('scan()', () => {
-    it('should pass when gate is disabled', async () => {
-      const disabledGate = new SecurityGate({ enabled: false });
-
-      const result = await disabledGate.scan(baseContext);
-
-      expect(result.passed).toBe(true);
-      expect(result.message).toContain('已禁用');
-    });
-
     it('should pass when no vulnerabilities found', async () => {
       mockExec.mockImplementationOnce((cmd, opts, callback) => {
         callback(null, { stdout: JSON.stringify({ vulnerabilities: {} }) });

package/src/gates/checker-gate.ts

@@ -4,7 +4,8 @@
  * 把已注册的 ConstraintCheck 适配为统一 Gate，供守卫链（如 studio
  * runCompletionGuards）复用 runGates 的 deny 单调 / ask fail-closed 语义。
  *
- * env 经 buildCheckEnv(..., 'none') 构造（显式不接证据），语义见工厂 doc。
+ * env 经 buildCheckEnv(..., 'none') 构造（显式不接证据），语义见工厂 doc；
+ * `ctx.runEnv` 传入即与本 run 其余消费方共用同一份上行数据读取（ADR-0023）。
  */
 
 import type { ConstraintCheck } from '../core/constraints/checkers';
@@ -29,7 +30,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 = buildCheckEnv({ operation: 'manual', projectPath }, 'none');
+      const env = buildCheckEnv({ operation: 'manual', projectPath }, 'none', ctx.runEnv);
       const outcome = normalizeCheckOutcome(await check.evaluate(env));
       const evidence = outcome.evidence.map((e) => `\n  - ${e}`).join('');
       const reason = outcome.skipped