@dommaker/harness 0.18.0 → 1.0.0

package/src/cli/commands/__tests__/analyze-sessions.test.ts

@@ -0,0 +1,178 @@
+/**
+ * analyze-sessions 命令测试（O6）
+ *
+ * Seam：analyzeSessions(options) 公开入口。
+ * 隔离面：
+ *   - os.homedir → 测试临时目录（memory 规则库落 TEST_HOME）
+ *   - readTranscriptSessions → fixture 会话（extractCorrectionMatches/tokenize 等纯函数保持真实）
+ *   - CLAUDE_TRANSCRIPTS_DIR → 测试临时目录（决定 transcripts 目录是否存在）
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { analyzeSessions } from '../analyze-sessions';
+import { readTranscriptSessions, type MinedSession } from '../../session-mining';
+
+const TEST_HOME = '/tmp/harness-analyze-test-home';
+
+jest.mock('os', () => ({
+  ...jest.requireActual('os'),
+  homedir: () => '/tmp/harness-analyze-test-home',
+}));
+
+jest.mock('../../session-mining', () => ({
+  ...jest.requireActual('../../session-mining'),
+  readTranscriptSessions: jest.fn(),
+}));
+
+jest.mock('chalk', () => {
+  const id = (s: string) => s;
+  const chalkFn = Object.assign(id, {
+    gray: id,
+    blue: id,
+    green: id,
+    yellow: id,
+    cyan: id,
+    bold: id,
+    red: id,
+  });
+  return {
+    __esModule: true,
+    default: chalkFn,
+    gray: id,
+    blue: id,
+    green: id,
+    yellow: id,
+    cyan: id,
+    bold: id,
+    red: id,
+  };
+});
+
+const mockReadTranscriptSessions = readTranscriptSessions as jest.MockedFunction<
+  typeof readTranscriptSessions
+>;
+
+const TRANSCRIPTS_DIR = path.join(TEST_HOME, 'transcripts');
+
+function mkSession(partial: Partial<MinedSession> = {}): MinedSession {
+  return {
+    id: 'session-1',
+    date: '2026-08-15',
+    mtimeMs: Date.now(),
+    turns: [
+      { role: 'user', content: '我不是说要用中文吗' },
+      { role: 'assistant', content: '收到，改用中文' },
+    ],
+    toolCalls: [],
+    ...partial,
+  };
+}
+
+function lastJsonOutput(consoleSpy: jest.SpyInstance): Record<string, unknown> {
+  const jsonLine = consoleSpy.mock.calls.map(c => c[0]).join('\n');
+  return JSON.parse(jsonLine);
+}
+
+describe('analyze-sessions command', () => {
+  let consoleSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    fs.rmSync(TEST_HOME, { recursive: true, force: true });
+    fs.mkdirSync(path.join(TEST_HOME, '.claude', 'projects', '-root-projects', 'memory'), { recursive: true });
+    fs.mkdirSync(TRANSCRIPTS_DIR, { recursive: true });
+    process.env.CLAUDE_TRANSCRIPTS_DIR = TRANSCRIPTS_DIR;
+    consoleSpy = jest.spyOn(console, 'log').mockImplementation();
+  });
+
+  afterEach(() => {
+    consoleSpy.mockRestore();
+    delete process.env.CLAUDE_TRANSCRIPTS_DIR;
+  });
+
+  test('transcripts 目录不存在：提示 No transcripts directory found', async () => {
+    process.env.CLAUDE_TRANSCRIPTS_DIR = path.join(TEST_HOME, 'missing-dir');
+
+    await analyzeSessions({});
+
+    expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('No transcripts directory found'));
+    expect(mockReadTranscriptSessions).not.toHaveBeenCalled();
+  });
+
+  test('窗口内无会话：提示 No sessions found（默认最近 7 天）', async () => {
+    mockReadTranscriptSessions.mockReturnValue([
+      mkSession({ id: 'old', mtimeMs: Date.now() - 30 * 86_400_000 }),
+    ]);
+
+    await analyzeSessions({});
+
+    expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('No sessions found in the last 7 days'));
+  });
+
+  test('--days 1：只统计最近 1 天（mtimeMs 窗口过滤）', async () => {
+    mockReadTranscriptSessions.mockReturnValue([
+      mkSession({ id: 'today' }),
+      mkSession({ id: 'two-days-ago', mtimeMs: Date.now() - 2 * 86_400_000 }),
+    ]);
+
+    await analyzeSessions({ days: 1 });
+
+    expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Analyzing 1 sessions (last 1 days)'));
+  });
+
+  test('缺省 --days：窗口为 7 天，两天前会话仍计入', async () => {
+    mockReadTranscriptSessions.mockReturnValue([
+      mkSession({ id: 'today' }),
+      mkSession({ id: 'two-days-ago', mtimeMs: Date.now() - 2 * 86_400_000 }),
+    ]);
+
+    await analyzeSessions({});
+
+    expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Analyzing 2 sessions (last 7 days)'));
+  });
+
+  test('--json：纠正句跨 3 会话聚合为 correction 候选', async () => {
+    mockReadTranscriptSessions.mockReturnValue([
+      mkSession({ id: 's1' }),
+      mkSession({ id: 's2' }),
+      mkSession({ id: 's3' }),
+    ]);
+
+    await analyzeSessions({ json: true });
+
+    const output = lastJsonOutput(consoleSpy);
+    expect(output.sessions).toBe(3);
+    expect(output.corrections).toBe(3);
+    expect(output.candidates).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          source: 'correction',
+          frequency: 3,
+          pattern: '我不是说',
+        }),
+      ]),
+    );
+  });
+
+  test('--json：跨会话重复概念产出 ngram 候选', async () => {
+    const ngramText = { role: 'user', content: '数据库迁移方案的详细讨论' };
+    mockReadTranscriptSessions.mockReturnValue([
+      mkSession({
+        id: 's1',
+        turns: [ngramText, { role: 'assistant', content: '好的' }],
+      }),
+      mkSession({
+        id: 's2',
+        turns: [ngramText, { role: 'assistant', content: '明白' }],
+      }),
+    ]);
+
+    await analyzeSessions({ json: true });
+
+    const output = lastJsonOutput(consoleSpy);
+    const ngramCandidates = (output.candidates as Array<{ source: string }>)
+      .filter(c => c.source === 'ngram');
+    expect(ngramCandidates.length).toBeGreaterThan(0);
+  });
+});

package/src/cli/commands/__tests__/check-drift.test.ts

@@ -16,7 +16,6 @@ import { getEffectiveConstraints } from '../../../core/effective-constraints';
 
 jest.mock('../../../core/constraints/checker', () => ({
   constraintChecker: {
-    setCustomConfig: jest.fn(),
     setTraceRecorder: jest.fn(),
     checkConstraints: jest.fn(),
   },
@@ -58,9 +57,7 @@ describe('check 命令注入漂移警告', () => {
       passed: true,
       ironLaws: [],
       guidelines: [],
-      tips: [],
       warningCount: 0,
-      tipCount: 0,
     });
   });
 

package/src/cli/commands/__tests__/check-skip-output.test.ts

@@ -29,7 +29,6 @@ jest.mock('child_process', () => ({
 // Mock constraintChecker
 jest.mock('../../../core/constraints/checker', () => ({
   constraintChecker: {
-    setCustomConfig: jest.fn(),
     setTraceRecorder: jest.fn(),
     checkConstraints: jest.fn(),
   },
@@ -89,9 +88,7 @@ describe('check 命令 skip 输出', () => {
         { id: 'law_skip', level: 'iron_law', satisfied: true, skipped: true, checkedAt: new Date(), constraint: fakeConstraint('law_skip', 'iron_law') },
       ],
       guidelines: [],
-      tips: [],
       warningCount: 0,
-      tipCount: 0,
     });
 
     await check({ preset: 'default', staged: false });
@@ -113,9 +110,7 @@ describe('check 命令 skip 输出', () => {
         { id: 'g_pass', level: 'guideline', satisfied: true, checkedAt: new Date(), constraint: fakeConstraint('g_pass', 'guideline') },
         { id: 'g_skip', level: 'guideline', satisfied: true, skipped: true, checkedAt: new Date(), constraint: fakeConstraint('g_skip', 'guideline') },
       ],
-      tips: [],
       warningCount: 0,
-      tipCount: 0,
     });
 
     await check({ preset: 'default', staged: false });

package/src/cli/commands/__tests__/check.test.ts

@@ -40,7 +40,6 @@ jest.mock('child_process', () => ({
 // Mock constraintChecker
 jest.mock('../../../core/constraints/checker', () => ({
   constraintChecker: {
-    setCustomConfig: jest.fn(),
     setTraceRecorder: jest.fn(),
     checkConstraints: jest.fn(),
   },
@@ -89,9 +88,7 @@ describe('check command', () => {
         passed: true,
         ironLaws: [{ id: 'test', level: 'iron_law', satisfied: true, checkedAt: new Date(), constraint: { kind: 'check' as const, id: 'test', rule: 'test', message: 'test', level: 'iron_law', trigger: 'code_implementation', enforcement: 'checkpoint-required' } }],
         guidelines: [],
-        tips: [],
         warningCount: 0,
-        tipCount: 0,
       });
 
       await check({ preset: 'default', staged: false });
@@ -103,9 +100,7 @@ describe('check command', () => {
         passed: false,
         ironLaws: [{ id: 'no_bypass_checkpoint', level: 'iron_law', satisfied: false, checkedAt: new Date(), constraint: { kind: 'check' as const, id: 'no_bypass_checkpoint', rule: 'test', message: 'test', level: 'iron_law', trigger: 'code_implementation', enforcement: 'checkpoint-required' } }],
         guidelines: [],
-        tips: [],
         warningCount: 0,
-        tipCount: 0,
       });
 
       const mockExit = jest.spyOn(process, 'exit').mockImplementation(() => undefined as never);
@@ -120,9 +115,7 @@ describe('check command', () => {
         passed: false,
         ironLaws: [],
         guidelines: [{ id: 'test_guideline', level: 'guideline', satisfied: false, checkedAt: new Date(), constraint: { kind: 'check' as const, id: 'test_guideline', rule: 'test', message: 'test', level: 'guideline', trigger: 'code_implementation', enforcement: 'warning' } }],
-        tips: [],
         warningCount: 1,
-        tipCount: 0,
       });
 
       await check({ preset: 'default', staged: false });
@@ -141,38 +134,23 @@ describe('check command', () => {
         passed: true,
         ironLaws: [],
         guidelines: [],
-        tips: [],
         warningCount: 0,
-        tipCount: 0,
       });
 
       await check({ preset: 'default', staged: false, projectPath: '/project' });
-      expect(mockChecker.setCustomConfig).toHaveBeenCalled();
+      expect(mockChecker.checkConstraints).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.objectContaining({ disabled: ['disabled_constraint'] })
+      );
       expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('已禁用约束'));
     });
 
-    it('应该显示提示信息', async () => {
-      mockChecker.checkConstraints.mockResolvedValue({
-        passed: true,
-        ironLaws: [],
-        guidelines: [],
-        tips: [{ id: 'test_tip', level: 'tip', satisfied: false, checkedAt: new Date(), constraint: { kind: 'check' as const, id: 'test_tip', rule: 'test', message: 'test tip', level: 'tip', trigger: 'code_implementation', enforcement: 'info' } }],
-        warningCount: 0,
-        tipCount: 1,
-      });
-
-      await check({ preset: 'default', staged: false });
-      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('提示'));
-    });
-
     it('应该显示通过的指导原则', async () => {
       mockChecker.checkConstraints.mockResolvedValue({
         passed: true,
         ironLaws: [],
         guidelines: [{ id: 'test_guideline', level: 'guideline', satisfied: true, checkedAt: new Date(), constraint: { kind: 'check' as const, id: 'test_guideline', rule: 'test', message: 'test', level: 'guideline', trigger: 'code_implementation', enforcement: 'warning' } }],
-        tips: [],
         warningCount: 0,
-        tipCount: 0,
       });
 
       await check({ preset: 'default', staged: false });
@@ -186,9 +164,7 @@ describe('check command', () => {
         passed: true,
         ironLaws: [],
         guidelines: [],
-        tips: [],
         warningCount: 0,
-        tipCount: 0,
       });
 
       await check({ preset: 'default', staged: true });
@@ -201,9 +177,7 @@ describe('check command', () => {
         passed: true,
         ironLaws: [],
         guidelines: [],
-        tips: [],
         warningCount: 0,
-        tipCount: 0,
       });
 
       await check({ preset: 'default', staged: false });
@@ -216,9 +190,7 @@ describe('check command', () => {
         passed: true,
         ironLaws: [],
         guidelines: [],
-        tips: [],
         warningCount: 0,
-        tipCount: 0,
       });
 
       await check({ preset: 'default', staged: true });
@@ -231,9 +203,7 @@ describe('check command', () => {
         passed: true,
         ironLaws: [],
         guidelines: [],
-        tips: [],
         warningCount: 0,
-        tipCount: 0,
       });
 
       await check({ preset: 'default', staged: false });
@@ -244,7 +214,7 @@ describe('check command', () => {
     it('应该检测 module_modification 触发条件（.ts 文件）', async () => {
       mockExecAsync.mockResolvedValue({ stdout: 'src/foo.ts\nsrc/bar.tsx\n', stderr: '' });
       mockChecker.checkConstraints.mockResolvedValue({
-        passed: true, ironLaws: [], guidelines: [], tips: [], warningCount: 0, tipCount: 0,
+        passed: true, ironLaws: [], guidelines: [], warningCount: 0,
       });
 
       // Mock filesystem so detectSourceRoots finds src/ as a source root
@@ -267,7 +237,7 @@ describe('check command', () => {
     it('应该检测 module_modification 触发条件（.js 文件）', async () => {
       mockExecAsync.mockResolvedValue({ stdout: 'src/foo.js\nsrc/bar.jsx\n', stderr: '' });
       mockChecker.checkConstraints.mockResolvedValue({
-        passed: true, ironLaws: [], guidelines: [], tips: [], warningCount: 0, tipCount: 0,
+        passed: true, ironLaws: [], guidelines: [], warningCount: 0,
       });
 
       // Mock filesystem so detectSourceRoots finds src/ as a source root
@@ -290,7 +260,7 @@ describe('check command', () => {
     it('应该检测 file_modification 触发条件（非 src/ 目录）', async () => {
       mockExecAsync.mockResolvedValue({ stdout: 'docs/bar.md\n', stderr: '' });
       mockChecker.checkConstraints.mockResolvedValue({
-        passed: true, ironLaws: [], guidelines: [], tips: [], warningCount: 0, tipCount: 0,
+        passed: true, ironLaws: [], guidelines: [], warningCount: 0,
       });
 
       await check({ preset: 'default', staged: false });
@@ -304,9 +274,7 @@ describe('check command', () => {
         passed: true,
         ironLaws: [],
         guidelines: [],
-        tips: [],
         warningCount: 0,
-        tipCount: 0,
       });
 
       // Mock filesystem so detectSourceRoots finds src/ as a source root
@@ -332,9 +300,7 @@ describe('check command', () => {
         passed: true,
         ironLaws: [],
         guidelines: [],
-        tips: [],
         warningCount: 0,
-        tipCount: 0,
       });
 
       await check({ preset: 'default', staged: false, trigger: 'code_implementation' });
@@ -361,9 +327,7 @@ describe('check command', () => {
           },
         }],
         guidelines: [],
-        tips: [],
         warningCount: 0,
-        tipCount: 0,
       });
 
       const mockExit = jest.spyOn(process, 'exit').mockImplementation(() => undefined as never);
@@ -393,43 +357,13 @@ describe('check command', () => {
             enforcement: 'warning',
           },
         }],
-        tips: [],
         warningCount: 1,
-        tipCount: 0,
       });
 
       await check({ preset: 'default', staged: false });
       expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('prefer_composition'));
     });
 
-    it('应该显示提示的约束详情', async () => {
-      mockExecAsync.mockResolvedValue({ stdout: '', stderr: '' });
-      mockChecker.checkConstraints.mockResolvedValue({
-        passed: true,
-        ironLaws: [],
-        guidelines: [],
-        tips: [{
-          id: 'consider_reuse',
-          level: 'tip',
-          satisfied: false,
-          checkedAt: new Date(),
-          constraint: {
-            kind: 'check' as const,
-            id: 'consider_reuse',
-            rule: 'CONSIDER REUSE',
-            message: '考虑复用',
-            level: 'tip',
-            trigger: 'code_implementation',
-            enforcement: 'info',
-          },
-        }],
-        warningCount: 0,
-        tipCount: 1,
-      });
-
-      await check({ preset: 'default', staged: false });
-      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('consider_reuse'));
-    });
   });
 
   describe('getSmartHint (通过 check 间接测试)', () => {
@@ -439,9 +373,7 @@ describe('check command', () => {
         passed: true,
         ironLaws: [],
         guidelines: [],
-        tips: [],
         warningCount: 0,
-        tipCount: 0,
       });
     });
 

package/src/cli/commands/__tests__/registry.test.ts

@@ -0,0 +1,201 @@
+/**
+ * 命令注册表闭环测试（H5：命令定义即注册 + per-command 懒加载）
+ *
+ * - 定义表内每个实现引用（module+export）都必须可解析（构建/测试期断言，
+ *   取代 commands barrel 的编译期保护——R6 消灭手工同步后的闭环兜底）
+ * - definitions 是纯数据模块：require 它不加载任何命令实现（保 --help/--version 懒加载）
+ * - 命令面与 CAPABILITIES.md 的 24 顶层命令一致（防误删回归）
+ * - bin/harness.js 端到端冒烟（dist 存在时）：--version/--help 零命令实现模块，
+ *   单命令执行只加载该命令模块（O2 per-command 懒加载）
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+import { COMMAND_DEFINITIONS, type CommandDefinition, type CommandImplRef } from '../definitions';
+import { GATE_DEFINITIONS } from '../../../gates/definitions';
+
+function collectRefs(defs: CommandDefinition[]): CommandImplRef[] {
+  const refs: CommandImplRef[] = [];
+  const walk = (def: CommandDefinition) => {
+    if (def.action) refs.push(def.action);
+    if (def.subcommands) {
+      for (const entry of Object.values(def.subcommands)) refs.push(entry.impl);
+    }
+    if (def.optionRoutes) {
+      for (const route of def.optionRoutes) refs.push(route.impl);
+    }
+    for (const child of def.children || []) walk(child);
+  };
+  for (const def of defs) walk(def);
+  return refs;
+}
+
+const EXPECTED_TOP_LEVEL_COMMANDS = [
+  'check', 'validate', 'passes-gate', 'init', 'report', 'status', 'spec',
+  'sync-docs', 'knowledge', 'sdd', 'failure', 'posteval-plan',
+  'update-user-model', 'release', 'analyze-sessions', 'constraints',
+  'doc-freshness-check', 'spec-baseline-check',
+  // 6 门禁命令（GATE_DEFINITIONS 驱动）
+  'acceptance', 'command', 'contract', 'performance', 'review', 'security',
+];
+
+describe('命令注册表闭环', () => {
+  it('definitions 是纯数据模块：加载时不引入任何命令实现', () => {
+    const loaded = Object.keys(require.cache)
+      .filter(k => k.includes('/cli/commands/') && k.endsWith('.ts') && !k.includes('__tests__'));
+    expect(loaded).toEqual([
+      expect.stringContaining('/cli/commands/definitions.ts'),
+    ]);
+  });
+
+  it('全部实现引用可解析（module 存在且 export 是函数）', () => {
+    const refs = collectRefs(COMMAND_DEFINITIONS);
+    for (const def of GATE_DEFINITIONS) {
+      refs.push(def.cli.action);
+      for (const entry of Object.values(def.cli.subcommands || {})) refs.push(entry);
+    }
+    expect(refs.length).toBeGreaterThan(0);
+
+    for (const ref of refs) {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const mod = require('../' + ref.module);
+      if (typeof mod[ref.export] !== 'function') {
+        throw new Error(`实现引用 ${ref.module}.${ref.export} 不存在或不是函数`);
+      }
+    }
+  });
+
+  it('顶层命令面与预期 24 命令一致（含 6 门禁）', () => {
+    const names = [
+      ...COMMAND_DEFINITIONS.map(d => d.command.split(' ')[0]),
+      ...GATE_DEFINITIONS.map(d => d.cli.command.split(' ')[0]),
+    ];
+    expect(new Set(names).size).toBe(names.length);
+    expect(names.sort()).toEqual([...EXPECTED_TOP_LEVEL_COMMANDS].sort());
+  });
+
+  it('命令定义无重复注册名', () => {
+    const names = COMMAND_DEFINITIONS.map(d => d.command);
+    expect(new Set(names).size).toBe(names.length);
+  });
+
+  it('全部命令定义的路由构造可执行（mapActionArgs/subcommands.args/optionRoutes.args/afterRun 冒烟）', () => {
+    const exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => undefined as never);
+    try {
+      const walk = (def: CommandDefinition) => {
+        if (def.mapActionArgs) {
+          def.mapActionArgs(['positional'], {});
+          def.mapActionArgs([], {});
+        }
+        for (const entry of Object.values(def.subcommands || {})) {
+          if (entry.args) {
+            entry.args(['positional'], {});
+            entry.args([], {});
+          }
+        }
+        for (const route of def.optionRoutes || []) {
+          if (route.args) {
+            route.args([], {});
+            route.args(['positional'], {});
+          }
+        }
+        if (def.afterRun) {
+          def.afterRun(true, {});
+          def.afterRun(false, { check: true });
+        }
+        for (const child of def.children || []) walk(child);
+      };
+      for (const def of COMMAND_DEFINITIONS) walk(def);
+      // sync-docs --check 失败路径确实会请求退出
+      expect(exitSpy).toHaveBeenCalled();
+    } finally {
+      exitSpy.mockRestore();
+    }
+  });
+});
+
+const repoRoot = path.join(__dirname, '..', '..', '..', '..');
+const distBin = path.join(repoRoot, 'bin', 'harness.js');
+const distCommands = path.join(repoRoot, 'dist', 'cli', 'commands');
+const hasDist = fs.existsSync(distCommands);
+
+/**
+ * 经 NODE_OPTIONS=--require 预加载探针 spawn bin（进程退出时打印加载的
+ * 命令实现模块清单）。不用 node -e（commander 在 -e 下走 eval 分支，
+ * argv 解析不同，会误判位置参数）。
+ */
+function runWithModuleProbe(argv: string[]): { status: number | null; implModules: string[]; stdout: string; stderr: string } {
+  const probeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-lazy-probe-'));
+  const probeFile = path.join(probeDir, 'probe.js');
+  fs.writeFileSync(probeFile, [
+    `process.on('exit', () => {`,
+    `  const impls = Object.keys(require.cache).filter(k => /dist[\\\\/]cli[\\\\/]commands[\\\\/]/.test(k) && !/definitions\\.js/.test(k)).sort();`,
+    `  console.error('IMPL_MODULES=' + impls.join(','));`,
+    `});`,
+  ].join('\n'));
+  try {
+    const r = spawnSync(process.execPath, [distBin, ...argv], {
+      cwd: repoRoot,
+      encoding: 'utf-8',
+      timeout: 30000,
+      env: { ...process.env, NODE_OPTIONS: `--require ${probeFile}` },
+    });
+    const match = r.stderr.match(/IMPL_MODULES=(.*)/);
+    return {
+      status: r.status,
+      implModules: match && match[1] ? match[1].split(',').filter(Boolean) : [],
+      stdout: r.stdout,
+      stderr: r.stderr,
+    };
+  } finally {
+    fs.rmSync(probeDir, { recursive: true, force: true });
+  }
+}
+
+const smoke = hasDist ? describe : describe.skip;
+
+smoke('bin/harness.js 端到端（dist 存在时）', () => {
+  it('--version：退出 0，零命令实现模块加载', () => {
+    const r = runWithModuleProbe(['--version']);
+    expect(r.status).toBe(0);
+    expect(r.implModules).toEqual([]);
+  });
+
+  it('--help：退出 0，零命令实现模块加载', () => {
+    const r = runWithModuleProbe(['--help']);
+    expect(r.status).toBe(0);
+    expect(r.implModules).toEqual([]);
+  });
+
+  it('harness constraints --json：只加载 constraints 命令模块', () => {
+    const r = runWithModuleProbe(['constraints', '--json']);
+    expect(r.status).toBe(0);
+    expect(r.implModules).toEqual([
+      expect.stringContaining('/dist/cli/commands/constraints.js'),
+    ]);
+  });
+
+  it('harness check --list：只加载 check 命令模块（optionRoutes）', () => {
+    const r = runWithModuleProbe(['check', '--list']);
+    expect(r.status).toBe(0);
+    expect(r.implModules).toEqual([
+      expect.stringContaining('/dist/cli/commands/check.js'),
+    ]);
+  });
+
+  it('harness acceptance：只加载 acceptance 命令模块（门禁注册表）', () => {
+    const r = runWithModuleProbe(['acceptance', '--check-all']);
+    expect(r.status).toBe(0);
+    expect(r.implModules).toEqual([
+      expect.stringContaining('/dist/cli/commands/acceptance.js'),
+    ]);
+  });
+
+  it('未知子命令报错退出（knowledge 兜底行为保留）', () => {
+    const r = runWithModuleProbe(['knowledge', 'bogus']);
+    expect(r.status).toBe(1);
+    expect(r.stderr).toContain('未知子命令: bogus');
+  });
+});