@dommaker/harness 1.3.0 → 1.4.0

package/src/cli/commands/__tests__/posteval-plan.test.ts

@@ -3,15 +3,18 @@
  */
 
 import * as fs from 'fs';
+import { captureIO, type CapturingIO } from '../../command-contract';
 import * as path from 'path';
 
+let io: CapturingIO;
+beforeEach(() => {
+  io = captureIO();
+});
+
 describe('postevalPlan', () => {
   jest.setTimeout(30000); // Retry-based tests with exponential backoff need longer timeout
   const tempDir = path.join(process.cwd(), 'temp-test-posteval');
   const planPath = path.join(tempDir, 'plan.md');
-  let consoleErrorSpy: jest.SpyInstance;
-  let consoleLogSpy: jest.SpyInstance;
-  let mockExit: jest.SpyInstance;
   let originalFetch: typeof fetch;
   let originalEnv: NodeJS.ProcessEnv;
 
@@ -34,19 +37,11 @@ describe('postevalPlan', () => {
     originalEnv = { ...process.env };
     delete process.env.API_PORT;
     delete process.env.POSTEVAL_GRACE_MS;
-    consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation();
-    consoleLogSpy = jest.spyOn(console, 'log').mockImplementation();
-    mockExit = jest.spyOn(process, 'exit').mockImplementation((() => {
-      // Don't actually exit
-    }) as any);
   });
 
   afterEach(() => {
     global.fetch = originalFetch;
     process.env = originalEnv;
-    consoleErrorSpy.mockRestore();
-    consoleLogSpy.mockRestore();
-    mockExit.mockRestore();
     jest.useRealTimers();
   });
 
@@ -61,12 +56,12 @@ describe('postevalPlan', () => {
     }) as any;
 
     const { postevalPlan } = await import('../posteval-plan');
-    await postevalPlan({ planPath });
+    await postevalPlan({ planPath }, io);
 
-    expect(consoleLogSpy).toHaveBeenCalledWith(expect.stringContaining('100%'));
+    expect(io.outText()).toContain('100%');
   });
 
-  it('completeness < 1 应该 exit(1)', async () => {
+  it('completeness < 1：fail（覆盖率不足，含缺失项）', async () => {
     global.fetch = jest.fn().mockResolvedValue({
       ok: true,
       json: () => Promise.resolve({
@@ -77,10 +72,10 @@ describe('postevalPlan', () => {
     }) as any;
 
     const { postevalPlan } = await import('../posteval-plan');
-    await postevalPlan({ planPath });
+    const result = await postevalPlan({ planPath }, io);
 
-    expect(mockExit).toHaveBeenCalledWith(1);
-    expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('50%'));
+    expect(result).toEqual({ kind: 'fail', reason: expect.stringContaining('plan coverage 50% < 100%') });
+    expect(io.errText()).toContain('50%');
   });
 
   it('completeness < 1 时应该列出缺失项', async () => {
@@ -94,10 +89,13 @@ describe('postevalPlan', () => {
     }) as any;
 
     const { postevalPlan } = await import('../posteval-plan');
-    await postevalPlan({ planPath });
+    const result = await postevalPlan({ planPath }, io);
 
-    expect(mockExit).toHaveBeenCalledWith(1);
-    expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('AC-002'));
+    expect(result).toEqual({
+      kind: 'fail',
+      reason: 'plan coverage 33% < 100%，缺 2 项: AC-002; AC-003',
+    });
+    expect(io.errText()).toContain('AC-002');
   });
 
   it('4xx 错误应该 exit(1)', async () => {
@@ -108,13 +106,13 @@ describe('postevalPlan', () => {
     }) as any;
 
     const { postevalPlan } = await import('../posteval-plan');
-    await postevalPlan({ planPath });
+    const result = await postevalPlan({ planPath }, io);
 
-    expect(mockExit).toHaveBeenCalledWith(1);
-    expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('400'));
+    expect(result).toEqual({ kind: 'fail', reason: 'PostEval API error: 400 Bad Request' });
+    expect(io.errText()).toContain('400');
   });
 
-  it('5xx 错误应该 exit(0) 允许提交', async () => {
+  it('5xx 错误：skip（未判定，允许提交；退出码面 0 不变）', async () => {
     global.fetch = jest.fn().mockResolvedValue({
       ok: false,
       status: 503,
@@ -122,20 +120,20 @@ describe('postevalPlan', () => {
     }) as any;
 
     const { postevalPlan } = await import('../posteval-plan');
-    await postevalPlan({ planPath });
+    const result = await postevalPlan({ planPath }, io);
 
-    expect(mockExit).toHaveBeenCalledWith(0);
-    expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('unavailable'));
+    expect(result).toEqual({ kind: 'skip', reason: expect.stringContaining('服务端错误 503') });
+    expect(io.errText()).toContain('unavailable');
   });
 
-  it('网络错误重试耗尽后应该 exit(0)', async () => {
+  it('网络错误重试耗尽：skip（未判定，允许提交）', async () => {
     global.fetch = jest.fn().mockRejectedValue(new Error('ECONNREFUSED'));
 
     const { postevalPlan } = await import('../posteval-plan');
-    await postevalPlan({ planPath });
+    const result = await postevalPlan({ planPath }, io);
 
-    expect(mockExit).toHaveBeenCalledWith(0);
-    expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('unreachable'));
+    expect(result).toEqual({ kind: 'skip', reason: expect.stringContaining('Studio API 不可达') });
+    expect(io.errText()).toContain('unreachable');
   });
 
   it('应该支持自定义 API_PORT', async () => {
@@ -150,7 +148,7 @@ describe('postevalPlan', () => {
     }) as any;
 
     const { postevalPlan } = await import('../posteval-plan');
-    await postevalPlan({ planPath });
+    await postevalPlan({ planPath }, io);
 
     // Verify the fetch was called with port 3999
     const fetchCall = (global.fetch as jest.Mock).mock.calls[0][0];
@@ -174,12 +172,12 @@ describe('postevalPlan', () => {
     global.fetch = mockFetch as any;
 
     const { postevalPlan } = await import('../posteval-plan');
-    await postevalPlan({ planPath });
+    const result = await postevalPlan({ planPath }, io);
 
     // Should have been called 3 times
     expect(mockFetch).toHaveBeenCalledTimes(3);
-    expect(consoleLogSpy).toHaveBeenCalledWith(expect.stringContaining('100%'));
-    expect(mockExit).not.toHaveBeenCalled();
+    expect(io.outText()).toContain('100%');
+    expect(result.kind).toBe('ok');
   });
 
   it('completeness 为 0 时应该正确显示 0%', async () => {
@@ -193,9 +191,12 @@ describe('postevalPlan', () => {
     }) as any;
 
     const { postevalPlan } = await import('../posteval-plan');
-    await postevalPlan({ planPath });
+    const result = await postevalPlan({ planPath }, io);
 
-    expect(mockExit).toHaveBeenCalledWith(1);
-    expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('0%'));
+    expect(result).toEqual({
+      kind: 'fail',
+      reason: 'plan coverage 0% < 100%，缺 1 项: AC-001',
+    });
+    expect(io.errText()).toContain('0%');
   });
 });

package/src/cli/commands/__tests__/project-path-anchoring.test.ts

@@ -0,0 +1,157 @@
+/**
+ * -p/--project-path 锚定回归（harness#95）
+ *
+ * 两条门禁命令都接受 -p，但真正执行/IO 的一侧过去取 process.cwd()：不 cd 到目标工程调用，
+ * 就会拿 A 工程的命令、在 B 目录跑、把证据写进 B；acceptance 的「无 tasks.yml 即跳过」
+ * 本身是 passed:true，于是 -p 失效直接表现为假绿。
+ *
+ * 既有单测全部 mock fs/exec + 假 projectPath，恰好抹平两种取径的差异。本文件不 mock 任何 IO，
+ * 前提统一为 **cwd ≠ projectPath**（cwd = A，-p = B），断言读写位置落在 B。
+ * 站点 2 从两面各断言一次：CLI 命令面（`acceptance -p`）与门禁实例面（默认构造 = 注册表单例形状）。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { createProjectFixture } from '../../../test-setup/project-fixture';
+import { SpecAcceptanceGate } from '../../../gates/acceptance';
+import { captureIO } from '../../command-contract';
+import { runPassesGate } from '../passes-gate';
+import { acceptance } from '../acceptance';
+
+/** 在自身 cwd 落标记文件：哪一侧被真正调用，标记就出现在哪一侧的目录里 */
+function markScript(marker: string): string {
+  return [
+    'const fs = require("fs");',
+    `fs.writeFileSync("${marker}-exec-location.txt", process.cwd());`,
+    'console.log("1 passed");',
+    '',
+  ].join('\n');
+}
+
+const PACKAGE_JSON = JSON.stringify({
+  name: 'fixture',
+  version: '1.0.0',
+  scripts: { test: 'node ./mark.js' },
+});
+
+/** acceptance_criteria 形状：checked 决定判定，两侧只差 checked 值 → 读错文件必然改变结论 */
+function tasksYml(checked: boolean): string {
+  return [
+    'tasks:',
+    '  - id: TASK-001',
+    '    title: 锚定用例',
+    '    acceptance_criteria:',
+    '      - id: crit-1',
+    '        description: 需要人工确认的验收条件',
+    '        type: manual',
+    '        required: true',
+    `        checked: ${checked}`,
+    '',
+  ].join('\n');
+}
+
+/** passes-gate 两侧夹具：A = 调用方所在目录（cwd），B = -p 指向的目标工程 */
+function createPassesGateSides(): { cwdSide: string; projectSide: string } {
+  return {
+    cwdSide: createProjectFixture({
+      name: 'pganchor-cwd-side',
+      files: { 'package.json': PACKAGE_JSON, 'mark.js': markScript('cwd-side') },
+    }),
+    projectSide: createProjectFixture({
+      name: 'pganchor-project-side',
+      files: { 'package.json': PACKAGE_JSON, 'mark.js': markScript('project-side') },
+    }),
+  };
+}
+
+describe('-p 锚定：执行与 IO 必须落在 projectPath（cwd ≠ projectPath）', () => {
+  const originalCwd = process.cwd();
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+  });
+
+  describe('passes-gate（站点 1：执行 + 证据落盘）', () => {
+    it('-p 指向 B → B 的 package.json 测试命令在 B 执行，证据落 B/.harness/evidence', async () => {
+      const { cwdSide, projectSide } = createPassesGateSides();
+      process.chdir(cwdSide);
+
+      const result = await runPassesGate({ projectPath: projectSide }, captureIO());
+
+      expect(result).toEqual({ kind: 'ok' });
+      expect(fs.readFileSync(path.join(projectSide, 'project-side-exec-location.txt'), 'utf-8'))
+        .toBe(projectSide);
+      // 跑在 B 的判据同时要求 A 侧什么都没被执行、没被写入
+      expect(fs.existsSync(path.join(cwdSide, 'cwd-side-exec-location.txt'))).toBe(false);
+      expect(fs.existsSync(path.join(cwdSide, '.harness', 'evidence'))).toBe(false);
+
+      const evidenceDir = path.join(projectSide, '.harness', 'evidence');
+      expect(fs.existsSync(evidenceDir)).toBe(true);
+      expect(fs.readdirSync(evidenceDir).filter(f => f.startsWith('test-'))).toHaveLength(1);
+    });
+  });
+
+  describe('acceptance（站点 2：tasks.yml 解析）', () => {
+    it('默认构造的门禁实例（registry / getEffectiveGates 形状）→ 读 B/tasks.yml，不读 cwd 的', async () => {
+      const cwdSide = createProjectFixture({
+        name: 'acccfg-cwd-side',
+        files: { 'tasks.yml': tasksYml(true) },
+      });
+      const projectSide = createProjectFixture({
+        name: 'acccfg-project-side',
+        files: { 'tasks.yml': tasksYml(false) },
+      });
+      process.chdir(cwdSide);
+
+      // 无 config 构造 = 注册表单例的形状（./tasks.yml 相对默认值在这一支按 cwd 解析）
+      const result = await new SpecAcceptanceGate().check({
+        projectPath: projectSide,
+        taskId: 'TASK-001',
+      });
+
+      expect(result.passed).toBe(false);
+      expect(result.message).toContain('1 unchecked acceptance criteria');
+    });
+
+    it('-p 指向 B → 读 B/tasks.yml，不因 cwd 无文件而假绿', async () => {
+      const cwdSide = createProjectFixture({
+        name: 'accanchor-cwd-side',
+        files: { 'tasks.yml': tasksYml(true) },
+      });
+      const projectSide = createProjectFixture({
+        name: 'accanchor-project-side',
+        files: { 'tasks.yml': tasksYml(false) },
+      });
+      process.chdir(cwdSide);
+
+      const result = await acceptance({ projectPath: projectSide, taskId: 'TASK-001' }, captureIO());
+
+      expect(result).toEqual({
+        kind: 'fail',
+        reason: expect.stringContaining('1 unchecked acceptance criteria'),
+      });
+    });
+
+    it('--tasks-path 相对路径按 projectPath 解析，不按 cwd', async () => {
+      const cwdSide = createProjectFixture({
+        name: 'accanchorrel-cwd-side',
+        files: { 'config/tasks.yml': tasksYml(true) },
+      });
+      const projectSide = createProjectFixture({
+        name: 'accanchorrel-project-side',
+        files: { 'config/tasks.yml': tasksYml(false) },
+      });
+      process.chdir(cwdSide);
+
+      const result = await acceptance(
+        { projectPath: projectSide, taskId: 'TASK-001', tasksPath: 'config/tasks.yml' },
+        captureIO(),
+      );
+
+      expect(result).toEqual({
+        kind: 'fail',
+        reason: expect.stringContaining('1 unchecked acceptance criteria'),
+      });
+    });
+  });
+});

package/src/cli/commands/__tests__/project-path-convention.test.ts

@@ -0,0 +1,169 @@
+/**
+ * projectPath 传递约定守护（harness#95）
+ *
+ * 约定（正本见本目录 CONTEXT.md「约定」段）：**projectPath 只在 CLI 入口做一次 `|| process.cwd()`
+ * 兜底，之后必须传到每个 IO/执行点**——下游禁止再取一次 cwd，也禁止用相对路径默认值
+ * （两者都会让 `-p` 半失效：读写/执行位置悄悄回到调用方的 cwd）。
+ *
+ * 本文件是这条约定的机器可检面，三道闸：
+ * 1. CLI 入口层：cwd 只能以 `xxx || process.cwd()` 的兜底形状出现，例外逐个点名并记理由
+ * 2. 下游层（core / gates / context / monitoring / hooks）：cwd 站点集合冻结，
+ *    新增即失败——要么把根传下去，要么在此记下豁免理由
+ * 3. `xxxPath: '相对路径'` 默认值同理冻结（acceptance 的 `tasksPath: './tasks.yml'` 就是这一类）
+ *
+ * 冻结集合还要求**每条豁免仍然成立**（站点消失却不删条目 → 同样失败），豁免不会烂成化石。
+ * 「根参数已传入却又取 cwd」这类静态看不出的漂移，由 project-path-anchoring.test.ts 的真实 IO 行为用例守。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+const SRC_ROOT = path.join(__dirname, '..', '..', '..', '..', 'src');
+
+/** 注释行不参与匹配：文档里「缺省 process.cwd()」这类描述不是站点 */
+function codeLines(file: string): string[] {
+  return fs
+    .readFileSync(file, 'utf-8')
+    .split('\n')
+    .map(line => line.trim())
+    .filter(line => !line.startsWith('*') && !line.startsWith('//') && !line.startsWith('/*'));
+}
+
+function listTsFiles(dir: string, skipDirs: string[] = []): string[] {
+  const found: string[] = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === '__tests__' || skipDirs.includes(entry.name)) continue;
+      found.push(...listTsFiles(full, skipDirs));
+    } else if (entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts')) {
+      found.push(full);
+    }
+  }
+  return found.sort();
+}
+
+/** 仓库相对路径（豁免表以此为准，跨机器稳定） */
+function repoPath(abs: string): string {
+  return path.relative(path.join(SRC_ROOT, '..'), abs).split(path.sep).join('/');
+}
+
+function cwdSites(files: string[]): Map<string, string[]> {
+  const sites = new Map<string, string[]>();
+  for (const file of files) {
+    const lines = codeLines(file).filter(line => line.includes('process.cwd()'));
+    if (lines.length > 0) sites.set(repoPath(file), lines);
+  }
+  return sites;
+}
+
+// ========================================
+// 闸 1：CLI 入口层的非兜底形状 cwd
+// ========================================
+
+/** CLI 层的合法形状：入口对 `-p/--project-path` 做一次性兜底 */
+const ENTRY_FALLBACK_SHAPE = /\|\|\s*process\.cwd\(\)/;
+
+/** 兜底形状之外的 CLI cwd 站点：逐个裁决过，理由与站点原文一起冻结 */
+const CLI_CWD_EXEMPTIONS: Record<string, { lines: string[]; reason: string }> = {
+  'src/cli/commands/release.ts': {
+    lines: ['const pkgPath = process.cwd();'],
+    reason:
+      'release 定义表里没有 -p/--project-path（只收 --bump/--dry-run），pkgPath 就是该命令唯一的根，' +
+      '且已逐个传给每条 run(cmd, pkgPath) 与 verifyReleaseArtifacts(pkgPath)——不构成 -p 半失效。' +
+      '给发布流水线新增 -p 属新能力（可指向任意目录做 push/publish），不在 #95 范围。',
+  },
+};
+
+// ========================================
+// 闸 2：下游层的 cwd 站点
+// ========================================
+
+/**
+ * 下游豁免的共同理由：这些是**库层公开 API 的可选根参数默认值**（调用方没给根时的缺省），
+ * 不是「根已经传进来了，取 IO 时又绕回 cwd」。core 不能 import cli，兜底只能留在各自入口，
+ * 故冻结而非删除；新增站点必须在此逐个点名并单独说明。
+ */
+const DOWNSTREAM_CWD_EXEMPTIONS: Record<string, string> = {
+  'src/context/session-manager.ts': '构造参数 basePath 缺省（会话存储根，CLI 已显式传 projectPath）',
+  'src/core/constraints/checker.ts': 'check 上下文缺 projectPath 时的根兜底（3 处同一形状）',
+  'src/core/constraints/checkers/types.ts': 'checker 环境的根兜底（context.projectPath 可选）',
+  'src/core/constraints/context-builder.ts': 'buildCheckEnv 的 options.projectPath 缺省兜底（2 处）',
+  'src/core/constraints/usage-report.ts': 'projectRoot 形参默认值（库层可选根）',
+  'src/core/effective-constraints.ts': '生效集三函数 projectRoot 形参默认值（库层可选根，JSDoc 已声明）',
+  'src/core/project-config-loader.ts': 'config 加载器 projectPath 构造参数缺省兜底',
+  'src/core/spec/validator.ts': 'validateAll 的可选 projectPath 兜底（其相对 schemaPath 默认值见闸 3 豁免）',
+  'src/gates/checker-gate.ts': 'GateContext.projectPath 缺省兜底（门禁适配器的根入口）',
+  'src/gates/effective-gates.ts': 'projectRoot 形参默认值（库层可选根）',
+  'src/hooks/bootstrap.ts': 'bootstrapHarness 的可选 projectPath 兜底（组合根入口，2 处）',
+  'src/monitoring/context-tracker.ts': 'basePath 构造参数缺省兜底',
+};
+
+// ========================================
+// 闸 3：core/gates 的相对路径默认值
+// ========================================
+
+/** key 必须 camelCase 以 Path 结尾，值为相对字面量——这类默认值按 cwd 解析，即 #95 的病根形状 */
+const RELATIVE_PATH_DEFAULT = /\b\w+Path\s*:\s*'(?!\/)([^']+)'/;
+
+const RELATIVE_PATH_DEFAULT_EXEMPTIONS: Record<string, string> = {
+  'src/core/spec/validator.ts':
+    'schemaPath: "./specs/schemas" 确实按 cwd 解析（同型病灶）。不随 #95 修：validateFile()/loadSchema() ' +
+    '签名里没有根，补齐要把根穿透整个 spec 域（属 spec 重构，非本票两门禁）。CLI 侧 `spec -s` 已 ' +
+    'path.resolve(projectPath, schema)，给了 -s 时口径正确。留待 spec 域单票收口。',
+};
+
+describe('projectPath 传递约定（harness#95）', () => {
+  const cliFiles = listTsFiles(path.join(SRC_ROOT, 'cli'));
+  const downstreamFiles = listTsFiles(SRC_ROOT).filter(f => !f.startsWith(path.join(SRC_ROOT, 'cli')));
+
+  describe('闸 1：CLI 入口层的 cwd 只能是一次性兜底', () => {
+    it('非兜底形状的 cwd 站点 = 冻结豁免表，且每条豁免仍然成立', () => {
+      const offenders = new Map<string, string[]>();
+      for (const [rel, lines] of cwdSites(cliFiles)) {
+        const notFallback = lines.filter(line => !ENTRY_FALLBACK_SHAPE.test(line));
+        if (notFallback.length > 0) offenders.set(rel, notFallback);
+      }
+
+      expect([...offenders.keys()].sort()).toEqual(Object.keys(CLI_CWD_EXEMPTIONS).sort());
+      for (const [rel, exemption] of Object.entries(CLI_CWD_EXEMPTIONS)) {
+        expect({ rel, lines: offenders.get(rel) }).toEqual({ rel, lines: exemption.lines });
+      }
+    });
+  });
+
+  describe('闸 2：下游层不得二次取 cwd', () => {
+    it('下游 cwd 站点集合 = 冻结豁免表（新增即失败；站点消失却不删条目也失败）', () => {
+      const sites = cwdSites(downstreamFiles);
+
+      expect([...sites.keys()].sort()).toEqual(Object.keys(DOWNSTREAM_CWD_EXEMPTIONS).sort());
+      expect(sites.size).toBe(Object.keys(DOWNSTREAM_CWD_EXEMPTIONS).length);
+    });
+
+    it('PassesGate 执行侧不再取 cwd（站点 1 的收口形状：workDir 由调用方传入）', () => {
+      const lines = codeLines(path.join(SRC_ROOT, 'core', 'validators', 'passes-gate.ts'));
+
+      expect(lines.some(line => line.includes('process.cwd()'))).toBe(false);
+      expect(lines.find(line => line.includes('async runTests'))).toContain('workDir');
+    });
+  });
+
+  describe('闸 3：相对路径默认值不再按 cwd 解析', () => {
+    it('core/gates 里 xxxPath: 相对字面量 的站点 = 冻结豁免表', () => {
+      const hits = new Set<string>();
+      for (const file of listTsFiles(path.join(SRC_ROOT, 'core')).concat(listTsFiles(path.join(SRC_ROOT, 'gates')))) {
+        if (codeLines(file).some(line => RELATIVE_PATH_DEFAULT.test(line))) hits.add(repoPath(file));
+      }
+
+      expect([...hits].sort()).toEqual(Object.keys(RELATIVE_PATH_DEFAULT_EXEMPTIONS).sort());
+    });
+
+    it('acceptance 的 tasks.yml 默认不再有相对路径常量（站点 2 的收口形状）', () => {
+      // 多行调用 → 拼成空白归一的整段文本再断言形状
+      const body = codeLines(path.join(SRC_ROOT, 'gates', 'acceptance.ts')).join(' ').replace(/\s+/g, ' ');
+
+      expect(body).not.toMatch(/tasksPath\s*:\s*'/);
+      expect(body).toMatch(/path\.resolve\(\s*context\.projectPath\s*,\s*[^)]*'tasks\.yml'/);
+    });
+  });
+});

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

@@ -36,7 +36,7 @@ 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',
+  'spec-baseline-check',
   // 6 门禁命令（GATE_DEFINITIONS 驱动）
   'acceptance', 'command', 'contract', 'performance', 'review', 'security',
 ];
@@ -66,6 +66,28 @@ describe('命令注册表闭环', () => {
     }
   });
 
+  it('全部命令实现声明 CommandResult 返回（候选7：判定经返回值外溢）', () => {
+    const refs = collectRefs([
+      ...COMMAND_DEFINITIONS,
+      ...GATE_DEFINITIONS.map(d => d.cli),
+    ]);
+    for (const ref of refs) {
+      const file = fs.existsSync(path.join(repoCommandsDir, ref.module + '.ts'))
+        ? path.join(repoCommandsDir, ref.module + '.ts')
+        : path.join(repoCommandsDir, ref.module, 'index.ts');
+      const source = fs.readFileSync(file, 'utf-8');
+      const declAt = source.search(new RegExp(`function\\s+${ref.export}\\s*\\(`));
+      expect(declAt).toBeGreaterThanOrEqual(0);
+      const decl = source.slice(declAt, declAt + 900);
+      expect(decl).toMatch(/\)\s*:\s*(?:Promise<)?CommandResult/);
+      // bin 的调用约定：任何路由/子命令/action 至少传 options（mapActionArgs 编组）
+      // → 首参不得是 io，否则 options 会被当成 io 传入（写流即崩，退出码 1）
+      const params = source.slice(declAt + ref.export.length, declAt + 900);
+      const firstParam = (params.slice(params.indexOf('(') + 1).match(/^\s*([A-Za-z_$][\w$]*)/) || [''])[1];
+      expect(['io', '_io']).not.toContain(firstParam);
+    }
+  });
+
   it('顶层命令面与预期 24 命令一致（含 6 门禁）', () => {
     const names = [
       ...COMMAND_DEFINITIONS.map(d => d.command.split(' ')[0]),
@@ -80,45 +102,42 @@ describe('命令注册表闭环', () => {
     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 });
+  it('子命令别名唯一：别名不与主名/其他别名碰撞（候选7：别名是数据，冲突即行为歧义）', () => {
+    const walk = (def: CommandDefinition) => {
+      const entries = Object.entries(def.subcommands || {});
+      const seen = new Set<string>();
+      for (const [name, entry] of entries) {
+        expect(seen.has(name)).toBe(false);
+        seen.add(name);
+        for (const alias of entry.aliases || []) {
+          expect(seen.has(alias)).toBe(false);
+          seen.add(alias);
         }
-        for (const child of def.children || []) walk(child);
-      };
-      for (const def of [
-        ...COMMAND_DEFINITIONS,
-        ...GATE_DEFINITIONS.map(d => d.cli),
-      ]) walk(def);
-      // sync-docs --check 失败路径确实会请求退出
-      expect(exitSpy).toHaveBeenCalled();
-    } finally {
-      exitSpy.mockRestore();
-    }
+      }
+      for (const child of def.children || []) walk(child);
+    };
+    for (const def of [...COMMAND_DEFINITIONS, ...GATE_DEFINITIONS.map(d => d.cli)]) walk(def);
+  });
+
+  it('全部命令定义的路由构造可执行（mapActionArgs 冒烟；候选7 后定义表零副作用闭包）', () => {
+    const walk = (def: CommandDefinition) => {
+      if (def.mapActionArgs) {
+        def.mapActionArgs(['positional'], {});
+        def.mapActionArgs([], {});
+      }
+      // 候选7：定义表不得再持有退出码处理闭包（afterRun 已废除，判定进返回值）
+      expect((def as unknown as Record<string, unknown>).afterRun).toBeUndefined();
+      for (const child of def.children || []) walk(child);
+    };
+    for (const def of [
+      ...COMMAND_DEFINITIONS,
+      ...GATE_DEFINITIONS.map(d => d.cli),
+    ]) walk(def);
   });
 });
 
 const repoRoot = path.join(__dirname, '..', '..', '..', '..');
+const repoCommandsDir = path.join(repoRoot, 'src', 'cli', 'commands');
 const distBin = path.join(repoRoot, 'bin', 'harness.js');
 const distCommands = path.join(repoRoot, 'dist', 'cli', 'commands');
 const hasDist = fs.existsSync(distCommands);
@@ -200,4 +219,19 @@ smoke('bin/harness.js 端到端（dist 存在时）', () => {
     expect(r.status).toBe(1);
     expect(r.stderr).toContain('未知子命令: bogus');
   });
+
+  it('别名子命令解析到同一实现（knowledge ls = list，候选7）', () => {
+    const r = runWithModuleProbe(['knowledge', 'ls', '--json']);
+    expect(r.status).toBe(0);
+    expect(JSON.parse(r.stdout)).toHaveProperty('total');
+    expect(r.implModules).toEqual([
+      expect.stringContaining('/dist/cli/commands/knowledge.js'),
+    ]);
+  });
+
+  it('search 编组闸门随别名命令名生效且提示逐字不变（kb s 缺参 → exit 1）', () => {
+    const r = runWithModuleProbe(['kb', 's']);
+    expect(r.status).toBe(1);
+    expect(r.stderr).toContain('请提供搜索关键词');
+  });
 });