@dommaker/harness 1.3.0 → 1.4.0

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

@@ -3,7 +3,8 @@
  */
 
 import { describe, it, expect, beforeAll, afterAll } from '@jest/globals';
-import { PassesGate, createPassesGate } from '../core/validators/passes-gate';
+import { PassesGate, createPassesGate, detectTestCommand } from '../core/validators/passes-gate';
+import type { TaskTestResult } from '../types/passes-gate';
 import { mkdirSync, rmSync, writeFileSync } from 'fs';
 import { join } from 'path';
 
@@ -60,13 +61,13 @@ describe('PassesGate', () => {
   });
 
   describe('runTests', () => {
-    // 跳过：会调用真实测试套件，需要 mock 重构
-    it.skip('应该返回测试结果', async () => {
-      const result = await gate.runTests();
-      
-      expect(result).toBeDefined();
-      expect(result.passed).toBeDefined();
-      expect(result.duration).toBeGreaterThan(0);
+    // 执行根由调用方传入（#95）：tempDir 的 package.json 测试命令是 echo，不再跑真实套件
+    it('应该返回测试结果', async () => {
+      const result = await gate.runTests(tempDir);
+
+      expect(result.passed).toBe(true);
+      expect(result.passedTests).toBe(1);
+      expect(result.duration).toBeGreaterThanOrEqual(0);
     });
   });
 
@@ -79,6 +80,93 @@ describe('PassesGate', () => {
     });
   });
 
+  // 探测正本行为钉住（架构评审 A2：CLI/core 双版收口后的统一语义，
+  // 此前 e2e 优先级、echo 排除、兜底均无测试钉住）
+  describe('detectTestCommand 正本（统一探测顺序）', () => {
+    const detectDir = join(process.cwd(), 'temp-test-detect-command');
+
+    const writePkg = (dir: string, scripts: Record<string, string>) => {
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'detect-case', scripts }));
+    };
+
+    afterAll(() => {
+      try {
+        rmSync(detectDir, { recursive: true, force: true });
+      } catch {
+        // ignore
+      }
+    });
+
+    it('test:ci 与 test 同存时优先 test:ci', async () => {
+      const dir = join(detectDir, 'ci-over-test');
+      writePkg(dir, { test: 'jest', 'test:ci': 'jest --ci' });
+
+      expect(await detectTestCommand(dir)).toBe('npm run test:ci');
+    });
+
+    it('echo 占位脚本不算 test，同存 e2e 时落到 e2e', async () => {
+      const dir = join(detectDir, 'echo-placeholder');
+      writePkg(dir, { test: 'echo "Error: no test specified"', 'test:e2e': 'playwright test' });
+
+      expect(await detectTestCommand(dir)).toBe('npm run test:e2e');
+    });
+
+    it('仅有 echo 占位且无其他标记时返回 undefined', async () => {
+      const dir = join(detectDir, 'echo-only');
+      writePkg(dir, { test: 'echo "Error: no test specified"' });
+
+      expect(await detectTestCommand(dir)).toBeUndefined();
+    });
+
+    it('无 test/test:ci 时 test:e2e 命中，无 e2e 时 test:coverage 命中', async () => {
+      const e2eDir = join(detectDir, 'e2e-only');
+      writePkg(e2eDir, { 'test:e2e': 'vitest e2e', 'test:coverage': 'vitest --coverage' });
+      expect(await detectTestCommand(e2eDir)).toBe('npm run test:e2e');
+
+      const covDir = join(detectDir, 'coverage-only');
+      writePkg(covDir, { 'test:coverage': 'vitest --coverage' });
+      expect(await detectTestCommand(covDir)).toBe('npm run test:coverage');
+    });
+
+    it('Python 标记 pyproject.toml 或 pytest.ini 任一命中', async () => {
+      const pyprojectDir = join(detectDir, 'py-pyproject');
+      mkdirSync(pyprojectDir, { recursive: true });
+      writeFileSync(join(pyprojectDir, 'pyproject.toml'), '[project]\nname = "x"\n');
+      expect(await detectTestCommand(pyprojectDir)).toBe('pytest');
+
+      const pytestIniDir = join(detectDir, 'py-pytest-ini');
+      mkdirSync(pytestIniDir, { recursive: true });
+      writeFileSync(join(pytestIniDir, 'pytest.ini'), '[pytest]\n');
+      expect(await detectTestCommand(pytestIniDir)).toBe('pytest');
+    });
+
+    it('go.mod 命中 go test，无任何标记返回 undefined', async () => {
+      const goDir = join(detectDir, 'go-mod');
+      mkdirSync(goDir, { recursive: true });
+      writeFileSync(join(goDir, 'go.mod'), 'module example.com/x\n');
+      expect(await detectTestCommand(goDir)).toBe('go test ./...');
+
+      const emptyDir = join(detectDir, 'empty');
+      mkdirSync(emptyDir, { recursive: true });
+      expect(await detectTestCommand(emptyDir)).toBeUndefined();
+    });
+
+    it('探测失败时 runTests 与 setPasses 双路径 fail-closed', async () => {
+      const emptyDir = join(detectDir, 'fail-closed');
+      mkdirSync(emptyDir, { recursive: true });
+
+      const runResult = await gate.runTests(emptyDir);
+      expect(runResult.passed).toBe(false);
+      expect(runResult.message).toBe('未检测到测试命令');
+
+      const setResult = await gate.setPasses('task-nocmd', true, emptyDir);
+      expect(setResult.allowed).toBe(false);
+      expect(setResult.testResult?.passed).toBe(false);
+      expect(setResult.testResult?.output).toBe('未检测到测试命令');
+    });
+  });
+
   describe('checkTestFileChanges', () => {
     it('应该检测测试文件变更', async () => {
       // 无 git 变更时返回空数组
@@ -88,104 +176,6 @@ describe('PassesGate', () => {
     });
   });
 
-  describe('扩展点支持', () => {
-    it('应该能注册扩展', () => {
-      gate.registerExtension('custom', {
-        name: 'custom',
-        run: async () => ({
-          passed: true,
-          command: 'custom-test',
-          timestamp: new Date(),
-        }),
-      });
-      
-      const names = gate.getExtensionNames();
-      expect(names).toContain('custom');
-    });
-
-    it('应该能注销扩展', () => {
-      gate.registerExtension('temp', {
-        name: 'temp',
-        run: async () => ({
-          passed: true,
-          command: 'temp-test',
-          timestamp: new Date(),
-        }),
-      });
-      
-      const removed = gate.unregisterExtension('temp');
-      expect(removed).toBe(true);
-      
-      const names = gate.getExtensionNames();
-      expect(names).not.toContain('temp');
-    });
-
-    it('runAllTests 应该运行所有测试包括扩展', async () => {
-      gate.registerExtension('puppeteer', {
-        name: 'puppeteer',
-        run: async () => ({
-          passed: true,
-          command: 'puppeteer-test',
-          timestamp: new Date(),
-        }),
-      });
-      
-      const results = await gate.runAllTests(tempDir);
-      
-      expect(results.length).toBeGreaterThan(1);  // 单元测试 + puppeteer
-      expect(results.some(r => r.type === 'puppeteer')).toBe(true);
-    });
-
-    it('checkAllPasses 应该返回综合结果', async () => {
-      gate.registerExtension('passing-ext', {
-        name: 'passing-ext',
-        run: async () => ({
-          passed: true,
-          command: 'passing-test',
-          timestamp: new Date(),
-        }),
-      });
-      
-      const result = await gate.checkAllPasses(tempDir);
-      
-      expect(result.passed).toBeDefined();
-      expect(result.results).toBeDefined();
-      expect(Array.isArray(result.failedTypes)).toBe(true);
-    });
-
-    it('checkAllPasses 应该返回失败类型', async () => {
-      const failingGate = createPassesGate({ enabled: true });
-      failingGate.registerExtension('failing-ext', {
-        name: 'failing-ext',
-        run: async () => ({
-          passed: false,
-          command: 'failing-test',
-          timestamp: new Date(),
-        }),
-      });
-      
-      const result = await failingGate.checkAllPasses(tempDir);
-      
-      expect(result.failedTypes).toContain('failing-ext');
-    });
-
-    it('扩展抛错应返回失败结果', async () => {
-      const errorGate = createPassesGate({ enabled: true });
-      errorGate.registerExtension('error-ext', {
-        name: 'error-ext',
-        run: async () => {
-          throw new Error('Extension error');
-        },
-      });
-      
-      const results = await errorGate.runAllTests(tempDir);
-      
-      const errorResult = results.find(r => r.type === 'error-ext');
-      expect(errorResult?.passed).toBe(false);
-      expect(errorResult?.error).toContain('Extension error');
-    });
-  });
-
   describe('getTestResult', () => {
     it('应该返回已存储的测试结果', async () => {
       const result = await gate.setPasses('stored-task', true, tempDir);
@@ -228,4 +218,50 @@ describe('PassesGate', () => {
       rmSync(retryDir, { recursive: true, force: true });
     });
   });
+
+  /**
+   * #94 裁决 B：harness 核心判定不管覆盖率 —— 从 stdout 抠覆盖率的 regex 路
+   * （extractCoverage → TaskTestResult.coverage）整体删除，结果面不再有 coverage 字段。
+   */
+  describe('覆盖率取数路删除（harness#94）', () => {
+    const covDir = join(process.cwd(), 'temp-test-no-coverage-field');
+
+    beforeAll(() => {
+      mkdirSync(covDir, { recursive: true });
+
+      // 输出里放一份 jest 覆盖率表：删除前 extractCoverage 会从中抠出 80.5 填进结果字段
+      writeFileSync(join(covDir, 'package.json'), JSON.stringify({
+        name: 'coverage-project',
+        scripts: { test: 'echo "All files | 80.50 | 70.21 | 83.33 | 79.59 |"' },
+      }));
+    });
+
+    afterAll(() => {
+      try {
+        rmSync(covDir, { recursive: true, force: true });
+      } catch {
+        // ignore
+      }
+    });
+
+    it('setPasses 结果不带 coverage 字段', async () => {
+      const covGate = createPassesGate({ enabled: true, requireEvidence: false });
+
+      const result = await covGate.setPasses('cov-task', true, covDir);
+
+      expect(result.testResult?.passed).toBe(true);
+      expect(result.testResult).not.toHaveProperty('coverage');
+    });
+
+    it('TaskTestResult 公开类型面不再接受 coverage 字段', () => {
+      const testResult: TaskTestResult = {
+        passed: true,
+        command: 'npm test',
+        // @ts-expect-error coverage 随 harness#94 删除，类型面不接受该字段
+        coverage: 85,
+      };
+
+      expect(testResult.passed).toBe(true);
+    });
+  });
 });

package/src/__tests__/skip-semantics.test.ts

@@ -9,7 +9,7 @@
  * - trace 记录 result: 'skip'；TraceAnalyzer 的 pass/fail 率分母不计 skip
  */
 
-import { describe, it, expect, beforeAll, afterAll, afterEach } from '@jest/globals';
+import { describe, it, expect, beforeAll, afterAll } from '@jest/globals';
 import { ConstraintChecker } from '../core/constraints/checker';
 import { detectTrigger, buildConstraintContext } from '../core/constraints/context-builder';
 import { IRON_LAWS } from '../core/constraints/definitions';
@@ -20,7 +20,8 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { execSync } from 'child_process';
 
-const checker = ConstraintChecker.getInstance();
+/** 套件共用 checker：显式 no-op 记录器（trace 断言的用例自带记录器实例） */
+const checker = new ConstraintChecker({ record: () => undefined });
 
 function makeConstraint(
   id: string,
@@ -51,11 +52,6 @@ describe('skip 三态语义（ADR-0001）', () => {
     }
   });
 
-  afterEach(() => {
-    // 复位 trace recorder，避免泄漏到其他用例
-    checker.setTraceRecorder({ record: () => undefined });
-  });
-
   describe('capability_sync 存在性探测', () => {
     it('无 CAPABILITIES.md（未采用约定）→ skip，不计 fail', async () => {
       const dir = path.join(tempDir, 'cap-skip');
@@ -289,9 +285,9 @@ describe('skip 三态语义（ADR-0001）', () => {
   describe('trace 的 skip 形态', () => {
     it('recordTrace：skip 记录为 result: skip', async () => {
       const records: ExecutionTrace[] = [];
-      checker.setTraceRecorder({ record: (t) => records.push(t) });
+      const recording = new ConstraintChecker({ record: (t) => records.push(t) });
 
-      await checker.checkConstraints({
+      await recording.checkConstraints({
         operation: 'code_implementation',
         projectPath: path.join(tempDir, 'empty'),
       });

package/src/cli/__tests__/command-contract.test.ts

@@ -0,0 +1,170 @@
+/**
+ * 命令契约测试（架构评审候选7）
+ *
+ * Seam：src/cli/command-contract.ts —— 命令实现的返回形状 + 输出注入面。
+ * 关键不变量：注入缺省 io（process 流）时，log/logError 的输出字节与
+ * console.log/console.error 逐字一致（CLI 语法冻结护栏：输出文案不得漂移）。
+ */
+
+import { Writable } from 'stream';
+import {
+  captureIO,
+  lastJsonOutput,
+  log,
+  logError,
+  processIO,
+  type CommandIO,
+  type CommandResult,
+} from '../command-contract';
+
+/** 同步收集写入 chunk 的最小可写流（console.Console 与 CommandIO 共用同一 sink） */
+class Sink extends Writable {
+  private chunks: string[] = [];
+  _write(chunk: any, _enc: string, cb: () => void): void {
+    this.chunks.push(String(chunk));
+    cb();
+  }
+  reset(): void {
+    this.chunks = [];
+  }
+  get text(): string {
+    return this.chunks.join('');
+  }
+}
+
+/**
+ * 同一参数分别经 Node 的 console（标准实现）与 log/logError（命令侧写入面）
+ * 写入同一 sink，返回两者渲染文本。
+ */
+function renderBoth(method: 'log' | 'error', args: unknown[]): { viaConsole: string; viaContract: string } {
+  const out = new Sink();
+  const err = new Sink();
+  const io: CommandIO = { stdout: out, stderr: err };
+
+  const nodeConsole = new console.Console(out, err);
+  (nodeConsole[method] as (...a: unknown[]) => void)(...args);
+  const viaConsole = method === 'log' ? out.text : err.text;
+
+  out.reset();
+  err.reset();
+  if (method === 'log') log(io, ...args);
+  else logError(io, ...args);
+  const viaContract = method === 'log' ? out.text : err.text;
+
+  return { viaConsole, viaContract };
+}
+
+describe('log/logError 与 console 输出等价', () => {
+  const cases: unknown[][] = [
+    [],
+    ['plain'],
+    ['%s and %d and %j', 'x', 3, { a: 1 }],
+    [{ nested: { deep: [1, 2, 3] } }],
+    [null, undefined, 0, false],
+    ['多字节 ✓ emoji 🎉'],
+    [''],
+  ];
+
+  it.each(cases.map((c, i) => [i, c] as [number, unknown[]]))(
+    'case %i：log(io) 与 console.log 逐字节一致',
+    (_i, args) => {
+      const { viaConsole, viaContract } = renderBoth('log', args as unknown[]);
+      expect(viaContract).toBe(viaConsole);
+    },
+  );
+
+  it.each(cases.map((c, i) => [i, c] as [number, unknown[]]))(
+    'case %i：logError(io) 与 console.error 逐字节一致',
+    (_i, args) => {
+      const { viaConsole, viaContract } = renderBoth('error', args as unknown[]);
+      expect(viaContract).toBe(viaConsole);
+    },
+  );
+
+  it('缺省 io 指向 process 标准流', () => {
+    expect(processIO.stdout).toBe(process.stdout);
+    expect(processIO.stderr).toBe(process.stderr);
+  });
+});
+
+describe('captureIO（测试注入面）', () => {
+  it('stdout/stderr 分别累积，按行可取', () => {
+    const io = captureIO();
+    log(io, 'one');
+    log(io, 'two %s', 'x');
+    logError(io, 'boom');
+    expect(io.outLines()).toEqual(['one', 'two x']);
+    expect(io.errLines()).toEqual(['boom']);
+    expect(io.outText()).toBe('one\ntwo x\n');
+    expect(io.errText()).toBe('boom\n');
+  });
+
+  it('无参 log 产生空行（console.log() 语义）', () => {
+    const io = captureIO();
+    log(io);
+    expect(io.outText()).toBe('\n');
+    expect(io.outLines()).toEqual(['']);
+  });
+
+  it('outRecords/errRecords 保留每次写入原文（多行 JSON 等同一次打印的整体）', () => {
+    const io = captureIO();
+    log(io, JSON.stringify({ a: 1 }, null, 2));
+    logError(io, 'e1');
+    logError(io, 'e2');
+
+    expect(io.outRecords()).toHaveLength(1);
+    expect(JSON.parse(io.outRecords()[0])).toEqual({ a: 1 });
+    expect(io.errRecords()).toEqual(['e1\n', 'e2\n']);
+  });
+
+  it('同一命令内 stdout 与 stderr 互不串台', () => {
+    const io = captureIO();
+    log(io, 'a');
+    logError(io, 'b');
+    log(io, 'c');
+    expect(io.outLines()).toEqual(['a', 'c']);
+    expect(io.errLines()).toEqual(['b']);
+  });
+});
+
+describe('lastJsonOutput（--json 命令输出解析正本，harness#108）', () => {
+  it('解析 captureIO 累计的 stdout 为 JSON（缺省 Record 形状）', () => {
+    const io = captureIO();
+    log(io, JSON.stringify({ sessions: 3, corrections: 3 }));
+    expect(lastJsonOutput(io)).toEqual({ sessions: 3, corrections: 3 });
+  });
+
+  it('多行 pretty JSON 整体解析（一次 log 写入）', () => {
+    const io = captureIO();
+    log(io, JSON.stringify({ a: 1, nested: { b: [2] } }, null, 2));
+    expect(lastJsonOutput(io)).toEqual({ a: 1, nested: { b: [2] } });
+  });
+
+  it('泛型参数解锁消费方已知形状（任意字段穿透）', () => {
+    const io = captureIO();
+    log(io, JSON.stringify({ flywheel: { refCoverage: 0.5 } }));
+    expect(lastJsonOutput<any>(io).flywheel.refCoverage).toBe(0.5);
+  });
+
+  it('stdout 非 JSON 时抛错（解析失败不静默吞掉）', () => {
+    const io = captureIO();
+    log(io, 'not json');
+    expect(() => lastJsonOutput(io)).toThrow();
+  });
+});
+
+describe('CommandResult 判别联合', () => {
+  it('四种 kind 均可构造，fail/usage-error 必带 reason（类型层护栏）', () => {
+    const results: CommandResult[] = [
+      { kind: 'ok' },
+      { kind: 'skip', reason: '约定未采纳' },
+      { kind: 'skip' },
+      { kind: 'fail', reason: 'gate:branch 非 master' },
+      { kind: 'usage-error', reason: '缺少 planPath' },
+    ];
+    const kinds = results.map(r => r.kind);
+    expect(kinds).toEqual(['ok', 'skip', 'skip', 'fail', 'usage-error']);
+    expect(results.filter(r => r.kind !== 'ok').map(r => ('reason' in r ? r.reason : undefined)))
+      .toEqual(['约定未采纳', undefined, 'gate:branch 非 master', '缺少 planPath']);
+  });
+});

package/src/cli/command-contract.ts

@@ -0,0 +1,108 @@
+/**
+ * CLI 命令契约（架构评审候选7）
+ *
+ * 命令实现的 interface 由两部分组成，都在本模块定义：
+ * - **返回值 `CommandResult`**：判定结果（哪个 kind、为什么）。退出码不再由命令
+ *   自己 `process.exit`，而是由 bin 依 kind 唯一映射（`process.exit` 因此只出现在
+ *   bin/harness.js 一处）。
+ * - **写入面 `CommandIO`**：流式输出去向。命令一律经注入的 io 打印，缺省 process
+ *   标准流——长命令（如 release）边跑边输出，不憋到结束由 bin 统一打印。
+ *
+ * 对外行为护栏：`processIO` 下 log/logError 的输出字节与 console.log/console.error
+ * 逐字一致（见 __tests__/command-contract.test.ts），CLI 语法与文案冻结。
+ */
+
+import { format } from 'util';
+
+/**
+ * 命令判定类别。
+ * 对外退出码只有 0/1（历史面），语义放进 kind，码值映射收敛在 bin。
+ */
+export type CommandKind = 'ok' | 'skip' | 'fail' | 'usage-error';
+
+/**
+ * 命令实现返回值（判别联合）。
+ * `fail` / `usage-error` 必附 `reason`，且 reason 要能唯一定位失败点
+ * （多闸门命令须含闸门标识）；`skip` 可选附原因。
+ */
+export type CommandResult =
+  | { kind: 'ok' }
+  | { kind: 'skip'; reason?: string }
+  | { kind: 'fail'; reason: string }
+  | { kind: 'usage-error'; reason: string };
+
+/**
+ * 命令输出流注入面（最小可写接口，`process.stdout` / `process.stderr` 结构化满足）
+ */
+export interface CommandIO {
+  stdout: { write(chunk: string): boolean };
+  stderr: { write(chunk: string): boolean };
+}
+
+/** 缺省 io：process 标准流（bin 不注入时的现状行为） */
+export const processIO: CommandIO = {
+  stdout: process.stdout,
+  stderr: process.stderr,
+};
+
+/**
+ * 与 console.log 同语义（util.format + 换行）写入 io.stdout
+ */
+export function log(io: CommandIO, ...args: unknown[]): void {
+  io.stdout.write(format(...args) + '\n');
+}
+
+/**
+ * 与 console.error 同语义（util.format + 换行）写入 io.stderr
+ */
+export function logError(io: CommandIO, ...args: unknown[]): void {
+  io.stderr.write(format(...args) + '\n');
+}
+
+/**
+ * 捕获型 io：测试注入面，替代 `spyOn(process, 'exit')` 时代的彩色字符串断言。
+ */
+export interface CapturingIO extends CommandIO {
+  /** 已写入 stdout 的全部文本 */
+  outText(): string;
+  /** 已写入 stderr 的全部文本 */
+  errText(): string;
+  /** stdout 按行切分（末尾换行不产生空尾行） */
+  outLines(): string[];
+  /** stderr 按行切分（末尾换行不产生空尾行） */
+  errLines(): string[];
+  /** stdout 每次写入的原始文本（一次 log 调用 = 一条记录，等价旧的 console.log 调用参数视图） */
+  outRecords(): string[];
+  /** stderr 每次写入的原始文本 */
+  errRecords(): string[];
+}
+
+export function captureIO(): CapturingIO {
+  let out = '';
+  let err = '';
+  const outChunks: string[] = [];
+  const errChunks: string[] = [];
+  const split = (text: string): string[] =>
+    text.endsWith('\n') ? text.slice(0, -1).split('\n') : (text === '' ? [] : text.split('\n'));
+  return {
+    stdout: { write: (chunk: string) => { out += chunk; outChunks.push(chunk); return true; } },
+    stderr: { write: (chunk: string) => { err += chunk; errChunks.push(chunk); return true; } },
+    outText: () => out,
+    errText: () => err,
+    outLines: () => split(out),
+    errLines: () => split(err),
+    outRecords: () => [...outChunks],
+    errRecords: () => [...errChunks],
+  };
+}
+
+/**
+ * 解析 --json 命令的捕获输出（测试断言面，harness#108）
+ *
+ * 与 captureIO 同住一处：它是 captureIO 的消费端正本，此前散在各命令测试里
+ * 逐字复制（JSON.parse(outText())）。缺省返回 Record 形状；消费方已知字段
+ * 形状时传泛型（如 lastJsonOutput<any>(io) 做任意字段穿透）。
+ */
+export function lastJsonOutput<T = Record<string, unknown>>(capture: CapturingIO): T {
+  return JSON.parse(capture.outText());
+}

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 单票收口）