@dommaker/harness 1.5.0 → 1.7.0

package/src/__tests__/public-type-surface.test.ts

@@ -0,0 +1,359 @@
+/**
+ * 已发布类型面全量冻结闸（ADR-0003 类型面补全 / ADR-0022 追记第 4 条）
+ *
+ * 存在的理由是一起**定级**错误，不是一起删除错误：本仓 breaking 定级长期挂在「这个符号在
+ * 不在包根导出面」这句断言上（ADR-0010:5/31、ADR-0019:10、ADR-0022 皆以它定级），而这句话
+ * 在删除动作之前没有任何闸可跑，全靠人 grep 记忆。`PassesGateResult`（评审 A2）与
+ * `DynamicTask`（二次复审 B1）已在同一处错两次；B1 那次是复审方直接断言「不在包根」，而
+ * 实测 v1.6.0 源 `src/index.ts:106` 与已发布 npm 产物 `dist/index.d.ts:38` 都在导出它。
+ * 本闸让「在不在公开面上」变成跑一下就有答案的事实。
+ *
+ * **公开面 = `package.json` 的 exports 映射，不是只有包根。** 本包发布五个入口点
+ * （`.` / `./core` / `./presets` / `./context` / `./gates`），`import type { X } from
+ * '@dommaker/harness/core'` 与从包根导入同样是对外承诺。入口清单从 exports **派生**而非
+ * 硬编码：新增子路径会立刻落进本闸（未登记冻结清单即红），免得重演「公开面的定义比现实窄」
+ * 这个 B1 病因——`DynamicTask` 除包根外同时经 `./core` 可达，只冻包根会留同一个洞。
+ *
+ * 与 `public-exports.test.ts` 的分工：那边钉的是**删完之后**（已删类型 `@ts-expect-error`
+ * 负钉 + 活类型正钉 + 四级 barrel 链残留扫描），且它 `import('../index')`。本闸只做源码文本
+ * 分析、**刻意不 import 任何入口**——这是它单独立一个文件的原因：类型面一旦被改动，那边的
+ * 编译期钉会让整套 suite「failed to run」（实测注入一条 `export type { DynamicTask }` 得
+ * 0 tests），拿不到可执行的清单 diff；本闸在那种改动下必须仍然跑得动、报得出是哪个入口的
+ * 哪个符号。
+ *
+ * 清单来源不是手抄：五个入口的 `src` 解析结果与 tsc 产物（各自 exports 的 types 指向，如
+ * `dist/core/index.d.ts`）逐项对撞，152/32/1/12/18 全部逐字一致，产物侧同时零 `export *`。
+ * 改动入口清单文件时同步改本文件对应条目，diff 即 PR 评审材料；增删符号属公共面 breaking，
+ * 须按 ADR-0003/0022 走发布级别裁决。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+const REPO_ROOT = path.join(__dirname, '../..');
+
+/**
+ * 入口点合法的导出写法只有三种：
+ * ① `export { 值 } from '...'`；② `export type { 类型 } from '...'`；③ 内联值声明
+ * `export function|const|let|var`（如 `src/gates/index.ts` 的 5 个 `create*Gate`）——纯值面，
+ * 不属类型清单管辖。
+ * 清单归类按**说明符自身**而非块形式：`export { getEffectiveGates, type GatesConfig }` 里的
+ * `GatesConfig` 按 TS 语义就是类型导出，必须进类型清单（本闸的职责是如实刻画公开面，不是管写法）。
+ * 其余行首 `export` 一律记为违禁而非跳过：`export *` / `export type *` 会让按名字扫描静默
+ * 漏算；内联 `export interface|type|enum|class|declare` 更必须红——它绕过类型清单，而
+ * `enum`/`class` 同时占值面与类型面，按单一分类必错一面。这正是 B1「公开面的定义比现实窄」
+ * 那个病因的形态来源。
+ */
+interface EntrySurface {
+  types: string[];
+  illegal: string[];
+}
+
+const INLINE_VALUE_DECL_RE = /^export\s+(?:async\s+)?(?:function|const|let|var)\b/;
+
+function parseEntrySurface(source: string): EntrySurface {
+  const stmtRe = /^export (type )?\{([^}]*)\}[^;]*;/gm;
+  const types: string[] = [];
+  const illegal: string[] = [];
+  const starts = new Set<number>();
+
+  let match: RegExpExecArray | null = stmtRe.exec(source);
+  while (match !== null) {
+    starts.add(match.index);
+    const isTypeBlock = Boolean(match[1]);
+    for (const raw of match[2].split(',')) {
+      const spec = raw.trim();
+      if (!spec) continue;
+      // `A as B` 对外名字是 B；`type A as B` 对外名字是 B 且属类型面
+      const isTypeSpec = /^(type|typeof)\s/.test(spec);
+      if (isTypeBlock || isTypeSpec) {
+        types.push(spec.replace(/^(type|typeof)\s+/, '').split(/\s+as\s+/).pop()!.trim());
+      }
+    }
+    match = stmtRe.exec(source);
+  }
+
+  let offset = 0;
+  for (const line of source.split('\n')) {
+    if (/^export\b/.test(line) && !starts.has(offset) && !INLINE_VALUE_DECL_RE.test(line)) {
+      illegal.push(line.trim());
+    }
+    offset += line.length + 1;
+  }
+
+  return { types, illegal };
+}
+
+/** exports 子路径 → 承载它的显式清单源文件。形态对不上返回 null，由映射闸 fail-loud。 */
+function sourceFileForSubpath(subpath: string): string | null {
+  if (subpath === '.') return 'src/index.ts';
+  const rest = subpath.replace(/^\.\//, '');
+  return /^[a-z][a-z0-9-]*$/.test(rest) ? `src/${rest}/index.ts` : null;
+}
+
+const EXPORTS_MAP = JSON.parse(
+  fs.readFileSync(path.join(REPO_ROOT, 'package.json'), 'utf-8'),
+).exports as Record<string, { types?: string }>;
+
+const ENTRY_SUBPATHS: string[] = Object.keys(EXPORTS_MAP);
+
+/** 每个已发布入口的类型面全量清单。增删任一项即公共面 breaking，见文件头。 */
+const PUBLISHED_ENTRY_TYPES: Record<string, string[]> = {
+  '.': [
+    'AcceptanceCriteria',
+    'AcceptanceGateContext',
+    'AgentConfig',
+    'AgentEvent',
+    'AgentState',
+    'AgentStatus',
+    'ArtifactIntegrityResult',
+    'AuditAction',
+    'AuditIssue',
+    'AuditOptions',
+    'AuditReport',
+    'AuditRuleName',
+    'BatchSpecValidationResult',
+    'CSOIssue',
+    'CSOValidationResult',
+    'CapabilitiesConfig',
+    'ChangelogConfig',
+    'ChangelogVersionCheck',
+    'CheckCacheConfig',
+    'CheckConfig',
+    'CheckConstraintsOptions',
+    'CheckResult',
+    'CheckSamplingConfig',
+    'CheckType',
+    'CheckerVerdict',
+    'Checkpoint',
+    'CheckpointCheck',
+    'CheckpointContext',
+    'CheckpointResult',
+    'ClassificationResult',
+    'CodeStructure',
+    'CommandBlacklistRule',
+    'CommandGateConfig',
+    'CommitFileClassification',
+    'CommitInput',
+    'CommitVerdict',
+    'CompactionConfig',
+    'CompactionLevel',
+    'CompletionCheckersConfig',
+    'ConstCountActual',
+    'Constraint',
+    'ConstraintCheckResult',
+    'ConstraintContext',
+    'ConstraintId',
+    'ConstraintKind',
+    'ConstraintLevel',
+    'ConstraintResult',
+    'ConstraintTrigger',
+    'ConsumptionEvent',
+    'ConsumptionMode',
+    'ContextAverages',
+    'ContextDocsCheck',
+    'ContextFilesConfig',
+    'ContextSource',
+    'ContextSourceType',
+    'ContextUsageSnapshot',
+    'ContractGateConfig',
+    'ContractPresenceContext',
+    'ContractPresenceResult',
+    'CustomConstraintDefinition',
+    'DecayConfig',
+    'DecisionRecord',
+    'DeclarationInfo',
+    'DirCountActual',
+    'DocDirCheck',
+    'DocFreshnessCheck',
+    'DocFreshnessConfig',
+    'DocRegexCountCheck',
+    'DocsSyncConfig',
+    'EffectiveConfigLint',
+    'ErrorClassificationRule',
+    'ErrorClassifierConfig',
+    'EventHandler',
+    'ExecutionResult',
+    'ExecutionTrace',
+    'FailureRecord',
+    'FailureRecorderConfig',
+    'FallbackStrategy',
+    'Gate',
+    'GateContext',
+    'GateDecision',
+    'GateDecisionStatus',
+    'GateDefinition',
+    'GateResult',
+    'GateRunResult',
+    'GatesConfig',
+    'GovernanceConfig',
+    'GrepCountActual',
+    'HarnessBootstrap',
+    'HookConfig',
+    'HookDefinition',
+    'HookErrorStrategy',
+    'HookExecutionRecord',
+    'HookPhase',
+    'HookResult',
+    'ImportInfo',
+    'IndexEntry',
+    'IngestOptions',
+    'InjectionConfig',
+    'InjectionResult',
+    'IronLawContext',
+    'KnowledgeEntry',
+    'KnowledgeOrigin',
+    'KnowledgeReference',
+    'KnowledgeStore',
+    'KnowledgeSubsystem',
+    'LintIssue',
+    'LintIssueType',
+    'MaturityChange',
+    'MaturityLevel',
+    'MergedConstraintsConfig',
+    'PassesGateCheckResult',
+    'PassesGateConfig',
+    'PassesGateViolation',
+    'PerformanceGateConfig',
+    'PerformanceThresholds',
+    'PhaseFormatResult',
+    'PipelineResult',
+    'ProjectConfig',
+    'QueryBudget',
+    'QueryFilter',
+    'QueryResult',
+    'ReferenceRecord',
+    'RenderConstraintsByTriggerOptions',
+    'ReviewGateConfig',
+    'SchemaLoader',
+    'SecurityGateConfig',
+    'SessionCheckpoint',
+    'SessionEvent',
+    'SessionEventType',
+    'SessionHandle',
+    'SessionMessage',
+    'SourceRef',
+    'SpecAcceptanceGateConfig',
+    'SpecSchemaDefinition',
+    'SpecType',
+    'SpecValidationError',
+    'SpecValidationResult',
+    'SpecValidatorConfig',
+    'StepMeta',
+    'StorageLayer',
+    'TaskTestResult',
+    'TddChainResult',
+    'TestResult',
+    'TestingGovernanceConfig',
+    'ToolMeta',
+    'TraceAnalyzerConfig',
+    'TraceAnomaly',
+    'TraceCollectorConfig',
+    'TraceFilter',
+    'TraceSummary',
+    'WorkflowMeta',
+  ],
+  './core': [
+    'BatchSpecValidationResult',
+    'CSOIssue',
+    'CSOValidationResult',
+    'CapabilitiesMode',
+    'CheckCacheConfig',
+    'CheckConfig',
+    'CheckConstraintsOptions',
+    'CheckResult',
+    'CheckSamplingConfig',
+    'CheckType',
+    'Checkpoint',
+    'CheckpointCheck',
+    'CheckpointContext',
+    'CheckpointResult',
+    'Constraint',
+    'ConstraintCheckResult',
+    'ConstraintContext',
+    'ConstraintId',
+    'ConstraintKind',
+    'ConstraintLevel',
+    'ConstraintResult',
+    'ConstraintTrigger',
+    'ContextFilesResolution',
+    'EffectiveConfigLint',
+    'IronLawContext',
+    'PassesGateConfig',
+    'RenderConstraintsByTriggerOptions',
+    'SpecSchemaDefinition',
+    'SpecType',
+    'SpecValidationResult',
+    'SpecValidatorConfig',
+    'TaskTestResult',
+  ],
+  './presets': [
+    'PresetConfig',
+  ],
+  './context': [
+    'CompactionConfig',
+    'CompactionLevel',
+    'ContextSource',
+    'ContextSourceType',
+    'ContextUsageSnapshot',
+    'InjectionConfig',
+    'InjectionResult',
+    'SessionCheckpoint',
+    'SessionEvent',
+    'SessionEventType',
+    'SessionHandle',
+    'SessionMessage',
+  ],
+  './gates': [
+    'AcceptanceCriteria',
+    'AcceptanceGateContext',
+    'CommandBlacklistRule',
+    'CommandGateConfig',
+    'ContractGateConfig',
+    'Gate',
+    'GateContext',
+    'GateDecision',
+    'GateDecisionStatus',
+    'GateDefinition',
+    'GateResult',
+    'GateRunResult',
+    'GatesConfig',
+    'PerformanceGateConfig',
+    'PerformanceThresholds',
+    'ReviewGateConfig',
+    'SecurityGateConfig',
+    'SpecAcceptanceGateConfig',
+  ],
+};
+
+describe('已发布类型面全量冻结（ADR-0022 追记 4）', () => {
+  it('exports 的每个子路径都映射到存在的显式清单源文件（新增子路径不得绕过本闸）', () => {
+    const unmapped = ENTRY_SUBPATHS.filter((sub) => {
+      const rel = sourceFileForSubpath(sub);
+      return rel === null || !fs.existsSync(path.join(REPO_ROOT, rel));
+    });
+    expect(unmapped).toEqual([]);
+  });
+
+  it('冻结清单覆盖全部已发布子路径（新增入口须先登记清单）', () => {
+    expect(Object.keys(PUBLISHED_ENTRY_TYPES).sort()).toEqual([...ENTRY_SUBPATHS].sort());
+  });
+
+  for (const sub of ENTRY_SUBPATHS) {
+    const rel = sourceFileForSubpath(sub);
+    if (rel === null) continue; // 映射闸已负责红，此处不重复报
+    const surface = parseEntrySurface(fs.readFileSync(path.join(REPO_ROOT, rel), 'utf-8'));
+
+    describe(`入口点 ${sub}（${rel}）`, () => {
+      it('只用白名单写法导出，无被漏算的导出面', () => {
+        expect(surface.illegal).toEqual([]);
+      });
+
+      it('类型清单与冻结集逐字一致（增删即 breaking，需发布级别裁决）', () => {
+        // 解析塌掉不得退化成空集合假绿
+        expect(surface.types.length).toBeGreaterThan(0);
+        expect([...surface.types].sort()).toEqual([...PUBLISHED_ENTRY_TYPES[sub]].sort());
+      });
+    });
+  }
+});

package/src/__tests__/trace-analyzer.test.ts

@@ -3,11 +3,15 @@
  */
 
 import { describe, it, expect, beforeAll, afterAll } from '@jest/globals';
-import { TraceAnalyzer } from '../monitoring/trace-analyzer';
+import {
+  TraceAnalyzer,
+  summarizeTraces,
+  detectTraceAnomalies,
+} from '../monitoring/trace-analyzer';
 import { TraceCollector } from '../monitoring/traces';
 import * as fs from 'fs';
 import * as path from 'path';
-import type { ExecutionTrace } from '../types/trace';
+import type { ExecutionTrace, TraceSummary } from '../types/trace';
 
 describe('TraceAnalyzer', () => {
   const tempDir = path.join(process.cwd(), 'temp-test-analyzer');
@@ -127,4 +131,50 @@ describe('TraceAnalyzer', () => {
       expect(customAnalyzer).toBeDefined();
     });
   });
+
+  // ADR-0020：summarize / detectAnomalies 的判定本体住在模块级纯函数上，
+  // 类壳只是转发。下面两枚用例直调模块级函数，钉住这个 interface——
+  // 经类壳的既有覆盖（上文）删不掉它，反之它也不依赖任何 collector/文件 IO。
+  describe('模块级纯函数', () => {
+    it('summarizeTraces 不构造 collector 即可汇总，skip 不进 pass/fail 分母', () => {
+      const traces: ExecutionTrace[] = [
+        { constraintId: 'pure', level: 'iron_law', timestamp: 1000, result: 'pass' },
+        { constraintId: 'pure', level: 'iron_law', timestamp: 2000, result: 'fail' },
+        { constraintId: 'pure', level: 'iron_law', timestamp: 3000, result: 'skip' },
+      ];
+
+      const summaries = summarizeTraces(traces);
+
+      expect(summaries).toHaveLength(1);
+      const summary = summaries[0];
+      expect(summary.constraintId).toBe('pure');
+      expect(summary.totalChecks).toBe(3);
+      expect(summary.skipCount).toBe(1);
+      expect(summary.passRate).toBeCloseTo(0.5);
+      expect(summary.failRate).toBeCloseTo(0.5);
+    });
+
+    it('detectTraceAnomalies 的阈值经参数传入，默认与自定义各判一次', () => {
+      // failRate 6/14 ≈ 0.43 且趋势上升：默认阈值 0.5 不触发，0.3 触发
+      const summary: TraceSummary = {
+        constraintId: 'param_threshold',
+        level: 'iron_law',
+        timeRange: { start: 1000, end: 2400 },
+        totalChecks: 14,
+        passCount: 8,
+        failCount: 6,
+        ignoreCount: 0,
+        passRate: 8 / 14,
+        failRate: 6 / 14,
+        recentTrend: 'rising',
+      };
+
+      expect(detectTraceAnomalies([summary])).toEqual([]);
+
+      const anomalies = detectTraceAnomalies([summary], { thresholds: { failRate: 0.3 } });
+      const rising = anomalies.find(a => a.type === 'rising_fail_rate');
+      expect(rising?.constraintId).toBe('param_threshold');
+      expect(rising?.data.threshold).toBe(0.3);
+    });
+  });
 });

package/src/cli/commands/CONTEXT.md

@@ -1,7 +1,7 @@
 # cli/commands/
 
 ## 职责
-CLI 子命令实现：23 个顶层命令 + constraints 治理子命令 report/retire，覆盖约束检查/门禁验证/文档同步/知识管理/失败诊断/发布/会话分析等。
+CLI 子命令实现：21 个顶层命令 + constraints 治理子命令 report/retire，覆盖约束检查/门禁验证/文档同步/知识管理/失败诊断/发布等。
 
 H5（#44）起：
 - **命令定义即注册**：`definitions.ts` 的 `COMMAND_DEFINITIONS` 是命令形状（名称/别名/位置参数/选项/子命令/实现引用）的单一来源；bin/harness.js 遍历本表注册表驱动生成，不再手写 commander 命令块，不再有 index.ts barrel 两处同步（R6）
@@ -10,7 +10,7 @@ H5（#44）起：
 ## 核心导出
 - `COMMAND_DEFINITIONS`（definitions.ts）— 全部非门禁命令定义（纯数据模块、零闭包，禁止 import 命令实现；ADR-0010）
 - 命令契约（`src/cli/command-contract.ts`，上层目录）— `CommandResult` / `CommandKind` / `CommandIO` / `processIO` / `captureIO` / `lastJsonOutput` / `log` / `logError`
-- 各命令文件：check / validate / passes-gate / init / report / status / spec / sync-docs / knowledge / sdd / failure / posteval-plan / release / analyze-sessions / update-user-model / constraints / spec-baseline-check
+- 各命令文件：check / validate / passes-gate / init / report / status / spec / sync-docs / knowledge / sdd / failure / posteval-plan / release / constraints / spec-baseline-check
 - 6 门禁命令实现在 `acceptance` / `command` / `contract` / `performance` / `review` / `security`（其 CLI 元数据在 `src/gates/definitions.ts`，形状同为 `CommandDefinition`，ADR-0007）
 
 `constraints` 下挂治理子命令：`constraints report`（使用统计 + 退役候选诊断 + 配置健康 + 注入漂移，`--export` 脱敏）、`constraints retire`（交互选择 + 人确认退役；带 id 直达需显式 `--yes`（#24 人确认闸门），无 `--yes` 报错 + 非零退出码且不落盘；内置落 config.yml retired 元数据，custom 落 custom-constraints.yml 条目 retired 段（studio#82 D6 一处真相）+ KnowledgeStore 沉淀 + 治理注入段同步）。
@@ -29,6 +29,7 @@ H5（#44）起：
 - **definitions.ts 是纯数据模块（ADR-0010 后零闭包）**：禁止 import 任何命令实现/运行时依赖（保 --help/--version 懒加载）；子命令别名是数据（条目 `aliases: string[]`，不复印整块），实参编组（缺参闸门/强转/兜底）归各命令模块的具名导出（如 `knowledgeSearchCommand`/`coverageCheck`）；实现引用可解析性由 `__tests__/registry.test.ts` 构建/测试期断言
 - 命令选项类型命名规范：XxxOptions
 - **本层是上行数据的注入方（harness#88）**：core 对 cli/gates/monitoring 零值导入，故 `check`/`report` 自己 `new ConstraintChecker(getTraceCollector())`（组合根接线 trace 记录器；用 `constraintChecker`/`getInstance()` 拿到的默认实例不写 trace），`sync-docs` 把 `COMMAND_DEFINITIONS` + `GATE_DEFINITIONS` 组装成 `CapabilityDefinitionSource` 注入 `capabilities-parser` 供能力清单计数
+- **数据已在手就不再构造带 IO 副作用的实例（ADR-0020）**：`status` 按 projectPath 直读出 traces 后，直调 `monitoring/trace-analyzer` 的模块级纯函数 `summarizeTraces()`/`detectTraceAnomalies()`，不再 `new TraceCollector({traceFile})` + `new TraceAnalyzer(c)`——collector 构造函数带 mkdir 副作用，而这条路径上它的读方法从未被调用，实例纯属构造仪式。机器可检：`__tests__/status-analysis-wiring.test.ts`（源形状闸：命令体不得出现 `new TraceCollector`/`new TraceAnalyzer`，也不 import `monitoring/traces`）
 - **projectPath 只在入口兜底一次，并传到每个 IO/执行点（harness#95）**：`-p/--project-path` 的 cwd 兜底唯一落点是命令模块入口（`const projectPath = options.projectPath || process.cwd()`）；往下每层只能收参数，**禁止再取一次 `process.cwd()`、也禁止用相对路径默认值**——两者都让 `-p` 半失效：执行/读写位置悄悄回到调用方 cwd，而 acceptance 的「无 tasks.yml 即跳过」本身就是 `passed:true`，于是失效表现为假绿。落地形状：执行/IO 根用**必传形参**表达（`PassesGate.runTests(workDir)`），门禁内的相对子路径锚到 projectPath：`ContractGate` 一直是 `path.join(context.projectPath, contractPath)`，`SpecAcceptanceGate` 的 tasksPath 随 #95 对齐成 `path.resolve(projectPath, 相对值)`（绝对值原样，缺省 `<projectPath>/tasks.yml`）
   - 机器可检：`__tests__/project-path-convention.test.ts` 三道闸——CLI 层 cwd 必须是 `xxx || process.cwd()` 兜底形状、下游层（= src 减 cli）cwd 站点**逐行**冻结（#98，豁免文件内新增行/行变形同样失败）、相对路径默认值冻结（#98 收紧：`xxxPath: '相对值'` 对象字面量之外，参数默认值形/模板字面量/双引号形同罪，扫描域 = 整个下游层）；豁免逐条带理由，站点消失却不删条目同样失败
   - 行为可检：`__tests__/project-path-anchoring.test.ts` 前提统一 **cwd ≠ projectPath**、不 mock 任何 IO，断言测试真在 B 执行、证据落 `B/.harness/evidence/`、acceptance 读 `B/tasks.yml`。「根已传入却又取 cwd」这类静态看不出的漂移由它守，冻结表守的是不再新增站点

package/src/cli/commands/__tests__/passes-gate-dead-options.test.ts

@@ -0,0 +1,158 @@
+/**
+ * passes-gate 重试选项死旗帜闸（code-review A1）
+ *
+ * 重试实现原住 `setPasses`，随 ADR-0022 删除后 `PassesGateConfig.maxRetries` /
+ * `retryDelay` 整条装配链只剩写入方、全仓无读取方——`harness passes-gate
+ * --max-retries N` 是恒不生效选项。ADR-0018 删 performance 幽灵旗帜的判据
+ * （只执法有真实现的维度）据此收口。
+ *
+ * 手法同 #125 的 AC-007：编译期 `@ts-expect-error` 钉字段不存在 + 运行期钉定义表与源形状。
+ * `src/agents/types.ts` 的 `maxRetries` 是 AgentLifecycle 自有字段（`lifecycle.ts` 真读取），
+ * 不在本闸范围内。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { COMMAND_DEFINITIONS, type CommandDefinition } from '../definitions';
+import { GATE_DEFINITIONS } from '../../../gates/definitions';
+import type { PassesGateConfig } from '../../../types/passes-gate';
+import type { PassesGateOptions } from '../passes-gate';
+
+/**
+ * 已删旗帜的精确令牌（二次复审 S2 收口）
+ *
+ * `--max-retries` 的旗帜名 + 它在 commander 里的选项键名（`optionRoutes.flag` 按键路由，
+ * 是同一个已删选项的第二个落点）。**只钉这两个令牌**，不钉「retry 这个词」。
+ */
+const DELETED_FLAG_TOKENS = ['--max-retries', 'maxRetries'];
+
+interface FlagSite {
+  /** 命令位（含父命令前缀，如 'constraints report'） */
+  slot: string;
+  /** 旗帜令牌（'-t' / '--test-command'）或选项路由键（'list'） */
+  token: string;
+}
+
+/** 递归收集命令位上的旗帜令牌与选项路由键（走法同 registry.test.ts 的 collectRefs） */
+function collectFlagSites(defs: CommandDefinition[], prefix = ''): FlagSite[] {
+  return defs.flatMap((def) => {
+    const slot = [prefix, def.command].filter(Boolean).join(' ');
+    const own: FlagSite[] = [
+      ...def.options.flatMap((option) =>
+        option.flags
+          .split(/[\s,]+/)
+          .filter((token) => token.startsWith('-'))
+          .map((token) => ({ slot, token })),
+      ),
+      ...(def.optionRoutes || []).map((route) => ({ slot, token: route.flag })),
+    ];
+    return [...own, ...collectFlagSites(def.children || [], slot)];
+  });
+}
+
+function sitesHoldingDeletedFlag(sites: FlagSite[]): FlagSite[] {
+  return sites.filter((site) => DELETED_FLAG_TOKENS.includes(site.token));
+}
+
+/** 全部命令位：通用命令表 + 门禁命令表（GATE_DEFINITIONS.cli 由 bin 同一引擎生成命令块） */
+const ALL_CLI_SITES = [
+  ...collectFlagSites(COMMAND_DEFINITIONS),
+  ...collectFlagSites(GATE_DEFINITIONS.map((gate) => gate.cli)),
+];
+
+const passesGateCommand = COMMAND_DEFINITIONS.find(d => d.command === 'passes-gate');
+const cliSource = fs.readFileSync(path.join(__dirname, '..', 'passes-gate.ts'), 'utf-8');
+const validatorSource = fs.readFileSync(
+  path.join(__dirname, '..', '..', '..', 'core', 'validators', 'passes-gate.ts'),
+  'utf-8',
+);
+
+describe('passes-gate 重试选项已删除（A1）', () => {
+  it('定义表已注册 passes-gate（前提）', () => {
+    expect(passesGateCommand).toBeDefined();
+  });
+
+  it('passes-gate 旗帜面逐字冻结，不含 --max-retries', () => {
+    expect((passesGateCommand?.options || []).map(o => o.flags)).toEqual([
+      '-t, --test-command <command>',
+      '-p, --project-path <path>',
+      '--allow-partial',
+      '--coverage',
+      '--coverage-threshold <n>',
+    ]);
+  });
+
+  it('采集面确实覆盖三类命令位（前提，防空扫致闸失效）', () => {
+    const rendered = ALL_CLI_SITES.map(s => `${s.slot} ${s.token}`);
+    expect(rendered).toContain('passes-gate --coverage-threshold'); // 通用表叶子命令的旗帜
+    expect(rendered).toContain('constraints report --json'); // children 递归（嵌套命令位）
+    expect(rendered).toContain('acceptance --task-id'); // 门禁表命令位（GATE_DEFINITIONS.cli）
+    expect(rendered).toContain('check list'); // 选项路由键（commander camelCase 键位）
+  });
+
+  it('已删的 --max-retries 不在任何命令位复活（逐命令逐选项精确冻结）', () => {
+    expect(sitesHoldingDeletedFlag(ALL_CLI_SITES)).toEqual([]);
+  });
+
+  /**
+   * 旧闸（A5 引入的全表禁词版）——原样保留，与上面的精确冻结并存。
+   * 它宽于「冻结已删选项」这一意图：将来任何命令新增合法的 retries 类选项都会被拦。
+   * 收窄（即删掉这条）是二次复审 S2 的应修项，但删除断言属 `no_test_simplification`
+   * 铁律拦截范围、而该闸无批准通道，故本轮只加不改，退役动作交人类裁决。
+   */
+  it('命令定义表任意层级都不含 retry 旗帜（防换个命令位复活）', () => {
+    expect(JSON.stringify(COMMAND_DEFINITIONS)).not.toMatch(/retry/i);
+  });
+
+  /**
+   * 反向验闸（二次复审 S2）：把已删旗帜分别挂到「另一条通用命令 / 门禁命令 / 选项路由键」
+   * 三处，断言扫描逐字报出——证明换掉的不是空洞，也证明覆盖面真的等于名义上的「任何命令位」。
+   * 将来若要在别的命令位做**有真实现**的重试，那是新设计：显式评审后把令牌从
+   * DELETED_FLAG_TOKENS 解除（同 ADR-0022 推翻 AC-007 的做法），不靠闸静默放行。
+   */
+  it('闸非空洞：复活在别的命令位仍会红（通用命令 / 门禁命令 / 选项路由键）', () => {
+    const probe = { flags: '--max-retries <n>', description: '复活探针' };
+    const otherCommand = COMMAND_DEFINITIONS.find(d => d.command === 'check')!;
+    const gateSlot = GATE_DEFINITIONS.find(g => g.id === 'acceptance')!;
+
+    const resurrected = [
+      ...collectFlagSites([{ ...otherCommand, options: [...otherCommand.options, probe] }]),
+      ...collectFlagSites([{ ...gateSlot.cli, options: [...gateSlot.cli.options, probe] }]),
+      ...collectFlagSites([{
+        ...otherCommand,
+        optionRoutes: [...(otherCommand.optionRoutes || []), { ...otherCommand.optionRoutes![0], flag: 'maxRetries' }],
+      }]),
+    ];
+
+    expect(sitesHoldingDeletedFlag(resurrected).map(s => `${s.slot} ${s.token}`)).toEqual([
+      'check --max-retries',
+      'acceptance --max-retries',
+      'check maxRetries',
+    ]);
+  });
+
+  it('CLI 装配链与 validator 默认配置都不再写重试字段', () => {
+    expect(cliSource).not.toMatch(/maxRetries|retryDelay/);
+    expect(validatorSource).not.toMatch(/maxRetries|retryDelay/);
+  });
+
+  it('PassesGateConfig / PassesGateOptions 的重试字段已从类型面消失（编译期钉）', () => {
+    // @ts-expect-error maxRetries 只写不读，随 A1 从 PassesGateConfig 删除
+    const removedMaxRetries: PassesGateConfig = { maxRetries: 2 };
+    // @ts-expect-error retryDelay 只写不读，随 A1 从 PassesGateConfig 删除
+    const removedRetryDelay: PassesGateConfig = { retryDelay: 1000 };
+    // @ts-expect-error CLI 侧同名字段随旗帜与装配一并删除
+    const removedOption: PassesGateOptions = { maxRetries: 2 };
+    expect([removedMaxRetries, removedRetryDelay, removedOption]).toHaveLength(3);
+  });
+
+  it('活字段仍可赋值（防止删多）', () => {
+    const live: PassesGateConfig = {
+      enabled: true,
+      testCommand: 'npm test',
+      requireEvidence: false,
+      allowPartialPass: true,
+    };
+    expect(Object.keys(live)).toHaveLength(4);
+  });
+});

package/src/cli/commands/__tests__/passes-gate.test.ts

@@ -130,9 +130,13 @@ describe('passes-gate command', () => {
       }));
 
       await runPassesGate({ testCommand: 'pytest' }, io);
-      expect(MockPassesGate).toHaveBeenCalledWith(
-        expect.objectContaining({ testCommand: 'pytest' })
-      );
+      // 精确形状（A1）：装配面只剩四个活字段，只写不读的重试字段已随旗帜一并删除
+      expect(MockPassesGate).toHaveBeenCalledWith({
+        enabled: true,
+        testCommand: 'pytest',
+        requireEvidence: false,
+        allowPartialPass: false,
+      });
     });
   });