@dommaker/harness 1.4.0 → 1.5.0

package/src/core/constraints/checkers/__tests__/check-outcome.test.ts

@@ -0,0 +1,176 @@
+/**
+ * 检查结果证据通道测试（harness#119）
+ *
+ * 背景：checker 只回 `boolean | 'skip'`，fail 的具体原因（哪个文件没登记）在 CLI
+ * 与 trace 两头都无处落脚——capability_sync 连红 22 次而无人能说出红在哪。
+ * 本套件锁住新接缝：CheckDetail（pass + evidence）经 normalizeCheckOutcome
+ * 归一后，落到 ConstraintResult.evidence 与 ExecutionTrace.evidence。
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { execFileSync } from 'child_process';
+import { ConstraintChecker } from '../../checker';
+import { normalizeCheckOutcome } from '../types';
+import { createProjectFixture } from '../../../../test-setup/project-fixture';
+import type { ExecutionTrace } from '../../../../types/trace';
+import { ConstraintViolationError } from '../../../../types/constraint';
+import type { Constraint, ConstraintResult } from '../../../../types/constraint';
+import type { MergedConstraintsConfig } from '../../../../types/project-config';
+
+const CAPABILITY_SYNC: Constraint = {
+  id: 'capability_sync',
+  kind: 'check',
+  level: 'guideline',
+  rule: 'CODE CHANGES MUST UPDATE CAPABILITIES.MD',
+  message: '核心模块变更必须同步功能清单',
+  trigger: ['module_modification'],
+  enforcement: 'update-capabilities',
+};
+
+/** 声明式夹具（harness#90）：CAPABILITIES.md + 源文件，无 git，staged 证据自然为空 */
+function fixture(name: string, files: Record<string, string>): string {
+  return createProjectFixture({ name: `cap-sync-${name}`, files });
+}
+
+describe('normalizeCheckOutcome — 三态 + 证据归一', () => {
+  it('boolean 兼容旧形状：true → satisfied / false → violated，evidence 空', () => {
+    expect(normalizeCheckOutcome(true)).toEqual({ satisfied: true, skipped: false, evidence: [] });
+    expect(normalizeCheckOutcome(false)).toEqual({ satisfied: false, skipped: false, evidence: [] });
+  });
+
+  it("'skip' → skipped 且不记证据", () => {
+    expect(normalizeCheckOutcome('skip')).toEqual({ satisfied: true, skipped: true, evidence: [] });
+  });
+
+  it('CheckDetail 透传 pass 与 evidence；缺省 evidence 归一为空数组', () => {
+    expect(normalizeCheckOutcome({ pass: false, evidence: ['a.ts'] })).toEqual({
+      satisfied: false,
+      skipped: false,
+      evidence: ['a.ts'],
+    });
+    expect(normalizeCheckOutcome({ pass: true })).toEqual({
+      satisfied: true,
+      skipped: false,
+      evidence: [],
+    });
+  });
+});
+
+/** 只含 capability_sync 的生效集：一次 run 一条 trace，不牵动其他约束 */
+function onlyCapabilitySync(): MergedConstraintsConfig {
+  return {
+    ironLaws: {},
+    guidelines: { capability_sync: CAPABILITY_SYNC },
+    prompts: {},
+    disabled: [],
+    custom: [],
+  };
+}
+
+/** 跑一次 checkConstraints，返回 capability_sync 的结果与它那条 trace */
+async function runGuideline(dir: string): Promise<{
+  result: ConstraintResult;
+  trace: ExecutionTrace;
+}> {
+  const traces: ExecutionTrace[] = [];
+  const checker = new ConstraintChecker({ record: (t) => traces.push(t) });
+  const run = await checker.checkConstraints(
+    { operation: 'module_modification', projectPath: dir },
+    onlyCapabilitySync()
+  );
+  const result = run.guidelines.find(r => r.id === 'capability_sync')!;
+  const trace = traces.find(t => t.constraintId === 'capability_sync')!;
+  return { result, trace };
+}
+
+/** 需要真 git 的用例专用手写根：夹具不建 git，而 staged 分区只能由真仓库产生 */
+function gitProjectRoot(files: Record<string, string>): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-evidence-git-'));
+  for (const [rel, content] of Object.entries(files)) {
+    const target = path.join(dir, rel);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content, 'utf-8');
+  }
+  execFileSync('git', ['init', '-q'], { cwd: dir });
+  execFileSync('git', ['config', 'user.email', 'fixture@example.com'], { cwd: dir });
+  execFileSync('git', ['config', 'user.name', 'Fixture'], { cwd: dir });
+  execFileSync('git', ['add', '.'], { cwd: dir });
+  execFileSync('git', ['commit', '-q', '-m', 'baseline'], { cwd: dir });
+  return dir;
+}
+
+describe('capability_sync 证据经编排层落到 ConstraintResult 与 trace', () => {
+  it('满足但存在仓库级未登记文件 → satisfied=true，evidence 带路径，trace 记 pass', async () => {
+    const dir = fixture('hint', {
+      'CAPABILITIES.md': '| 模块 | 文件 | 说明 |\n|------|------|------|\n| foo | src/foo.ts | foo |\n',
+      'src/foo.ts': 'export const a = 1;\n',
+      'src/unlisted.ts': 'export const b = 2;\n',
+    });
+
+    const { result, trace } = await runGuideline(dir);
+
+    expect(result.satisfied).toBe(true);
+    expect(result.skipped).toBeUndefined();
+    expect(result.evidence?.join('\n')).toContain('unlisted.ts');
+    expect(trace.result).toBe('pass');
+    expect(trace.evidence?.join('\n')).toContain('unlisted.ts');
+  });
+
+  it('违规（staged 新文件未登记）→ satisfied=false，evidence 指出该文件，trace 记 fail', async () => {
+    const dir = gitProjectRoot({
+      'CAPABILITIES.md': '| 模块 | 文件 | 说明 |\n|------|------|------|\n| foo | src/foo.ts | foo |\n',
+      'src/foo.ts': 'export const a = 1;\n',
+    });
+    fs.writeFileSync(path.join(dir, 'src/brand-new.ts'), 'export const c = 3;\n');
+    execFileSync('git', ['add', '--', 'src/brand-new.ts'], { cwd: dir });
+
+    const { result, trace } = await runGuideline(dir);
+
+    expect(result.satisfied).toBe(false);
+    expect(result.evidence?.join('\n')).toContain('src/brand-new.ts');
+    expect(trace.result).toBe('fail');
+    expect(trace.evidence?.join('\n')).toContain('src/brand-new.ts');
+  });
+
+  it('skip 不携带证据（未评估不得留下证据行）', async () => {
+    const dir = fixture('no-convention', { 'README.md': '# no capabilities convention\n' });
+
+    const { result, trace } = await runGuideline(dir);
+
+    expect(result.skipped).toBe(true);
+    expect(result.evidence).toBeUndefined();
+    expect(trace.result).toBe('skip');
+    expect(trace.evidence).toBeUndefined();
+  });
+});
+
+describe('证据随铁律异常外溢（CLI catch 分支只打印 error.message）', () => {
+  it('ConstraintViolationError 文案带出证据行', () => {
+    const error = new ConstraintViolationError({
+      id: 'docs_freshness',
+      level: 'iron_law',
+      satisfied: false,
+      message: '文档新鲜度检查未通过',
+      evidence: ['CAPABILITIES.md 登记的条目不存在:', 'src/gone.ts'],
+      checkedAt: new Date(),
+    });
+
+    expect(error.message).toContain('文档新鲜度检查未通过');
+    expect(error.message).toContain('src/gone.ts');
+  });
+
+  it('无证据时文案保持原样（旧消费方断言不受影响）', () => {
+    const error = new ConstraintViolationError({
+      id: 'no_test_simplification',
+      level: 'iron_law',
+      satisfied: false,
+      message: '禁止简化测试绕过困难',
+      checkedAt: new Date(),
+    });
+
+    expect(error.message).toBe('禁止简化测试绕过困难');
+  });
+});

package/src/core/constraints/checkers/__tests__/docs-freshness.test.ts

@@ -6,17 +6,21 @@
  * 项目根由 src/test-setup/project-fixture 声明式构造（回收仍走 mkdtemp-cleanup）。
  */
 
-import { describe, it, expect, jest } from '@jest/globals';
+import { describe, it, expect } from '@jest/globals';
 import * as fs from 'fs';
 import * as path from 'path';
 import { docsFreshness } from '../docs-freshness';
-import { buildCheckEnv } from '../types';
+import { buildCheckEnv, normalizeCheckOutcome, type CheckOutcome } from '../types';
 import { collectSourceFiles } from '../../capabilities-reconcile';
 import { createProjectFixture } from '../../../../test-setup/project-fixture';
 import type { ConstraintContext } from '../../../../types/constraint';
 
 const TABLE_HEAD = '| 模块 | 文件 | 说明 |\n|------|------|------|\n';
 
+/** 证据行拼成单串，便于按路径断言（harness#119） */
+const evidenceText = (outcome: CheckOutcome): string =>
+  normalizeCheckOutcome(outcome).evidence.join('\n');
+
 function setupProject(name: string, files: string[]): string {
   return createProjectFixture({
     name: `docs-fresh-${name}`,
@@ -66,10 +70,9 @@ describe('docs_freshness — 幽灵判定（文档→代码方向）', () => {
       dir,
       `${TABLE_HEAD}| old | src/old.ts | old |\n| deleted | src/deleted.ts | deleted |`
     );
-    const errSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
-    expect(await docsFreshness.evaluate(makeEnv(dir))).toBe(false);
-    expect(errSpy).toHaveBeenCalledWith(expect.stringContaining('src/deleted.ts'));
-    errSpy.mockRestore();
+    const outcome = await docsFreshness.evaluate(makeEnv(dir));
+    expect(normalizeCheckOutcome(outcome).satisfied).toBe(false);
+    expect(evidenceText(outcome)).toContain('src/deleted.ts');
   });
 
   it('登记的目录条目已消失 → 失败（ADR-0009 口径从严，文件+目录都查）', async () => {
@@ -78,7 +81,9 @@ describe('docs_freshness — 幽灵判定（文档→代码方向）', () => {
       dir,
       `${TABLE_HEAD}| 核心 | src/core/ | 核心 |\n| 遗魂 | src/gone/ | 已删目录 |`
     );
-    expect(await docsFreshness.evaluate(makeEnv(dir))).toBe(false);
+    const outcome = await docsFreshness.evaluate(makeEnv(dir));
+    expect(normalizeCheckOutcome(outcome).satisfied).toBe(false);
+    expect(evidenceText(outcome)).toContain('src/gone/');
   });
 
   it('登记的目录条目仍存在 → 通过', async () => {
@@ -93,7 +98,9 @@ describe('docs_freshness — 幽灵判定（文档→代码方向）', () => {
       dir,
       `${TABLE_HEAD}| routes | src/agents/routes.ts | 活 |\n| 旧路由 | src/agent-configs/routes.ts | 已删 |`
     );
-    expect(await docsFreshness.evaluate(makeEnv(dir))).toBe(false);
+    const outcome = await docsFreshness.evaluate(makeEnv(dir));
+    expect(normalizeCheckOutcome(outcome).satisfied).toBe(false);
+    expect(evidenceText(outcome)).toContain('src/agent-configs/routes.ts');
   });
 });
 
@@ -112,6 +119,8 @@ describe('docs_freshness — 内置 Runner 检查（changelog/context）', () =>
       JSON.stringify({ name: 'x', version: '2.0.0' })
     );
     fs.writeFileSync(path.join(dir, 'CHANGELOG.md'), '## [1.0.0] - 2026-01-01\n\n- old\n');
-    expect(await docsFreshness.evaluate(makeEnv(dir))).toBe(false);
+    const outcome = await docsFreshness.evaluate(makeEnv(dir));
+    expect(normalizeCheckOutcome(outcome).satisfied).toBe(false);
+    expect(evidenceText(outcome)).toContain('1.0.0 !== package.json 版本 2.0.0');
   });
 });

package/src/core/constraints/checkers/__tests__/three-state-consistency.test.ts

@@ -14,7 +14,7 @@
 import { describe, it, expect } from '@jest/globals';
 import { contextDocSync } from '../context-doc-sync';
 import { docsFreshness } from '../docs-freshness';
-import { buildCheckEnv } from '../types';
+import { buildCheckEnv, normalizeCheckOutcome, type CheckOutcome } from '../types';
 import { collectSourceFiles } from '../../capabilities-reconcile';
 import { createProjectFixture } from '../../../../test-setup/project-fixture';
 import type { ConstraintContext } from '../../../../types/constraint';
@@ -62,10 +62,16 @@ function evalDocsFreshness(dir: string) {
   );
 }
 
+/** 三态判定（比较判定结论本身，不比较返回形状——harness#119 后 checker 可带回证据） */
+function verdictOf(outcome: CheckOutcome): true | false | 'skip' {
+  const normalized = normalizeCheckOutcome(outcome);
+  return normalized.skipped ? 'skip' : normalized.satisfied;
+}
+
 /** 同一 fixture 上两条约束的判定必须一致（对照断言） */
 async function expectBoth(dir: string, verdict: true | false | 'skip'): Promise<void> {
-  expect(await evalContextDocSync(dir)).toBe(verdict);
-  expect(await evalDocsFreshness(dir)).toBe(verdict);
+  expect(verdictOf(await evalContextDocSync(dir))).toBe(verdict);
+  expect(verdictOf(await evalDocsFreshness(dir))).toBe(verdict);
 }
 
 describe('context_files 三态对照 — context_doc_sync vs docs_freshness（工单 84）', () => {
@@ -140,6 +146,8 @@ describe('docs_freshness 评估段 skip 行为变更（工单 84：约定已立
       files: ['src/old.ts'],
       capabilitiesBody: `${TABLE_HEAD}| old | src/old.ts | 活 |\n| 遗魂 | src/gone/ | 已删 |`,
     });
-    expect(await evalDocsFreshness(dir)).toBe(false);
+    const outcome = await evalDocsFreshness(dir);
+    expect(verdictOf(outcome)).toBe(false);
+    expect(normalizeCheckOutcome(outcome).evidence.join('\n')).toContain('src/gone/');
   });
 });

package/src/core/constraints/checkers/capability-sync.ts

@@ -1,17 +1,28 @@
 /**
  * capability_sync：CAPABILITIES.md 与代码同步检查（工单 21）
  *
- * 两步验证：
- *   1. Git diff 增量 — 当前变更的非测试文件是否在文档中有记录
- *   2. 全量扫描 — 源码根下所有源文件是否都在 CAPABILITIES.md 中（T-058）
+ * 两步验证，归因不同（harness#119）：
+ *   1. Git diff 增量 — 本次变更的非测试文件是否在文档中有记录 → **判违规**（有因果）
+ *   2. 全量扫描（T-058）— 源码根下所有源文件是否都在 CAPABILITIES.md 中 → **只出提示**
+ *
+ * Step 2 不判违规的理由：它是仓库级完备性不变量，与正在被评估的那次变更无因果——
+ * 一处历史漏登会让此后每次 module_* 评估恒红（studio 实测 22/22 fail，且因 fail
+ * 零证据而无人能定位）。本处保留缺口输出是为了让人看得见、能自己修，而不是为了拦。
+ *
+ * 已知缺口（ADR-0016「影响」①）：降级后仓库级漏登**没有自动拦截点**。`sync-docs --check`
+ * 单独跑会点名并 exit 1，但 CI/ship 都按「先 sync-docs 写入、后 --check」的顺序跑
+ * （2026-08-08 CI 4 连红固化的顺序），而 file 模式的写入正给缺登记自动补行
+ * （`capabilities-syncer` 的 `mode !== 'module'` 分支）、那份写入又不回提——于是流水线里
+ * 永远查不到漏登。补这个牙齿归流水线侧（sync 后 git diff 非空即失败），不在本约束里做。
+ *
+ * 例外：「有表格但零条目」= 文档被清空，判违规（历史门，此前靠 Step 2 兜，现显式化）。
  *
  * 覆盖/漏登判定不在本文件实现，统一走 capabilities-reconcile（ADR-0009）：
  * 目录条目（以 / 结尾）前缀匹配，文件条目精确匹配或路径边界后缀匹配；
  * module 模式下目录条目参与覆盖，未覆盖文件按源码根下第一级子目录聚合。
  *
  * 清单格式（计数行，mode=listing 或嗅探命中）无文件表可核对，直接放行；
- * 「有表格但零条目」不得放行，无表格的散文文档保持历史放行；
- * 检查异常时 fail-open 但输出 console.warn 保留可观测性。
+ * 无表格的散文文档保持历史放行；检查异常时 fail-open 但输出 console.warn 保留可观测性。
  *
  * ADR-0001 存在性探测：项目根无 CAPABILITIES.md（未采用该约定）时返回 'skip'，
  * 不计 pass/fail，避免在未采用约定的项目上全量误报。
@@ -23,7 +34,7 @@ import { isCapabilityListingFormat } from '../capabilities-parser';
 import { getCapabilitiesMode } from '../../project-config-loader';
 import { detectSourceRoots } from '../../../utils/detect-source-roots';
 import { reconcileCapabilities, significantCodeChanges } from '../capabilities-reconcile';
-import type { ConstraintCheck } from './types';
+import { formatEvidence, type ConstraintCheck } from './types';
 
 export const capabilitySync: ConstraintCheck = {
   id: 'capability_sync',
@@ -59,25 +70,52 @@ export const capabilitySync: ConstraintCheck = {
         sourceRoots,
       });
 
-      // 零条目门槛：有表格但什么都没登记时不得直接放行
-      const gateOpen = verdict.coverageEntries.length === 0 && !verdict.hasTable;
-      if (gateOpen) return true;
+      // 无表格的散文文档：历史放行语义
+      if (!verdict.hasTable) return true;
 
-      // ── Step 1: Git diff 增量检查（每个变更文件都必须被覆盖）──
-      if (verdict.uncoveredChanges.length > 0) return false;
+      // 文档退化门：有表格却什么都没登记（限定「源码根下确有文件」——空仓 + 空表没有可登记
+      // 对象，历史行为是放行，本票不顺手扩大 fail 面）
+      if (verdict.coverageEntries.length === 0 && population.length > 0) {
+        return {
+          pass: false,
+          evidence: ['CAPABILITIES.md 有表格但零条目登记，运行 harness sync-docs 或直接补登记'],
+        };
+      }
 
-      // ── Step 2: 全量源码根扫描（T-058 修复核心）──
-      if (capabilitiesMode === 'module') {
-        if (verdict.uncoveredDirs.length > 0) return false;
-      } else if (verdict.uncoveredFiles.length > 0) {
-        return false;
+      // ── Step 1: Git diff 增量检查（与本次变更有因果，每个变更文件都必须被覆盖）──
+      if (verdict.uncoveredChanges.length > 0) {
+        return {
+          pass: false,
+          evidence: formatEvidence(
+            `本次变更有 ${verdict.uncoveredChanges.length} 个文件未登记进 CAPABILITIES.md`,
+            verdict.uncoveredChanges
+          ),
+        };
+      }
+
+      // ── Step 2: 全量源码根扫描（T-058）——仓库级漂移，只提示不判违规，见文件头 ──
+      const gaps = capabilitiesMode === 'module' ? verdict.uncoveredDirs : verdict.uncoveredFiles;
+      if (gaps.length > 0) {
+        const kind = capabilitiesMode === 'module' ? '未登记模块目录' : '未登记源文件';
+        return {
+          pass: true,
+          evidence: formatEvidence(
+            `CAPABILITIES.md ${kind} ${gaps.length} 项（仓库级漂移，与本次变更无关；修复: harness sync-docs）`,
+            gaps
+          ),
+        };
       }
 
       return true;
     } catch (err) {
-      // fail-open 语义保留，但必须可观测：静默吞错会让解析 bug 变成「永远通过」
+      // fail-open 语义保留，但异常放行也要落地可见：warn 只进本地 stderr，
+      // 进不了 trace——静默吞错会让解析 bug 变成「永远通过」（harness#119 同族问题）
+      const reason = err instanceof Error ? err.message : String(err);
       console.warn('[capability_sync] 检查执行异常，默认放行：', err);
-      return true;
+      return {
+        pass: true,
+        evidence: [`检查异常，按 fail-open 放行: ${reason}（本次结果不代表文档已同步）`],
+      };
     }
   },
 };

package/src/core/constraints/checkers/docs-freshness.ts

@@ -15,6 +15,7 @@ import { detectSourceRoots } from '../../../utils/detect-source-roots';
 import { reconcileCapabilities } from '../capabilities-reconcile';
 import type { DocFreshnessCheck } from '../../../types/project-config';
 import type { ConstraintCheck, CheckEnv } from './types';
+import { formatEvidence } from './types';
 
 /**
  * 内置默认文档新鲜度检查配置
@@ -95,10 +96,13 @@ export const docsFreshness: ConstraintCheck = {
     // Step 1: 文件表格式 — 登记的条目（文件+目录）是否仍存在（ADR-0009）
     const deadEntries = findDeadCapabilityEntries(projectPath, env);
     if (deadEntries.length > 0) {
-      // 报出具体条目：此前只返回 false，CLI 只能打印通用提示，
-      // 幽灵条目 basename 碰撞时 sync-docs 也不剔除，用户无从定位（2026-08-08 studio CI 4 连红）
-      console.error(`[docs_freshness] CAPABILITIES.md 登记的条目不存在: ${deadEntries.join(', ')}`);
-      return false;
+      // 证据通道点名条目（harness#119）：此前是 console.error 侧信道（2026-08-08 studio
+      // CI 4 连红时的临时办法），CLI 结构化输出与 trace 两头都拿不到，
+      // 铁律拦截时用户只看到一句通用提示，basename 碰撞下无从定位
+      return {
+        pass: false,
+        evidence: formatEvidence('CAPABILITIES.md 登记的条目不存在', deadEntries),
+      };
     }
 
     // Step 2: 能力清单格式 + CLAUDE.md + CHANGELOG — 通过 FreshnessRunner
@@ -120,7 +124,16 @@ export const docsFreshness: ConstraintCheck = {
         results = runner.runAll({ checks: getBuiltInDocFreshnessConfig() }, projectPath, { requiredDirs });
       }
 
-      if (!results.every(r => r.pass)) return false;
+      const failed = results.filter(r => !r.pass);
+      if (failed.length > 0) {
+        return {
+          pass: false,
+          evidence: formatEvidence(
+            '文档新鲜度检查未通过',
+            failed.map(r => `${r.label}: ${r.message ?? '未通过'}`)
+          ),
+        };
+      }
     } catch {
       // FreshnessRunner 失败不影响整体
     }

package/src/core/constraints/checkers/index.ts

@@ -80,5 +80,12 @@ export function registeredCheckCount(): number {
   return registry.size;
 }
 
-export { buildCheckEnv } from './types';
-export type { ConstraintCheck, CheckEnv, CheckOutcome, EvidenceProviders } from './types';
+export { buildCheckEnv, normalizeCheckOutcome } from './types';
+export type {
+  ConstraintCheck,
+  CheckEnv,
+  CheckOutcome,
+  CheckDetail,
+  NormalizedOutcome,
+  EvidenceProviders,
+} from './types';

package/src/core/constraints/checkers/types.ts

@@ -73,8 +73,64 @@ export function buildCheckEnv(
  * - true = 满足（pass）
  * - false = 违反（fail）
  * - 'skip' = 未评估（项目未采用对应约定，或证据 flag 未接线），不计 pass/fail
+ * - CheckDetail = 判定 + 证据行（harness#119）
  */
-export type CheckOutcome = boolean | 'skip';
+export type CheckOutcome = boolean | 'skip' | CheckDetail;
+
+/**
+ * 带证据的检查结果（harness#119）
+ *
+ * 动机：只回布尔时，fail 的具体原因（哪个文件没登记）在 CLI 与 trace 两头都落脚不了，
+ * 一条恒红的约束无法被诊断。证据行由 checker 自行措辞（自描述、可直接给人看），
+ * 编排层只负责透传与打印，不参与解释内容。
+ *
+ * `pass: true` + 非空 evidence = 「满足但有提示」：不进 pass/fail 统计口径，
+ * 仅作为可观测输出（如仓库级文档漂移——与本次变更无因果，不该判违规）。
+ */
+export interface CheckDetail {
+  /** false = 违反；true = 满足 */
+  pass: boolean;
+  /** 证据行（每条自描述，如「变更文件未登记: src/foo.ts」） */
+  evidence?: string[];
+}
+
+/** 归一后的检查结果：编排层 / gate 唯一消费形状 */
+export interface NormalizedOutcome {
+  satisfied: boolean;
+  skipped: boolean;
+  evidence: string[];
+}
+
+/** 证据条数上限：trace 是 JSONL，缺口上百项时不能整仓落盘 */
+export const MAX_EVIDENCE_ITEMS = 10;
+
+/**
+ * 组装证据行：一行说明 + 逐条依据（超限截断）
+ *
+ * 每行自描述且不带缩进——缩进由消费端（CLI / gate 理由 / 铁律异常文案）决定，trace 原样存。
+ * 修复入口不写在这里：那是各约束自己的事，写进各自的 summary 行（docs_freshness 的
+ * 幽灵条目与 sync-docs 无关，共用一个指针会误导）。
+ */
+export function formatEvidence(summary: string, items: string[]): string[] {
+  const shown = items.slice(0, MAX_EVIDENCE_ITEMS);
+  const hidden = items.length - shown.length;
+  return [...(summary ? [summary] : []), ...shown, ...(hidden > 0 ? [`…另 ${hidden} 项`] : [])];
+}
+
+/**
+ * 归一 CheckOutcome（boolean | 'skip' | CheckDetail）为统一形状
+ *
+ * skip 恒不携带证据：未评估的约束不得留下证据行（否则统计侧会把「没查」读成「查出问题」）。
+ */
+export function normalizeCheckOutcome(outcome: CheckOutcome): NormalizedOutcome {
+  if (outcome === 'skip') return { satisfied: true, skipped: true, evidence: [] };
+  if (typeof outcome === 'boolean') return { satisfied: outcome, skipped: false, evidence: [] };
+  return {
+    satisfied: outcome.pass,
+    skipped: false,
+    evidence: outcome.evidence ?? [],
+  };
+}
 
 /**
  * 单条约束检查实现
@@ -82,7 +138,7 @@ export type CheckOutcome = boolean | 'skip';
 export interface ConstraintCheck {
   /** 约束 ID（与 definitions 一致） */
   id: string;
-  /** 检查主体：true = 满足；false = 违反；'skip' = 未评估 */
+  /** 检查主体：true = 满足；false = 违反；'skip' = 未评估；CheckDetail = 判定 + 证据行 */
   evaluate(env: CheckEnv): Promise<CheckOutcome> | CheckOutcome;
 }
 

package/src/gates/CONTEXT.md

@@ -9,7 +9,7 @@
 - 定义表：`GATE_DEFINITIONS`（`definitions.ts`）——id/description/默认 order/CLI 元数据；CLI 元数据形状即 `CommandDefinition`（ADR-0007：门禁与非门禁共用同一命令定义形状，bin 单引擎单循环；门禁特有语义 = `subcommandStrict:false` 未知子命令落回默认 action + `bareRunsAction:true` 裸跑执行 action）；bin/harness.js 注册表驱动生成 6 门禁命令（纯数据模块，禁 import 实现，保 --help 懒加载；CLI 实现引用为 module+export，per-command 懒加载，H5）
 - 执行器：`runGates`（`runner.ts`）——按 order 升序；deny 单调（下游 abstain 不得改回 allow）+ ask 枚举预留 fail-closed = deny；决策浅冻结
 - 生效集：`getEffectiveGates(projectRoot)`（`effective-gates.ts`）——对齐 getEffectiveConstraints 裁剪模式：config.yml `gates.order` 重排 + `gates.<id>.enabled:false` 移除；enabled 段未注册校验与裁剪走 core/effective-set 共享筛选器（throw 模式），order 重排与重复 id 检测留本侧
-- checker-as-guard 接线点：`createCheckerGate(check)`（`checker-gate.ts`）——ConstraintCheck → Gate（studio #129 随动）；false→deny，true/'skip'→abstain；env 经 `buildCheckEnv(..., 'none')` 构造（显式不接证据，语义见 core/constraints/checkers/types.ts 工厂 doc）
+- checker-as-guard 接线点：`createCheckerGate(check)`（`checker-gate.ts`）——ConstraintCheck → Gate（studio #129 随动）；判定经唯一归一点 `normalizeCheckOutcome`（harness#119/ADR-0016）：`false` 或 `CheckDetail.pass=false` → deny（证据行随理由带出），`true`（含 pass+提示）/'skip' → abstain；env 经 `buildCheckEnv(..., 'none')` 构造（显式不接证据，语义见 core/constraints/checkers/types.ts 工厂 doc）
 - 门禁类：`ReviewGate` / `SecurityGate` / `PerformanceGate` / `ContractGate` / `SpecAcceptanceGate` / `CommandGate`（各自执行细节私有，保留 `check()`/`scan()` 报告方法）；SpecAcceptanceGate 的 runner 输出解读与 e2e 判负都从 `core/validators/test-output.ts` 的 `judgeTestRun` 取（解析收口 ADR-0012、判定依据 ADR-0014，本层既不自带正则也不自写判定 `if`）
 - `types.ts` — GateResult（报告结构，保留）/ GateContext / GateDecision 等公共类型 + 报告构造器 `pass` / `fail` / `fromError`（动态 passed 走 `gateResult`）：timestamp 与 duration 口径唯一落点，门禁实现禁止手写 GateResult 字面量（duration 是可选字段，漏写无编译期报错）
 - 便捷工厂函数：createReviewGate / createSecurityGate / createPerformanceGate / createContractGate / createSpecAcceptanceGate / createCommandGate

package/src/gates/__tests__/checker-gate.test.ts

@@ -37,6 +37,30 @@ describe('createCheckerGate', () => {
     expect(decision.result.message).toContain('跳过');
   });
 
+  // harness#119：CheckDetail 形状接入后，映射必须经 normalizeCheckOutcome——
+  // 写 `outcome !== false` 会把 { pass: false } 读成「不是 false」= 通过，deny 静默丢失
+  it('CheckDetail{pass:false} → deny，理由带出证据行', async () => {
+    const gate = createCheckerGate({
+      id: 'detail-fail',
+      evaluate: () => ({ pass: false, evidence: ['src/gone.ts'] }),
+    });
+    const decision = await gate.evaluate(ctx);
+    expect(decision.status).toBe('deny');
+    expect(decision.result.passed).toBe(false);
+    expect(decision.result.message).toContain('判定违规');
+    expect(decision.result.message).toContain('src/gone.ts');
+  });
+
+  it('CheckDetail{pass:true} + 提示证据 → abstain（提示不得变拦截）', async () => {
+    const gate = createCheckerGate({
+      id: 'detail-hint',
+      evaluate: () => ({ pass: true, evidence: ['仓库级漂移 1 项', 'src/drifted.ts'] }),
+    });
+    const decision = await gate.evaluate(ctx);
+    expect(decision.status).toBe('abstain');
+    expect(decision.result.message).toContain('通过');
+  });
+
   it('决策浅冻结（单调语义契约）', async () => {
     const gate = createCheckerGate(contextFlag('flag-freeze', () => true));
     const decision = await gate.evaluate(ctx);

package/src/gates/checker-gate.ts

@@ -8,7 +8,7 @@
  */
 
 import type { ConstraintCheck } from '../core/constraints/checkers';
-import { buildCheckEnv } from '../core/constraints/checkers';
+import { buildCheckEnv, normalizeCheckOutcome } from '../core/constraints/checkers';
 import type { Gate, GateContext, GateDecision } from './types';
 import { gateResult } from './types';
 import { decisionFromResult } from './decision';
@@ -16,7 +16,8 @@ import { decisionFromResult } from './decision';
 /**
  * 将已注册 checker 适配为统一 Gate（checker-as-guard 接线点）
  *
- * 判定映射：false（违反）→ deny；true（满足）/ 'skip'（未评估）→ abstain。
+ * 判定映射：violated（false 或 CheckDetail.pass=false）→ deny；
+ * 满足 / 'skip'（未评估）→ abstain。违规证据随理由带出。
  *
  * @param check 已注册的 ConstraintCheck（经 checkers 注册表取回）
  * @param order 门禁顺序（供 guard 链排序）
@@ -29,19 +30,14 @@ export function createCheckerGate(check: ConstraintCheck, order = 0): Gate {
       const startTime = Date.now();
       const projectPath = ctx.projectPath || process.cwd();
       const env = buildCheckEnv({ operation: 'manual', projectPath }, 'none');
-      const outcome = await check.evaluate(env);
-      return decisionFromResult(
-        gateResult(
-          check.id,
-          outcome !== false,
-          outcome === false
-            ? `checker "${check.id}" 判定违规`
-            : outcome === 'skip'
-              ? `checker "${check.id}" 跳过（证据未接线）`
-              : `checker "${check.id}" 通过`,
-          startTime
-        )
-      );
+      const outcome = normalizeCheckOutcome(await check.evaluate(env));
+      const evidence = outcome.evidence.map((e) => `\n  - ${e}`).join('');
+      const reason = outcome.skipped
+        ? `checker "${check.id}" 跳过（证据未接线）`
+        : outcome.satisfied
+          ? `checker "${check.id}" 通过`
+          : `checker "${check.id}" 判定违规${evidence}`;
+      return decisionFromResult(gateResult(check.id, outcome.satisfied, reason, startTime));
     },
   };
 }

package/src/types/constraint.ts

@@ -108,7 +108,16 @@ export interface ConstraintResult {
   
   /** 消息 */
   message?: string;
-  
+
+  /**
+   * 证据行（harness#119）
+   *
+   * checker 经 CheckDetail 返回的具体判定依据（如未登记的文件路径）。
+   * 违规时随 message 一并展示；满足但非空时为「提示」（不进 pass/fail 统计）。
+   * skip 恒为空——未评估不得留下证据行。
+   */
+  evidence?: string[];
+
   /** 建议操作 */
   requiredAction?: string;
   
@@ -194,7 +203,12 @@ export class ConstraintViolationError extends Error {
   public readonly result: ConstraintResult;
 
   constructor(result: ConstraintResult) {
-    super(result.message || 'Constraint violation');
+    // 铁律违规在 checkConstraints 处直接 throw，CLI 的结构化输出块走不到这里，
+    // error.message 是判定证据唯一的外溢面（harness#119）
+    const detail = result.evidence?.length
+      ? `：\n${result.evidence.map((line) => `  - ${line}`).join('\n')}`
+      : '';
+    super(`${result.message || 'Constraint violation'}${detail}`);
     this.name = 'ConstraintViolationError';
     this.result = result;
   }