@dommaker/harness 1.4.0 → 1.6.0

package/src/core/CONTEXT.md

@@ -1,16 +1,15 @@
 # core/
 
 ## 职责
-约束引擎核心：check/prompt 二元约束系统（ADR-0001）、生效集合并（effective-constraints）、检查点验证器(CSO/passes-gate)、会话管理、Spec 验证器、项目配置加载。
+约束引擎核心：check/prompt 二元约束系统（ADR-0001）、生效集合并（effective-constraints）、检查点验证器(CSO/passes-gate)、Spec 验证器、项目配置加载。
 
 ## 核心导出
-- `constraints/` — 约束定义(IRON_LAWS/GUIDELINES/PROMPTS) + 检查引擎(ConstraintChecker，拦截统一由 checkBeforeExecution 承担，ADR-0004) + 缓存(CheckCache：TTL 缓存 + 计数采样，H6/G5 起公开导出) + 注入渲染(injection-renderer) + 落点写入器(injection-writer：「声明→对照→幂等替换」中 marker-range 替换的唯一 writer——replaceStandaloneRange/replaceEnclosedRange/cutMarkerBlock + 半标记守护；落点路由读写两侧同住此模块 resolveInjectionTarget(CLAUDE.md 有标记段优先、否则 AGENTS.md PRESERVE:governance，studio #307)/resolveGovernanceLanding(init 写侧，含旧版无标记 Governance Rules 块豁免)，ADR-0011) + Agent prompt 渲染(agent-prompt-renderer：trigger 参数化分组渲染，role 路由留 studio，H6/G6)/漂移校验(injection-drift：纯检测只读，路由消费 injection-writer)/使用统计(usage-report：constraints report·retire 的只读数据层，读 trace 两个入口——`readProjectTracesReport()` 带 `skippedLines`、`readProjectTraces()` 兼容包装丢计数；报告模型 `ConstraintsUsageReport` 的降级位 = `traceFileExists` + `skippedLines`，harness#100)/清单对照(capabilities-reconcile：CAPABILITIES.md 与代码实况的覆盖/幽灵判定唯一实现，capability_sync·docs_freshness·sync-docs 共消费，ADR-0009)；CheckEnv 生产侧唯一构造点 `buildCheckEnv(context, providers|'none')`（checkers/types.ts：providers = 证据接线，git 两项绑 GitEvidence 实例，'none' = 显式不接 → evidence flag checker 按契约 skip）
-- `git-evidence.ts` — 全仓唯一 git 取证点（#87）：`createGitEvidence(projectPath, run?)` 返回 `GitEvidence{stagedDiff, changedFileNames(staged), headDirs}`，seam 上两个真 adapter（缺省 `realGitCommandRunner` 走真 git / 注入 runner 供计数与替身）。命令级 memo 落在此实例（含失败结果），实例生命周期 = 一次 check run，故 context-builder 与 ConstraintChecker 传同一实例即共用证据；判定语义与迁移前一致（diff 取证失败 → 空串，`git ls-tree` 失败 → null = 所有目录视为新）；`parseHeadDirs`/`splitFileNames` 是配套纯函数
+- `constraints/` — 约束定义(IRON_LAWS/GUIDELINES/PROMPTS) + 检查引擎(ConstraintChecker，拦截统一由 checkBeforeExecution 承担，ADR-0004) + 缓存(CheckCache：TTL 缓存 + 计数采样，H6/G5 起公开导出) + 注入渲染(injection-renderer) + 落点写入器(injection-writer：「声明→对照→幂等替换」中 marker-range 替换的唯一 writer——replaceStandaloneRange/replaceEnclosedRange/cutMarkerBlock + 半标记守护；落点路由读写两侧同住此模块 resolveInjectionTarget(CLAUDE.md 有标记段优先、否则 AGENTS.md PRESERVE:governance，studio #307)/resolveGovernanceLanding(init 写侧，含旧版无标记 Governance Rules 块豁免)，ADR-0011) + Agent prompt 渲染(agent-prompt-renderer：trigger 参数化分组渲染，role 路由留 studio，H6/G6)/漂移校验(injection-drift：纯检测只读，路由消费 injection-writer)/使用统计(usage-report：constraints report·retire 的只读数据层，读 trace 两个入口——`readProjectTracesReport()` 带 `skippedLines`、`readProjectTraces()` 兼容包装丢计数；报告模型 `ConstraintsUsageReport` 的降级位 = `traceFileExists` + `skippedLines`，harness#100)/清单对照(capabilities-reconcile：CAPABILITIES.md 与代码实况的覆盖/幽灵判定唯一实现，capability_sync·docs_freshness·sync-docs 共消费，ADR-0009)；CheckEnv 生产侧唯一构造点 `buildCheckEnv(context, providers|'none')`（checkers/types.ts：providers = 证据接线，git 两项绑 GitEvidence 实例，'none' = 显式不接 → evidence flag checker 按契约 skip）；判定接缝 `CheckOutcome = boolean | 'skip' | CheckDetail{pass, evidence}`（harness#119/ADR-0016）——编排层与 `gates/checker-gate` 一律经唯一归一点 `normalizeCheckOutcome()` 取三态 + 证据，不各自 `=== false`（对新形状会误判）；证据行由 checker 自行措辞（自描述、不带缩进），组装与截断策略单点在 `formatEvidence()`/`MAX_EVIDENCE_ITEMS`（同住 checkers/types.ts）；证据四出口 = `ConstraintResult.evidence` → CLI 结论块/提示块、`ExecutionTrace.evidence`、铁律 `ConstraintViolationError.message`（铁律违规直接 throw，异常文案是其证据唯一外溢面）；检查引擎双出口——`checkConstraints`（block：首个铁律违规即抛，throw 契约不动）与 `collectConstraints`（collect：共享检查体、不抛、全量收集，report 的不抛出口，架构评审候选1）
+- `git-evidence.ts` — check 链路的 git 取证唯一接缝（#87，范围按 ADR-0021 收窄；`spec/validator` 的 staged 列表同型复用）：`createGitEvidence(projectPath, run?)` 返回 `GitEvidence{stagedDiff, changedFileNames(staged), headDirs}`，seam 上两个真 adapter（缺省 `realGitCommandRunner` 走真 git / 注入 runner 供计数与替身）。命令级 memo 落在此实例（含失败结果），实例生命周期 = 一次 check run，故 context-builder 与 ConstraintChecker 传同一实例即共用证据；判定语义与迁移前一致（diff 取证失败 → 空串，`git ls-tree` 失败 → null = 所有目录视为新）；`parseHeadDirs`/`splitFileNames` 是配套纯函数
 - `constraints/context-builder.ts` — 只装配不取证：`buildConstraintContext(options.evidence?)` 与 `detectTrigger(options.evidence?)` 经 GitEvidence 取 git 事实（不传 = 自建真 adapter），本模块无 child_process import；其余证据标志（traces/文档标记）仍为本地探测
 - `effective-constraints.ts` — `getEffectiveConstraints(projectRoot, {preset?})`：全仓唯一生效集来源（内置 → preset → config.yml 禁用（内置与 custom 同效）→ custom 追加（禁用/已退役的不追加）→ scenes 过滤）；`getMergedConstraintsConfig(projectRoot, {preset?})`：同链路的完整 MergedConstraintsConfig 形状（含 disabled/custom/unknownIds），内置工单 23 优先级规则（--preset 仅在无项目自定义配置时生效），check 命令经此入口；`lintEffectiveConfig` 配置诊断
 - `effective-set.ts` — `filterEnabledEntries(knownIds, entries, {onUnknownId})`：约束侧（collect）与门禁侧（throw）共用的 config 条目筛选器
-- `validators/` — checkpoints、passes-gate、CSO 验证器；`test-output.ts` —「测试产物解读」唯一实现：`extractFailures` 提取函数 + `judgeTestRun` 判定入口（退出码为主 + 行首锚定的文本失败信号交叉否决；文本救不回非零退出，`allowPartialPass` 只作用于文本否决那一维），passes-gate 与 `gates/acceptance` 的结论一律从它取、各自体内不写判定 `if`（解析收口 ADR-0012，判定依据 ADR-0014）；**不读覆盖率**——harness 核心判定对覆盖率不取数不执法，判覆盖率的两处（CLI `passes-gate --coverage`、`gates/performance`）各自读 json-summary，`extractCoverage` 与 `TaskTestResult.coverage` 已随 ADR-0015 删除；`PassesGate.runTests(workDir)` 的执行与证据落盘根是**必传形参**，本层不再取 cwd（harness#95，约定正本见 `src/cli/commands/CONTEXT.md`）；`detectTestCommand` 是测试命令探测唯一正本（模块级导出：test:ci → test 排 echo 占位 → test:e2e → test:coverage → Python 标记 pyproject.toml/pytest.ini → go.mod，探不到返回 undefined，兜底归调用方——CLI 映射 skip、PassesGate 内部 fail-closed，不再兜底 'npm test'；CLI 本地版已删，架构评审 A2）；PassesGate 扩展注册表（registerExtension/unregisterExtension/getExtensionNames/runAllTests/checkAllPasses + PassesGateExtension/ExtensionTestResult 两类型与包根导出）已整段删除——零 adapter 假想 seam 且扩展结果本就不参与 allowed 判定，需要扩展测试类型时按 ADR-0014 判例在 `judgeTestRun` 层加，不恢复旧 seam（harness#104，架构评审 B1）；包内模块，不进 `src/index.ts` 导出面
-- `session/` — 会话管理
+- `validators/` — checkpoints、passes-gate、CSO 验证器；`test-output.ts` —「测试产物解读」唯一实现：`extractFailures` 提取函数 + `judgeTestRun` 判定入口（退出码为主 + 行首锚定的文本失败信号交叉否决；文本救不回非零退出，`allowPartialPass` 只作用于文本否决那一维），passes-gate 与 `gates/acceptance` 的结论一律从它取、各自体内不写判定 `if`（解析收口 ADR-0012，判定依据 ADR-0014）；**不读覆盖率**——harness 核心判定对覆盖率不取数不执法，判覆盖率的两处（CLI `passes-gate --coverage`、`gates/performance`）各自读 json-summary，`extractCoverage` 与 `TaskTestResult.coverage` 已随 ADR-0015 删除；`PassesGate.runTests(workDir)` 的执行与证据落盘根是**必传形参**，本层不再取 cwd（harness#95，约定正本见 `src/cli/commands/CONTEXT.md`）；`detectTestCommand` 是测试命令探测唯一正本（模块级导出：test:ci → test 排 echo 占位 → test:e2e → test:coverage → Python 标记 pyproject.toml/pytest.ini → go.mod，探不到返回 undefined，兜底归调用方——CLI 映射 skip、PassesGate 内部 fail-closed，不再兜底 'npm test'；CLI 本地版已删，架构评审 A2）；PassesGate 扩展注册表（registerExtension/unregisterExtension/getExtensionNames/runAllTests/checkAllPasses + PassesGateExtension/ExtensionTestResult 两类型与包根导出）已整段删除——零 adapter 假想 seam 且扩展结果本就不参与 allowed 判定，需要扩展测试类型时按 ADR-0014 判例在 `judgeTestRun` 层加，不恢复旧 seam（harness#104，架构评审 B1）；PassesGate 公开面 = `check()` + `runTests()` 两个真实消费点，`setPasses`/`getTestResult`/`checkTestFileChanges` 三方法与死数据 `PROTECTED_TEST_PATTERNS`、私有 `testResults` 缓存已随 ADR-0022（双仓零消费者）删除，历史 AC-007「保留 setPasses 向后兼容」同案推翻；包内模块，不进 `src/index.ts` 导出面
 - `spec/validator` — SpecValidator
 - `project-config-loader` — 项目配置加载 + 约束合并（mergeConstraints 内含 preset 裁剪：presets/ 纯数据 + 未知名回落 standard，禁用到未知 id 经 effective-set 共享筛选器 collect 模式）；`getGovernanceConfig` 是全仓唯一允许手写钻取 `config.governance` 的点（工单 84），消费方一律经它或经 `resolveContextFiles`（三态：unconfigured / enabled-empty / enabled，dirs 元素类型在此收口）取数据，不得再自己 cast `Record<string, unknown>`；checker 对前两态一律 skip，自动探测回落只属于 init/扫描类工具流调用方
 
@@ -25,9 +24,10 @@
 - check 层必须带真实 checker（注册表闭环，引用未注册 checker 构建报错）
 - Iron Law 违规必须 throw ConstraintViolationError
 - 上行数据一律注入，不在 core 内 require 上层（harness#88）：trace 记录器经 `ConstraintChecker` 构造参数注入（缺省 no-op，`getInstance()`/`constraintChecker` 即未接线的默认实例，只评估不写 trace），真实收集器由组合根接线（CLI check/report、`bootstrapHarness`）；CAPABILITIES.md 能力清单计数经 `capabilities-parser` 的 `CapabilityDefinitionSource` 由 cli 侧注入定义表
-- git 事实只能经 `constraints/git-evidence.ts` 的 adapter 取（#87）：core/cli 内不得出现 `execSync('git …')`；一次 run 一份实例、沿调用链显式传递（CLI check → buildConstraintContext → checkConstraints），memo 既不做成模块级全局也不做成单例字段
+- git **取证**（读判定证据）在 check 链路内只能经 `constraints/git-evidence.ts` 的 adapter 取（#87，适用范围按 ADR-0021 收窄为「check 链路唯一」，不再声称全仓唯一）：`context-builder` / `checker` / `CheckEnv` / `validators` 这条判定链内不得出现 `execSync`/`execAsync`/`execFileAsync` 跑 git；`spec/validator` 的 staged 文件列表与 `changedFileNames(staged:true)` 同型，已收口（就地 `createGitEvidence(cwd)`，测试注入 runner）；一次 run 一份实例、沿调用链显式传递（CLI check → buildConstraintContext → checkConstraints），memo 既不做成模块级全局也不做成单例字段。**链外站点记名豁免**（语义异质：不要 memo、不要 once 语义、失败处理各异，硬并入会造出宽 interface）——`cli/commands/release.ts`（发布流程编排，非判定证据）、`gates/review.ts` 与 `cli/commands/review.ts`（PR 审查流，gh/日志语义）、`knowledge/import.ts`（导入启发式，失败记 ImportError 降级）。豁免清单外新增 git 站点先回答「在不在判定链内」；`validators/passes-gate.ts` 的 `git diff --name-only` 站点已随 ADR-0022 删 `checkTestFileChanges` 消失，判定链内当下无站外 git 调用点
 
 ## 注意事项
 - 零 Token 成本：所有分析纯文件操作，无 LLM 调用
 - 约束配置支持 .harness/config.yml 自定义合并（preset 真实生效）
 - 存在性探测约束（capability_sync/docs_freshness/context_doc_sync）在约定文件缺失，或 context_files 约定已立但无目标（enabled-empty）时 skip，不计 pass/fail；context_doc_sync 与 docs_freshness 对三态判定同构（工单 84）
+- **fail 必须可归因到被评估的对象**（harness#119/ADR-0016）：`capability_sync` 的 Step 1（staged 增量未登记）判违规，Step 2（T-058 全量完备性）与本次变更无因果、只出提示（`satisfied=true` + evidence）；「有表格但零条目 + 确有源文件」的文档退化门仍判违规（显式，不借 Step 2 兜）。2026-09-08 前 `capability_sync` 恒红（studio 22/22）就是这条错位造成的。注意降级并不换来执法：`sync-docs --check` 单独跑才 exit 1，CI/ship 都先跑写入（file 模式自补行）再 `--check`，harness 自有 CI 那步还是 `continue-on-error`——仓库级漏登目前无自动拦截点，缺口与修法见 ADR-0016「影响」

package/src/core/constraints/__tests__/collect-constraints.test.ts

@@ -0,0 +1,66 @@
+/**
+ * collectConstraints — 收集模式（架构评审候选1）
+ *
+ * 与 checkConstraints 共享检查体，唯一差别是不 throw：
+ * 铁律违规不抛、全量收进 ironLaws、guidelines 照常、passed 如实。
+ * block 模式的 throw 契约由 checker-extra / iron-laws 既有用例钉住，这里只测 collect 侧。
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import { ConstraintChecker } from '../checker';
+import type { ConstraintContext, ConstraintResult } from '../../../types/constraint';
+
+// 缺省 no-op trace 记录器：本套件不验 trace 面（trace 面由 trace-injection 套件钉住）
+const checker = new ConstraintChecker();
+
+/** 只违 no_completion_without_verification，其余铁律满足（flag 口径同 checker-extra） */
+const VIOLATING: ConstraintContext = {
+  operation: 'code_implementation',
+  hasTest: false,
+  hasVerificationEvidence: false,
+  hasRequirement: true,
+  hasSingleTask: true,
+  taskDescription: 'single focused change',
+};
+
+const CLEAN: ConstraintContext = {
+  operation: 'code_implementation',
+  hasTest: true,
+  hasVerificationEvidence: true,
+  hasRequirement: true,
+  hasSingleTask: true,
+  taskDescription: 'single focused change',
+};
+
+describe('collectConstraints（收集模式，不抛）', () => {
+  it('铁律违规不抛 —— resolves 而非 rejects', async () => {
+    await expect(checker.collectConstraints(VIOLATING)).resolves.toBeDefined();
+  });
+
+  it('违规铁律如实进 ironLaws：satisfied=false 且 passed=false', async () => {
+    const result = await checker.collectConstraints(VIOLATING);
+    const violated = result.ironLaws.find((r: ConstraintResult) => r.id === 'no_completion_without_verification');
+    expect(violated).toBeDefined();
+    expect(violated!.satisfied).toBe(false);
+    expect(result.passed).toBe(false);
+  });
+
+  it('首个违规不截断：触发域内后续铁律照常评估', async () => {
+    const result = await checker.collectConstraints(VIOLATING);
+    const ids = result.ironLaws.map((r: ConstraintResult) => r.id);
+    expect(ids).toContain('incremental_progress');
+    expect(ids).toContain('no_implementation_without_requirement');
+  });
+
+  it('guidelines 照常执行，warningCount 与不满意条目同口径', async () => {
+    const result = await checker.collectConstraints(VIOLATING);
+    expect(result.guidelines.length).toBeGreaterThan(0);
+    expect(result.warningCount).toBe(result.guidelines.filter((g: ConstraintResult) => !g.satisfied).length);
+  });
+
+  it('干净上下文对照：passed=true、ironLaws 全满意', async () => {
+    const result = await checker.collectConstraints(CLEAN);
+    expect(result.passed).toBe(true);
+    expect(result.ironLaws.every((r: ConstraintResult) => r.satisfied)).toBe(true);
+  });
+});

package/src/core/constraints/checker.ts

@@ -22,7 +22,7 @@ import { matchesTrigger } from '../../utils/exec';
 import { join, relative } from 'path';
 import { CheckCache } from './check-cache';
 import { findTsSourceFiles } from '../../utils/file-walk';
-import { getConstraintCheck, buildCheckEnv, type CheckOutcome } from './checkers';
+import { getConstraintCheck, buildCheckEnv, normalizeCheckOutcome, type CheckOutcome } from './checkers';
 import { createGitEvidence, type GitEvidence } from './git-evidence';
 
 /**
@@ -112,9 +112,11 @@ export class ConstraintChecker {
     }
 
     // 检查前置条件（'skip' = 约定未采用/证据未接线：satisfied 置 true 但不计 pass/fail）
-    const outcome = await this.checkPrecondition(constraint, context, evidence);
+    const outcome = normalizeCheckOutcome(
+      await this.checkPrecondition(constraint, context, evidence)
+    );
 
-    if (outcome === 'skip') {
+    if (outcome.skipped) {
       return {
         id: constraint.id,
         level: constraint.level,
@@ -126,7 +128,7 @@ export class ConstraintChecker {
       };
     }
 
-    const satisfied = outcome;
+    const satisfied = outcome.satisfied;
 
     return {
       id: constraint.id,
@@ -134,6 +136,7 @@ export class ConstraintChecker {
       satisfied,
       constraint,
       message: satisfied ? undefined : constraint.message,
+      evidence: outcome.evidence.length > 0 ? outcome.evidence : undefined,
       requiredAction: satisfied ? undefined : constraint.enforcement,
       checkedAt: new Date(),
     };
@@ -172,6 +175,7 @@ export class ConstraintChecker {
       severity: this.getSeverity(constraint.level),
       projectPath: context.projectPath,
       sessionId: context.sessionId,
+      evidence: checkResult.evidence,
     });
   }
 
@@ -259,6 +263,35 @@ export class ConstraintChecker {
     context: ConstraintContext,
     customConfig?: MergedConstraintsConfig | null,
     evidence?: GitEvidence
+  ): Promise<ConstraintCheckResult> {
+    return this.runAllConstraints(context, customConfig, evidence, 'block');
+  }
+
+  /**
+   * 收集模式执行约束检查（harness report 的不抛出口，架构评审候选1）
+   *
+   * 与 checkConstraints 共享同一检查体，唯一差别是不 throw：
+   * 铁律违规照进 result.ironLaws、passed=false，后续铁律与 guidelines 照常执行，
+   * trace 逐条照记。报告类消费者拿全量视图；阻断语义只属于 checkConstraints
+   * （throw 契约是 #119 判定证据的外溢面，逐字不动）。
+   */
+  async collectConstraints(
+    context: ConstraintContext,
+    customConfig?: MergedConstraintsConfig | null,
+    evidence?: GitEvidence
+  ): Promise<ConstraintCheckResult> {
+    return this.runAllConstraints(context, customConfig, evidence, 'collect');
+  }
+
+  /**
+   * checkConstraints / collectConstraints 的共享检查体；
+   * mode='block' 首个铁律违规即抛，mode='collect' 全量跑完不抛
+   */
+  private async runAllConstraints(
+    context: ConstraintContext,
+    customConfig: MergedConstraintsConfig | null | undefined,
+    evidence: GitEvidence | undefined,
+    mode: 'block' | 'collect'
   ): Promise<ConstraintCheckResult> {
     // run 起始：重置 src 扫描缓存（S7）；git 证据 = 本 run 独占的 adapter 实例（工单 18 → #87）
     this.cache.invalidate();
@@ -275,7 +308,7 @@ export class ConstraintChecker {
     // context.operation 为主触发条件，extraTriggers 为次级推断（ADR-0001），任一命中即匹配
     const operations = [context.operation, ...(context.extraTriggers ?? [])];
 
-    // 1. Iron Laws: 必须全部通过
+    // 1. Iron Laws: block 模式首个违规即抛；collect 模式全量收集
     for (const constraint of Object.values(constraints.ironLaws)) {
       if (!matchesTrigger(constraint, operations)) continue;
 
@@ -285,7 +318,9 @@ export class ConstraintChecker {
 
       if (!checkResult.satisfied) {
         result.passed = false;
-        throw new ConstraintViolationError(checkResult);
+        if (mode === 'block') {
+          throw new ConstraintViolationError(checkResult);
+        }
       }
     }
 

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

@@ -9,7 +9,7 @@
 
 import { describe, it, expect, jest } from '@jest/globals';
 import { capabilitySync } from '../capability-sync';
-import { buildCheckEnv, type CheckEnv } from '../types';
+import { buildCheckEnv, normalizeCheckOutcome, type CheckEnv, type CheckOutcome } from '../types';
 import { collectSourceFiles } from '../../capabilities-reconcile';
 import { createProjectFixture } from '../../../../test-setup/project-fixture';
 import type { ConstraintContext } from '../../../../types/constraint';
@@ -47,6 +47,12 @@ function makeEnv(
   });
 }
 
+/** 判定归一：boolean 与 CheckDetail 两种返回形状统一断言（harness#119） */
+const passed = (outcome: CheckOutcome): boolean => normalizeCheckOutcome(outcome).satisfied;
+/** 证据行拼成单串，便于按路径断言 */
+const evidenceText = (outcome: CheckOutcome): string =>
+  normalizeCheckOutcome(outcome).evidence.join('\n');
+
 describe('capability_sync — skip 与文档格式门槛', () => {
   it('无 CAPABILITIES.md → skip（ADR-0001 存在性探测，有无变更都一样）', async () => {
     const dir = createProjectFixture({ name: 'cap-sync-none' });
@@ -56,84 +62,104 @@ describe('capability_sync — skip 与文档格式门槛', () => {
 
   it('散文文档（无表格）+ 有变更 → 放行（历史语义）', async () => {
     const dir = setupDir('prose', '# Capabilities\n\n- Feature: test', ['feature.ts']);
-    expect(await capabilitySync.evaluate(makeEnv(dir, ['feature.ts']))).toBe(true);
+    expect(passed(await capabilitySync.evaluate(makeEnv(dir, ['feature.ts'])))).toBe(true);
   });
 
   it('清单格式（计数行）→ 放行，计数由 sync-docs 维护', async () => {
     const dir = setupDir('listing', '# Capabilities\n\n## CLI Commands (25)\ncheck, validate\n');
-    expect(await capabilitySync.evaluate(makeEnv(dir, ['src/foo.ts']))).toBe(true);
+    expect(passed(await capabilitySync.evaluate(makeEnv(dir, ['src/foo.ts'])))).toBe(true);
   });
 
-  it('有表格但零条目 + 有变更 → 不得放行', async () => {
+  it('有表格但零条目 + 有变更 → 不得放行（step1 拦下，证据点名变更文件）', async () => {
     const dir = setupDir('empty-table', `# Capabilities\n\n${TABLE_HEAD}`);
-    expect(await capabilitySync.evaluate(makeEnv(dir, ['src/foo.ts']))).toBe(false);
+    const outcome = await capabilitySync.evaluate(makeEnv(dir, ['src/foo.ts']));
+    expect(passed(outcome)).toBe(false);
+    expect(evidenceText(outcome)).toContain('src/foo.ts');
   });
 
-  it('有表格但零条目 + 源码有文件 → step2 不得放行', async () => {
+  it('有表格但零条目 + 源码有文件 → 文档退化门拦下（不靠 step2 兜，harness#119）', async () => {
     const dir = setupDir('empty-table-scan', `# Capabilities\n\n${TABLE_HEAD}`, ['src/foo.ts']);
-    expect(await capabilitySync.evaluate(makeEnv(dir, []))).toBe(false);
+    const outcome = await capabilitySync.evaluate(makeEnv(dir, []));
+    expect(passed(outcome)).toBe(false);
+    expect(evidenceText(outcome)).toContain('零条目');
+  });
+
+  it('有表格但零条目 + 源码无文件 → 放行（门限定「确有可登记对象」，不扩大 fail 面）', async () => {
+    const dir = setupDir('empty-table-nosrc', `# Capabilities\n\n${TABLE_HEAD}`);
+    expect(passed(await capabilitySync.evaluate(makeEnv(dir, [])))).toBe(true);
   });
 });
 
-describe('capability_sync — step1 增量覆盖', () => {
+describe('capability_sync — step1 增量覆盖（唯一判违规处，harness#119）', () => {
   const run = (dir: string, staged: string[]) =>
     capabilitySync.evaluate(makeEnv(dir, staged, {}));
 
-  it('变更文件未被登记 → 失败', async () => {
+  it('变更文件未被登记 → 失败，且证据点名该文件', async () => {
     const dir = setupDir('step1-uncovered', `# C\n\n${TABLE_HEAD}| 旧 | old/module.ts | 旧 |\n`);
-    expect(await run(dir, ['new-module.ts'])).toBe(false);
+    const outcome = await run(dir, ['new-module.ts']);
+    expect(passed(outcome)).toBe(false);
+    expect(evidenceText(outcome)).toContain('new-module.ts');
   });
 
   it('变更文件按登记路径覆盖 → 通过', async () => {
     const dir = setupDir('step1-covered', `# C\n\n${TABLE_HEAD}| foo | src/foo.ts | foo |\n`);
-    expect(await run(dir, ['src/foo.ts'])).toBe(true);
+    expect(passed(await run(dir, ['src/foo.ts']))).toBe(true);
   });
 
   it('每个变更文件都必须被覆盖（every 而非 some）', async () => {
     const dir = setupDir('step1-every', `# C\n\n${TABLE_HEAD}| foo | src/foo.ts | foo |\n`);
-    expect(await run(dir, ['src/foo.ts', 'scripts/bar.ts'])).toBe(false);
+    const outcome = await run(dir, ['src/foo.ts', 'scripts/bar.ts']);
+    expect(passed(outcome)).toBe(false);
+    expect(evidenceText(outcome)).toContain('scripts/bar.ts');
   });
 
   it('后缀碰撞不覆盖：xfoo.ts 不被 foo.ts 条目覆盖', async () => {
     const dir = setupDir('step1-endswith', `# C\n\n${TABLE_HEAD}| foo | foo.ts | foo |\n`);
-    expect(await run(dir, ['web/xfoo.ts'])).toBe(false);
+    expect(passed(await run(dir, ['web/xfoo.ts']))).toBe(false);
   });
 
   it('子串误配不覆盖：docs/src/foo.tsx 不被 src/foo.ts 条目覆盖', async () => {
     const dir = setupDir('step1-includes', `# C\n\n${TABLE_HEAD}| foo | src/foo.ts | foo |\n`);
-    expect(await run(dir, ['docs/src/foo.tsx'])).toBe(false);
+    expect(passed(await run(dir, ['docs/src/foo.tsx']))).toBe(false);
   });
 
   it('basename 条目按路径边界后缀覆盖（src/foo.ts 被 foo.ts 覆盖）', async () => {
     const dir = setupDir('step1-suffix-ok', `# C\n\n${TABLE_HEAD}| foo | foo.ts | foo |\n`);
-    expect(await run(dir, ['src/foo.ts'])).toBe(true);
+    expect(passed(await run(dir, ['src/foo.ts']))).toBe(true);
   });
 
   it('测试文件与非代码变更不参与 step1', async () => {
     const dir = setupDir('step1-noncode', `# C\n\n${TABLE_HEAD}| foo | src/foo.ts | foo |\n`);
     expect(
-      await run(dir, ['src/__tests__/foo.test.ts', 'docs/readme.md', 'package.json'])
+      passed(await run(dir, ['src/__tests__/foo.test.ts', 'docs/readme.md', 'package.json']))
     ).toBe(true);
   });
 });
 
-describe('capability_sync — step2 全量覆盖（file 模式）', () => {
-  it('全部源文件已登记 → 通过', async () => {
+describe('capability_sync — step2 全量覆盖（file 模式：只提示，不判违规）', () => {
+  it('全部源文件已登记 → 通过且无提示', async () => {
     const dir = setupDir(
       'step2-ok',
       `# C\n\n${TABLE_HEAD}| foo | src/foo.ts | foo |\n`,
       ['src/foo.ts']
     );
-    expect(await capabilitySync.evaluate(makeEnv(dir, []))).toBe(true);
+    const outcome = await capabilitySync.evaluate(makeEnv(dir, []));
+    expect(passed(outcome)).toBe(true);
+    expect(evidenceText(outcome)).toBe('');
   });
 
-  it('有未登记源文件 → 失败', async () => {
+  it('有未登记源文件 → 仍通过，但提示点名该文件（harness#119 归位）', async () => {
     const dir = setupDir(
       'step2-missing',
       `# C\n\n${TABLE_HEAD}| foo | src/foo.ts | foo |\n`,
       ['src/foo.ts', 'src/unlisted.ts']
     );
-    expect(await capabilitySync.evaluate(makeEnv(dir, []))).toBe(false);
+    const outcome = await capabilitySync.evaluate(makeEnv(dir, []));
+    expect(passed(outcome)).toBe(true);
+    const evidence = evidenceText(outcome);
+    expect(evidence).toContain('src/unlisted.ts');
+    expect(evidence).toContain('仓库级漂移');
+    expect(evidence).toContain('sync-docs');
   });
 
   it('basename 条目同样按边界后缀覆盖 step2（step1/step2 语义一致）', async () => {
@@ -142,16 +168,40 @@ describe('capability_sync — step2 全量覆盖（file 模式）', () => {
       `# C\n\n${TABLE_HEAD}| foo | foo.ts | foo |\n`,
       ['src/foo.ts']
     );
-    expect(await capabilitySync.evaluate(makeEnv(dir, []))).toBe(true);
+    expect(passed(await capabilitySync.evaluate(makeEnv(dir, [])))).toBe(true);
   });
 
-  it('不同路径同后缀文件不被误覆盖（lib/foo.ts 不覆盖 src/foo.ts）', async () => {
+  it('不同路径同后缀文件不被误覆盖（lib/foo.ts 不覆盖 src/foo.ts）→ 记为漂移', async () => {
     const dir = setupDir(
       'step2-boundary',
       `# C\n\n${TABLE_HEAD}| foo | lib/foo.ts | foo |\n`,
       ['src/foo.ts']
     );
-    expect(await capabilitySync.evaluate(makeEnv(dir, []))).toBe(false);
+    const outcome = await capabilitySync.evaluate(makeEnv(dir, []));
+    expect(passed(outcome)).toBe(true);
+    expect(evidenceText(outcome)).toContain('src/foo.ts');
+  });
+
+  it('step1 优先：变更未登记时判违规，证据是变更文件而非仓库漂移清单', async () => {
+    const dir = setupDir(
+      'step1-beats-step2',
+      `# C\n\n${TABLE_HEAD}| foo | src/foo.ts | foo |\n`,
+      ['src/foo.ts', 'src/drifted.ts']
+    );
+    const outcome = await capabilitySync.evaluate(makeEnv(dir, ['src/new.ts']));
+    expect(passed(outcome)).toBe(false);
+    expect(evidenceText(outcome)).toContain('src/new.ts');
+    expect(evidenceText(outcome)).not.toContain('src/drifted.ts');
+  });
+
+  it('漂移项超过 10 个 → 证据截断并给出全量查看入口', async () => {
+    const files = ['src/foo.ts', ...Array.from({ length: 12 }, (_, i) => `src/drift${i}.ts`)];
+    const dir = setupDir('step2-truncate', `# C\n\n${TABLE_HEAD}| foo | src/foo.ts | foo |\n`, files);
+    const outcome = await capabilitySync.evaluate(makeEnv(dir, []));
+    expect(passed(outcome)).toBe(true);
+    const lines = normalizeCheckOutcome(outcome).evidence;
+    expect(lines).toHaveLength(12); // 说明行 + 10 条 + 截断行
+    expect(lines[lines.length - 1]).toContain('另 2 项');
   });
 });
 
@@ -163,7 +213,7 @@ describe('capability_sync — module 模式（未覆盖聚合为目录形状）'
       ['src/core/foo.ts', 'src/core/bar.ts'],
       'module'
     );
-    expect(await capabilitySync.evaluate(makeEnv(dir, []))).toBe(true);
+    expect(passed(await capabilitySync.evaluate(makeEnv(dir, [])))).toBe(true);
   });
 
   it('文件条目精确匹配也算覆盖', async () => {
@@ -173,17 +223,22 @@ describe('capability_sync — module 模式（未覆盖聚合为目录形状）'
       ['src/core/foo.ts'],
       'module'
     );
-    expect(await capabilitySync.evaluate(makeEnv(dir, []))).toBe(true);
+    expect(passed(await capabilitySync.evaluate(makeEnv(dir, [])))).toBe(true);
   });
 
-  it('新目录未登记 → 失败', async () => {
+  it('新目录未登记 → 不判违规，提示按目录聚合', async () => {
     const dir = setupDir(
       'mod-uncovered',
       `# C\n\n${TABLE_HEAD}| 核心 | src/core/ | 核心 |\n`,
       ['src/core/foo.ts', 'src/newdir/bar.ts'],
       'module'
     );
-    expect(await capabilitySync.evaluate(makeEnv(dir, []))).toBe(false);
+    const outcome = await capabilitySync.evaluate(makeEnv(dir, []));
+    expect(passed(outcome)).toBe(true);
+    const evidence = evidenceText(outcome);
+    expect(evidence).toContain('未登记模块目录');
+    expect(evidence).toContain('src/newdir/');
+    expect(evidence).not.toContain('src/newdir/bar.ts');
   });
 
   it('module 模式文件条目按边界后缀覆盖（step1/step2 同规则）', async () => {
@@ -193,12 +248,12 @@ describe('capability_sync — module 模式（未覆盖聚合为目录形状）'
       ['src/foo.ts'],
       'module'
     );
-    expect(await capabilitySync.evaluate(makeEnv(dir, []))).toBe(true);
+    expect(passed(await capabilitySync.evaluate(makeEnv(dir, [])))).toBe(true);
   });
 });
 
 describe('capability_sync — fail-open 可观测', () => {
-  it('证据读取异常时放行但输出 warn', async () => {
+  it('证据读取异常时放行但输出 warn，且异常原因进 evidence', async () => {
     const dir = setupDir('failopen', `# C\n\n${TABLE_HEAD}| foo | src/foo.ts | foo |\n`);
     const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
     const env: CheckEnv = {
@@ -207,7 +262,11 @@ describe('capability_sync — fail-open 可观测', () => {
         throw new Error('git boom');
       },
     };
-    expect(await capabilitySync.evaluate(env)).toBe(true);
+    const outcome = await capabilitySync.evaluate(env);
+    // fail-open 语义不变（仍不拦），但「因异常而通过」必须留痕：warn 只进本地 stderr
+    expect(passed(outcome)).toBe(true);
+    expect(evidenceText(outcome)).toContain('git boom');
+    expect(evidenceText(outcome)).toContain('fail-open');
     expect(warnSpy).toHaveBeenCalled();
     warnSpy.mockRestore();
   });

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('禁止简化测试绕过困难');
+  });
+});