@dommaker/harness 1.2.3 → 1.4.0

package/src/cli/commands/CONTEXT.md

@@ -1,18 +1,19 @@
 # cli/commands/
 
 ## 职责
-CLI 子命令实现：24 个顶层命令 + constraints 治理子命令 report/retire，覆盖约束检查/门禁验证/文档同步/知识管理/失败诊断/发布/会话分析等。
+CLI 子命令实现：23 个顶层命令 + constraints 治理子命令 report/retire，覆盖约束检查/门禁验证/文档同步/知识管理/失败诊断/发布/会话分析等。
 
 H5（#44）起：
 - **命令定义即注册**：`definitions.ts` 的 `COMMAND_DEFINITIONS` 是命令形状（名称/别名/位置参数/选项/子命令/实现引用）的单一来源；bin/harness.js 遍历本表注册表驱动生成，不再手写 commander 命令块，不再有 index.ts barrel 两处同步（R6）
 - **per-command 懒加载**（O2）：定义表存实现引用 `{ module, export }`，bin 只在 action 执行时 require 对应命令模块，任一命令执行不再加载全部命令实现
 
 ## 核心导出
-- `COMMAND_DEFINITIONS`（definitions.ts）— 全部非门禁命令定义（纯数据模块，禁止 import 命令实现）
-- 各命令文件：check / validate / passes-gate / init / report / status / spec / sync-docs / knowledge / sdd / failure / posteval-plan / release / analyze-sessions / update-user-model / constraints / doc-freshness-check / spec-baseline-check
+- `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
 - 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 段（#82 D6 一处真相）+ KnowledgeStore 沉淀 + 治理注入段同步）。
+`constraints` 下挂治理子命令：`constraints report`（使用统计 + 退役候选诊断 + 配置健康 + 注入漂移，`--export` 脱敏）、`constraints retire`（交互选择 + 人确认退役；带 id 直达需显式 `--yes`（#24 人确认闸门），无 `--yes` 报错 + 非零退出码且不落盘；内置落 config.yml retired 元数据，custom 落 custom-constraints.yml 条目 retired 段（studio#82 D6 一处真相）+ KnowledgeStore 沉淀 + 治理注入段同步）。
 
 ## 依赖关系
 - 依赖 `src/core/constraints/` 约束引擎
@@ -25,13 +26,27 @@ H5（#44）起：
 ## 约定
 - 每个命令一个实现文件，命名与命令名一致（sync-docs 为模块族目录）
 - **新增命令 = 命令实现文件 + definitions.ts 一条定义（含 CLI 元数据与实现引用）+ 测试**，不再改 bin/harness.js
-- **definitions.ts 是纯数据模块**：禁止 import 任何命令实现/运行时依赖（保 --help/--version 懒加载）；实现引用可解析性由 `__tests__/registry.test.ts` 构建/测试期断言
+- **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` 供能力清单计数
+- **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()` 兜底形状、下游层（core/gates/context/monitoring/hooks）cwd 站点集合冻结、`xxxPath: '相对值'` 默认值冻结；豁免逐条带理由，站点消失却不删条目同样失败
+  - 行为可检：`__tests__/project-path-anchoring.test.ts` 前提统一 **cwd ≠ projectPath**、不 mock 任何 IO，断言测试真在 B 执行、证据落 `B/.harness/evidence/`、acceptance 读 `B/tasks.yml`。「根已传入却又取 cwd」这类静态看不出的漂移由它守，冻结表守的是不再新增站点
+- **读到部分结果必须告知（harness#100）**：命令面以 `skip` 策略读 JSONL（traces.log / failures.log）时，坏行计数要到用户可见输出，**不允许默默丢弃**。共同约束：无损坏零噪声（计数为 0 不出行）、不改任何既有计数口径（`status` 的 `记录数` 仍是原始非空行数，逐字节不变）、计数一律取自 `src/utils/jsonl` 读链返回的 `skippedLines`（经报告入口透传或在读点就地取用），**禁止**用「原始行数 − 统计条数」反推（窗过滤掉的合法行与坏行分不开）。三处落点各自对得上一行代码：
+  - `status`：告知**走 stderr**（`logError(io, …)`），因为 stdout 是报告体、其字节已被 `记录数` 那一行定死，挤进去等于改输出
+  - `constraints report`：提示属于**报告体内的降级位**，与既有的 `traceFileExists` 说明同在 stdout；结构化面另两份——`--json` 的 `skippedLines` 字段、`--export` markdown 的警示行（只报条数，不报路径与坏行内容）
+  - `constraints retire`：两条路径都**走 stderr**——交互模式在候选列表前一行（沿用本函数既有的 console 例外，`console.error`），`--yes` 直达分支在落盘前 `logError(io, …)`（`retireConstraint` 本身按契约「纯执行无交互」不打印）
+  - 原则正本与逐点去向见 `src/monitoring/CONTEXT.md`「约定」段；机器可检面是 `src/utils/__tests__/jsonl-skip-disposition.test.ts`（冻结全仓 skip 读点集合 + 要求每个读点记名声明 `计数去向：`）
 
 ## 注意事项
 - 新增命令需同步更新 CLAUDE.md / CAPABILITIES.md / src/CONTEXT.md
 - init 治理约束段写入落点（studio #302，ADR 2026-08-21 落点模型）：新仓 → AGENTS.md `PRESERVE:governance` 段（sync-docs 重新生成时保留）；旧模型仓（CLAUDE.md 已有 HARNESS_CONSTRAINTS 标记或 `## Governance Rules` 块）→ 续写 CLAUDE.md，幂等重跑不制造双份正本。治理段「在场守护」由 core 侧 governance_presence checker 承担（段缺失/为空时 check 报警）
 - PRESERVE:governance 段内写入纪律：机器管理的只有 HARNESS_CONSTRAINTS 标记区间——有标记只换标记区间，无标记（纯手写段）在段尾追加注入段；段内其余手写内容（治理契约引言/流程/纪律等）必须原样保留（曾整段替换清空手写内容的回归，init-injection.test 有防回归用例）
-- 注入段读取侧同一路由（studio #307）：`resolveInjectionTarget`（core/constraints/injection-drift）按「CLAUDE.md 有标记优先，否则 AGENTS.md」定位注入段，`detectInjectionDrift` 与 `constraints retire` 的注入段同步共用；未注入 = 两处均无完整标记段
+- 注入段落点路由与 marker-range 替换收口在 `core/constraints/injection-writer`（ADR-0011）：读侧 `resolveInjectionTarget`（漂移检测/retire 同步共用「CLAUDE.md 有标记优先，否则 AGENTS.md」）+ 写侧 `resolveGovernanceLanding`（init 落点选择）；init 三个治理段 writer 与 retire 注入同步均为「渲染 body + 调 writer」，半标记（单边/乱序）一律拒写告警；未注入 = 两处均无完整标记段
 - knowledge 命令包含 13 个子操作（list/search/import/decay/stats/upsert/sync-status/sync-rag/audit/snapshot/migrate/index/health）
-- 特殊路由（选项条件、子命令兜底、退出码处理、裸跑语义）表达在定义表的 optionRoutes / subcommands / subcommandStrict / bareRunsAction / afterRun 字段，bin 是纯通用引擎、不含单命令知识
+- `stats` / `health` 的飞轮数字不在 CLI 内计算：分子口径唯一实现是 `knowledge/flywheel-metrics.ts`（`evaluateFlywheel`，ADR-0013），本层只做百分比取整/一位小数与字段名映射；`.consumption-stats.json` 的读取留在各命令（module 零 IO）
+- 特殊路由（选项条件、子命令兜底、裸跑语义）表达在定义表的 optionRoutes / subcommands / subcommandStrict / bareRunsAction 字段，bin 是纯通用引擎、不含单命令知识
+- **命令 interface = `CommandResult` + 注入 io（架构评审候选7）**：命令实现一律声明 `Promise<CommandResult>`（判别联合 `ok|skip|fail|usage-error`，`fail`/`usage-error` 必附可定位的 `reason`，多闸门命令 reason 含 `gate <id>`），末位可选形参 `io: CommandIO = processIO`；类型与写入面在 `src/cli/command-contract.ts`
+- **本目录零 `process.exit` / `process.exitCode`**：kind → 退出码的唯一映射在 `bin/harness.js`（`ok`/`skip` → 0，`fail`/`usage-error` → 1，未知 kind fail-closed）。历史上两处条件式（`command --level` 按严重级、门禁按 passed）已由命令侧译成 kind；`sync-docs --check` 的漂移改由实现返回 `fail`（定义表的 `afterRun` 逃生门随之废除）
+- **输出不得直接用 console**：流式打印走 `log(io, …)` / `logError(io, …)`（`util.format` + 换行，与 console 逐字节等价，见 `src/cli/__tests__/command-contract.test.ts`）；测试断言输出用 `captureIO()`，不再 `spyOn(process, 'exit')`；`--json` 输出断言用 `lastJsonOutput(io)`（JSON.parse 正本，harness#108）。例外：`constraints retire` 交互正文仍走 console（其 `RetireIO` 只注入 readline 流），退役结果打印已接注入流
+- **#95 同型扫荡结论**：两门禁站点已修（`passes-gate` 执行/证据落 projectPath、`acceptance` 去掉 `tasksPath: './tasks.yml'` 相对默认值）。逐点判定后的豁免三处，理由与站点原文一起冻结在 `__tests__/project-path-convention.test.ts` 的豁免表：`release` 的 `pkgPath`（定义表本无 `-p`，pkgPath 就是该命令唯一的根且已逐个传给每条 `run(cmd, pkgPath)`，不构成半失效；给发布流水线新增 `-p` 属新能力）、`constraints` 的 `join(process.cwd(), 'package.json')`（报的是 harness 自身包版本，主锚 `__dirname`，cwd 仅兜底）、`core/spec/validator.ts` 的 `schemaPath: './specs/schemas'`（**确是同型病灶**：`validateAll(projectPath)` 用 projectPath 找 spec 文件、却用 cwd 找 schema；但 `validateFile`/`loadSchema` 签名里没有根，补齐要穿透整个 spec 域，留待 spec 单票收口）

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

@@ -3,6 +3,7 @@
  */
 
 import { acceptance, listAcceptanceCriteria } from '../acceptance';
+import { captureIO, type CapturingIO } from '../../command-contract';
 import * as fs from 'fs/promises';
 import { SpecAcceptanceGate } from '../../../gates/acceptance';
 
@@ -35,20 +36,12 @@ const MockGate = SpecAcceptanceGate as jest.MockedClass<typeof SpecAcceptanceGat
 const yaml = require('js-yaml');
 
 describe('acceptance command', () => {
-  let consoleSpy: jest.SpyInstance;
-  let exitSpy: jest.SpyInstance;
+  let io: CapturingIO;
 
   beforeEach(() => {
-    jest.clearAllMocks();
-    consoleSpy = jest.spyOn(console, 'log').mockImplementation();
-    exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => undefined as never);
-    process.exitCode = 0;
-  });
 
-  afterEach(() => {
-    consoleSpy.mockRestore();
-    exitSpy.mockRestore();
-    process.exitCode = 0;
+    io = captureIO();
+    jest.clearAllMocks();
   });
 
   describe('acceptance', () => {
@@ -60,10 +53,10 @@ describe('acceptance command', () => {
       });
       MockGate.mockImplementation(() => ({ check: mockCheck }) as any);
 
-      await acceptance({});
+      const result = await acceptance({}, io);
 
-      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('验收标准检查通过'));
-      expect(exitSpy).not.toHaveBeenCalled();
+      expect(io.outText()).toContain('验收标准检查通过');
+      expect(result.kind).toBe('ok');
     });
 
     it('should print failure and exit 1 when check fails', async () => {
@@ -74,27 +67,33 @@ describe('acceptance command', () => {
       });
       MockGate.mockImplementation(() => ({ check: mockCheck }) as any);
 
-      await acceptance({});
+      const result = await acceptance({}, io);
 
-      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('验收标准检查失败'));
-      expect(exitSpy).toHaveBeenCalledWith(1);
+      expect(io.outText()).toContain('验收标准检查失败');
+      expect(result).toEqual({
+        kind: 'fail',
+        reason: 'acceptance gate denied: criteria not met',
+      });
     });
 
     it('should handle errors and exit 1', async () => {
       const mockCheck = jest.fn().mockRejectedValue(new Error('gate error'));
       MockGate.mockImplementation(() => ({ check: mockCheck }) as any);
 
-      await acceptance({});
+      const result = await acceptance({}, io);
 
-      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('验收标准检查出错'));
-      expect(exitSpy).toHaveBeenCalledWith(1);
+      expect(io.outText()).toContain('验收标准检查出错');
+      expect(result).toEqual({
+        kind: 'fail',
+        reason: 'acceptance gate error: gate error',
+      });
     });
 
     it('should use cwd as default projectPath', async () => {
       const mockCheck = jest.fn().mockResolvedValue({ passed: true, message: 'ok' });
       MockGate.mockImplementation(() => ({ check: mockCheck }) as any);
 
-      await acceptance({});
+      await acceptance({}, io);
 
       expect(mockCheck).toHaveBeenCalledWith(
         expect.objectContaining({ projectPath: process.cwd() }),
@@ -105,7 +104,7 @@ describe('acceptance command', () => {
       const mockCheck = jest.fn().mockResolvedValue({ passed: true, message: 'ok' });
       MockGate.mockImplementation(() => ({ check: mockCheck }) as any);
 
-      await acceptance({ taskId: 'TASK-001' });
+      await acceptance({ taskId: 'TASK-001' }, io);
 
       expect(mockCheck).toHaveBeenCalledWith(
         expect.objectContaining({ taskId: 'TASK-001' }),
@@ -116,7 +115,7 @@ describe('acceptance command', () => {
       const mockCheck = jest.fn().mockResolvedValue({ passed: true, message: 'ok' });
       MockGate.mockImplementation(() => ({ check: mockCheck }) as any);
 
-      await acceptance({ runE2e: true });
+      await acceptance({ runE2e: true }, io);
 
       expect(MockGate).toHaveBeenCalledWith(
         expect.objectContaining({ e2eTestCommand: 'npx playwright test' }),
@@ -127,7 +126,7 @@ describe('acceptance command', () => {
       const mockCheck = jest.fn().mockResolvedValue({ passed: true, message: 'ok' });
       MockGate.mockImplementation(() => ({ check: mockCheck }) as any);
 
-      await acceptance({});
+      await acceptance({}, io);
 
       expect(MockGate).toHaveBeenCalledWith(
         expect.objectContaining({ e2eTestCommand: undefined }),
@@ -143,10 +142,10 @@ describe('acceptance command', () => {
         'task-2': { acceptanceCriteria: ['Criteria A'] },
       });
 
-      await listAcceptanceCriteria({});
+      await listAcceptanceCriteria({}, io);
 
-      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('task-1'));
-      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Criteria 1'));
+      expect(io.outText()).toContain('task-1');
+      expect(io.outText()).toContain('Criteria 1');
     });
 
     it('should handle task with no criteria', async () => {
@@ -155,26 +154,34 @@ describe('acceptance command', () => {
         'task-1': {},
       });
 
-      await listAcceptanceCriteria({});
+      await listAcceptanceCriteria({}, io);
 
-      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('无验收标准'));
+      expect(io.outText()).toContain('无验收标准');
     });
 
     it('should handle empty tasks object', async () => {
       mockFs.readFile.mockResolvedValue('yaml-content');
       yaml.load.mockReturnValue(null);
 
-      await listAcceptanceCriteria({});
+      const result = await listAcceptanceCriteria({}, io);
 
-      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('未找到任务定义'));
+      expect(io.outText()).toContain('未找到任务定义');
+      expect(result).toEqual({
+        kind: 'skip',
+        reason: expect.stringContaining('未找到任务定义'),
+      });
     });
 
     it('should handle file read error', async () => {
       mockFs.readFile.mockRejectedValue(new Error('ENOENT'));
 
-      await listAcceptanceCriteria({});
+      const result = await listAcceptanceCriteria({}, io);
 
-      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('读取 tasks.yml 失败'));
+      expect(io.outText()).toContain('读取 tasks.yml 失败');
+      expect(result).toEqual({
+        kind: 'skip',
+        reason: expect.stringContaining('读取 tasks.yml 失败'),
+      });
     });
   });
 });

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

@@ -9,6 +9,7 @@
  */
 
 import * as fs from 'fs';
+import { captureIO, lastJsonOutput, type CapturingIO } from '../../command-contract';
 import * as path from 'path';
 import { analyzeSessions } from '../analyze-sessions';
 import { readTranscriptSessions, type MinedSession } from '../../session-mining';
@@ -69,13 +70,12 @@ function mkSession(partial: Partial<MinedSession> = {}): MinedSession {
   };
 }
 
-function lastJsonOutput(consoleSpy: jest.SpyInstance): Record<string, unknown> {
-  const jsonLine = consoleSpy.mock.calls.map(c => c[0]).join('\n');
-  return JSON.parse(jsonLine);
-}
+let io: CapturingIO;
+beforeEach(() => {
+  io = captureIO();
+});
 
 describe('analyze-sessions command', () => {
-  let consoleSpy: jest.SpyInstance;
 
   beforeEach(() => {
     jest.clearAllMocks();
@@ -83,42 +83,48 @@ describe('analyze-sessions command', () => {
     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({});
+    const result = await analyzeSessions({}, io);
 
-    expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('No transcripts directory found'));
+    expect(io.outText()).toContain('No transcripts directory found');
+    expect(result).toEqual({ kind: 'skip', reason: expect.stringContaining('会话记录目录不存在') });
     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'));
+    const before = Date.now() - 7 * 86_400_000;
+    mockReadTranscriptSessions.mockReturnValue([]);
+
+    const result = await analyzeSessions({}, io);
+    const after = Date.now() - 7 * 86_400_000;
+
+    expect(io.outText()).toContain('No sessions found in the last 7 days');
+    expect(result).toEqual({ kind: 'skip', reason: '最近 7 天没有会话' });
+    // since 过滤下推到 seam：默认窗口 7 天
+    const filter = mockReadTranscriptSessions.mock.calls[0][1] as { since?: number };
+    expect(filter.since).toBeGreaterThanOrEqual(before);
+    expect(filter.since).toBeLessThanOrEqual(after);
   });
 
-  test('--days 1：只统计最近 1 天（mtimeMs 窗口过滤）', async () => {
-    mockReadTranscriptSessions.mockReturnValue([
-      mkSession({ id: 'today' }),
-      mkSession({ id: 'two-days-ago', mtimeMs: Date.now() - 2 * 86_400_000 }),
-    ]);
+  test('--days 1：since 过滤下推到 seam（mtimeMs 窗口）', async () => {
+    const before = Date.now() - 86_400_000;
+    mockReadTranscriptSessions.mockReturnValue([mkSession({ id: 'today' })]);
 
-    await analyzeSessions({ days: 1 });
+    await analyzeSessions({ days: 1 }, io);
+    const after = Date.now() - 86_400_000;
 
-    expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Analyzing 1 sessions (last 1 days)'));
+    expect(io.outText()).toContain('Analyzing 1 sessions (last 1 days)');
+    const filter = mockReadTranscriptSessions.mock.calls[0][1] as { since?: number };
+    expect(filter.since).toBeGreaterThanOrEqual(before);
+    expect(filter.since).toBeLessThanOrEqual(after);
   });
 
   test('缺省 --days：窗口为 7 天，两天前会话仍计入', async () => {
@@ -127,9 +133,9 @@ describe('analyze-sessions command', () => {
       mkSession({ id: 'two-days-ago', mtimeMs: Date.now() - 2 * 86_400_000 }),
     ]);
 
-    await analyzeSessions({});
+    await analyzeSessions({}, io);
 
-    expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Analyzing 2 sessions (last 7 days)'));
+    expect(io.outText()).toContain('Analyzing 2 sessions (last 7 days)');
   });
 
   test('--json：纠正句跨 3 会话聚合为 correction 候选', async () => {
@@ -139,9 +145,9 @@ describe('analyze-sessions command', () => {
       mkSession({ id: 's3' }),
     ]);
 
-    await analyzeSessions({ json: true });
+    await analyzeSessions({ json: true }, io);
 
-    const output = lastJsonOutput(consoleSpy);
+    const output = lastJsonOutput(io);
     expect(output.sessions).toBe(3);
     expect(output.corrections).toBe(3);
     expect(output.candidates).toEqual(
@@ -168,9 +174,9 @@ describe('analyze-sessions command', () => {
       }),
     ]);
 
-    await analyzeSessions({ json: true });
+    await analyzeSessions({ json: true }, io);
 
-    const output = lastJsonOutput(consoleSpy);
+    const output = lastJsonOutput(io);
     const ngramCandidates = (output.candidates as Array<{ source: string }>)
       .filter(c => c.source === 'ngram');
     expect(ngramCandidates.length).toBeGreaterThan(0);

package/src/cli/commands/__tests__/bin-exit-mapping.test.ts

@@ -0,0 +1,101 @@
+/**
+ * bin 侧退出码映射测试（架构评审候选7）
+ *
+ * 命令实现只返回 CommandResult，`process.exit` 的唯一出口在 bin/harness.js。
+ * 两层证据：
+ * 1. exitCodeFor 纯映射：四种 kind + 契约违规（未知/缺失 kind）fail-closed；
+ * 2. 端到端 spawn bin/harness.js（dist 存在时）：真实命令的对外退出码
+ *    ——断言进程 status，不用 spyOn(process,'exit')。
+ * 另加零 process.exit 的源码护栏（命令实现/定义表目录）。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const { exitCodeFor } = require('../../../../bin/harness.js');
+
+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);
+
+describe('exitCodeFor：kind → 退出码唯一映射', () => {
+  it('ok / skip → 0（现状对外码面只有 0/1，skip 不新增码值）', () => {
+    expect(exitCodeFor({ kind: 'ok' })).toBe(0);
+    expect(exitCodeFor({ kind: 'skip' })).toBe(0);
+    expect(exitCodeFor({ kind: 'skip', reason: '没有定义检查点' })).toBe(0);
+  });
+
+  it('fail / usage-error → 1', () => {
+    expect(exitCodeFor({ kind: 'fail', reason: 'gate branch: 非 master' })).toBe(1);
+    expect(exitCodeFor({ kind: 'usage-error', reason: '缺少关键词' })).toBe(1);
+  });
+
+  it('未知或缺失 kind → fail-closed（命令契约违规不得静默通过）', () => {
+    const errSpy = jest.spyOn(console, 'error').mockImplementation();
+    try {
+      expect(exitCodeFor({ kind: 'exploded' })).toBe(1);
+      expect(exitCodeFor(undefined)).toBe(1);
+      expect(exitCodeFor({})).toBe(1);
+      expect(errSpy).toHaveBeenCalledTimes(3);
+    } finally {
+      errSpy.mockRestore();
+    }
+  });
+});
+
+describe('命令实现/定义表目录零 process.exit（唯一出口在 bin）', () => {
+  const dirs = [
+    path.join(repoRoot, 'src', 'cli', 'commands'),
+    path.join(repoRoot, 'src', 'cli', 'commands', 'sync-docs'),
+  ];
+
+  it.each(dirs.map(d => [d]))('%s', (dir: string) => {
+    const offenders = fs.readdirSync(dir)
+      .filter(f => f.endsWith('.ts') && !f.includes('.test.'))
+      .filter(f => fs.readFileSync(path.join(dir, f), 'utf-8').includes('process.exit'))
+      .map(f => `${dir}/${f}`);
+    expect(offenders).toEqual([]);
+  });
+
+  it('bin/harness.js 只有一处 process.exit 调用点', () => {
+    const source = fs.readFileSync(distBin, 'utf-8');
+    const calls = [...source.matchAll(/process\.exit\(/g)];
+    expect(calls).toHaveLength(1);
+  });
+});
+
+const smoke = hasDist ? describe : describe.skip;
+
+smoke('端到端：真实命令经 bin 映射后的对外退出码', () => {
+  const run = (argv: string[]) => spawnSync(process.execPath, [distBin, ...argv], {
+    cwd: repoRoot,
+    encoding: 'utf-8',
+    timeout: 60000,
+  });
+
+  it('放行命令 → 0（返回 ok，进程自然退出）', () => {
+    const r = run(['command', 'ls']);
+    expect(r.status).toBe(0);
+  });
+
+  it('门禁否决 → 1（返回 fail，bin 映射）', () => {
+    const r = run(['command', 'rm -rf /']);
+    expect(r.status).toBe(1);
+    expect(r.stdout).toContain('✗');
+  });
+
+  it('用法错误 → 1（返回 usage-error）', () => {
+    const r = run(['kb', 's']);
+    expect(r.status).toBe(1);
+    expect(r.stderr).toContain('请提供搜索关键词');
+  });
+
+  it('bin 自身子命令路由错误 → 1', () => {
+    const r = run(['knowledge', 'bogus']);
+    expect(r.status).toBe(1);
+    expect(r.stderr).toContain('未知子命令: bogus');
+  });
+});

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

@@ -7,18 +7,23 @@
  */
 
 import * as fs from 'fs';
-import * as os from 'os';
+import { captureIO, type CapturingIO } from '../../command-contract';
 import * as path from 'path';
 import { check } from '../check';
-import { constraintChecker } from '../../../core/constraints/checker';
 import { renderConstraintsSection } from '../../../core/constraints/injection-renderer';
 import { getEffectiveConstraints } from '../../../core/effective-constraints';
+import { createProjectFixture } from '../../../test-setup/project-fixture';
 
+// 命令 per-run 构造 checker（harness#88）：构造替身即控制 checkConstraints 返回值
+const mockChecker = { checkConstraints: jest.fn() };
 jest.mock('../../../core/constraints/checker', () => ({
-  constraintChecker: {
-    setTraceRecorder: jest.fn(),
-    checkConstraints: jest.fn(),
-  },
+  ConstraintChecker: jest.fn(function () {
+    return mockChecker;
+  }),
+}));
+
+jest.mock('../../../monitoring/traces', () => ({
+  getTraceCollector: jest.fn(() => ({ record: jest.fn() })),
 }));
 
 jest.mock('../../../utils/exec', () => ({
@@ -30,15 +35,9 @@ jest.mock('child_process', () => ({
   execSync: jest.fn(() => Buffer.from('')),
 }));
 
-const mockChecker = constraintChecker as jest.Mocked<typeof constraintChecker>;
-
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const REAL_VERSION = require('../../../../package.json').version as string;
 
-function makeTmpProject(): string {
-  return fs.mkdtempSync(path.join(os.tmpdir(), 'harness-check-drift-test-'));
-}
-
 function writeClaudeMd(root: string, version: string): void {
   const section =
     '## Governance Rules\n' + renderConstraintsSection(getEffectiveConstraints(root), version);
@@ -46,13 +45,12 @@ function writeClaudeMd(root: string, version: string): void {
 }
 
 describe('check 命令注入漂移警告', () => {
-  let consoleSpy: jest.SpyInstance;
-  let exitSpy: jest.SpyInstance;
+  let io: CapturingIO;
 
   beforeEach(() => {
+
+    io = captureIO();
     jest.clearAllMocks();
-    consoleSpy = jest.spyOn(console, 'log').mockImplementation(() => {});
-    exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => undefined as never);
     mockChecker.checkConstraints.mockResolvedValue({
       passed: true,
       ironLaws: [],
@@ -61,18 +59,13 @@ describe('check 命令注入漂移警告', () => {
     });
   });
 
-  afterEach(() => {
-    consoleSpy.mockRestore();
-    exitSpy.mockRestore();
-  });
-
-  const outputText = () => consoleSpy.mock.calls.map(c => String(c[0])).join('\n');
+  const outputText = () => io.outText();
 
   it('版本漂移：黄色警告块 + ⚠️⚠️ 版本行，但不阻断（exit 未调用，仍判通过）', async () => {
-    const root = makeTmpProject();
+    const root = createProjectFixture({ name: 'harness-check-drift-test' });
     writeClaudeMd(root, '0.0.1-old');
 
-    await check({ preset: 'standard', staged: false, projectPath: root });
+    const result = await check({ preset: 'standard', staged: false, projectPath: root }, io);
 
     const output = outputText();
     expect(output).toContain('约束注入漂移');
@@ -82,43 +75,43 @@ describe('check 命令注入漂移警告', () => {
     expect(output).toContain('npx @dommaker/harness init');
     // 不阻断：检查仍通过、未调用 process.exit
     expect(output).toContain('约束检查通过');
-    expect(exitSpy).not.toHaveBeenCalled();
+    expect(result.kind).toBe('ok');
   });
 
   it('内容漂移：手改一条 → 警告块含缺失/多余计数，exit 未调用', async () => {
-    const root = makeTmpProject();
+    const root = createProjectFixture({ name: 'harness-check-drift-test' });
     writeClaudeMd(root, REAL_VERSION);
     const claudeMdPath = path.join(root, 'CLAUDE.md');
     const content = fs.readFileSync(claudeMdPath, 'utf-8');
     const originalLine = content.split('\n').find(l => l.startsWith('- **'))!;
     fs.writeFileSync(claudeMdPath, content.replace(originalLine, originalLine.replace(/: .+$/, ': 篡改')), 'utf-8');
 
-    await check({ preset: 'standard', staged: false, projectPath: root });
+    const result = await check({ preset: 'standard', staged: false, projectPath: root }, io);
 
     const output = outputText();
     expect(output).toContain('内容漂移: 缺失 1 条 / 多余 1 条');
     expect(output).toContain('约束检查通过');
-    expect(exitSpy).not.toHaveBeenCalled();
+    expect(result.kind).toBe('ok');
   });
 
   it('无漂移：零警告输出（不增加噪音）', async () => {
-    const root = makeTmpProject();
+    const root = createProjectFixture({ name: 'harness-check-drift-test' });
     writeClaudeMd(root, REAL_VERSION);
 
-    await check({ preset: 'standard', staged: false, projectPath: root });
+    const result = await check({ preset: 'standard', staged: false, projectPath: root }, io);
 
     const output = outputText();
     expect(output).not.toContain('注入漂移');
     expect(output).toContain('约束检查通过');
-    expect(exitSpy).not.toHaveBeenCalled();
+    expect(result.kind).toBe('ok');
   });
 
   it('未注入（无 CLAUDE.md）：不警告', async () => {
-    const root = makeTmpProject();
+    const root = createProjectFixture({ name: 'harness-check-drift-test' });
 
-    await check({ preset: 'standard', staged: false, projectPath: root });
+    const result = await check({ preset: 'standard', staged: false, projectPath: root }, io);
 
     expect(outputText()).not.toContain('注入漂移');
-    expect(exitSpy).not.toHaveBeenCalled();
+    expect(result.kind).toBe('ok');
   });
 });