@dommaker/harness 1.3.0 → 1.5.0

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

@@ -1,16 +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 中 → **只出提示**
  *
- * 覆盖判定两步统一（isCoveredBy）：目录条目（以 / 结尾）前缀匹配，
- * 文件条目精确匹配或路径边界后缀匹配。module 模式下目录条目参与覆盖，
- * 未覆盖文件按源码根下第一级子目录聚合。
+ * 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，避免在未采用约定的项目上全量误报。
@@ -18,32 +30,11 @@
 
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
-import {
-  aggregateToSourceSubdir,
-  isCapabilityListingFormat,
-  parseCapabilitiesEntries,
-} from '../capabilities-parser';
+import { isCapabilityListingFormat } from '../capabilities-parser';
 import { getCapabilitiesMode } from '../../project-config-loader';
 import { detectSourceRoots } from '../../../utils/detect-source-roots';
-import type { ConstraintCheck } from './types';
-
-/** markdown 表格分隔行（|------|------|）：区分「无表格的散文文档」与「有表格但零条目」 */
-const TABLE_SEPARATOR_REGEX = /^\s*\|[\s:|-]+\|\s*$/m;
-
-/**
- * 变更文件是否被条目覆盖
- *
- * 目录条目（以 / 结尾）前缀匹配；文件条目精确匹配或路径边界后缀匹配
- * （兼容 basename 条目，但拒绝 xfoo.ts 命中 foo.ts、docs/src/foo.tsx 命中 src/foo.ts
- * 这类 endsWith/includes 模糊匹配造成的碰撞）
- */
-function isCoveredBy(entries: string[], changed: string): boolean {
-  return entries.some((listed) =>
-    listed.endsWith('/')
-      ? changed.startsWith(listed)
-      : changed === listed || changed.endsWith('/' + listed)
-  );
-}
+import { reconcileCapabilities, significantCodeChanges } from '../capabilities-reconcile';
+import { formatEvidence, type ConstraintCheck } from './types';
 
 export const capabilitySync: ConstraintCheck = {
   id: 'capability_sync',
@@ -55,15 +46,6 @@ export const capabilitySync: ConstraintCheck = {
     }
     try {
       const capabilitiesPath = join(projectPath, 'CAPABILITIES.md');
-      if (!existsSync(capabilitiesPath)) {
-        // 检查是否有代码变更，无变更则跳过
-        const diff = await env.stagedDiffNames();
-        const changedCodeFiles = diff.split('\n').filter(
-          (f: string) => f.endsWith('.ts') || f.endsWith('.tsx') || f.endsWith('.js')
-        );
-        return changedCodeFiles.length === 0;
-      }
-
       const content = readFileSync(capabilitiesPath, 'utf-8');
       const capabilitiesMode = getCapabilitiesMode(projectPath);
 
@@ -72,71 +54,68 @@ export const capabilitySync: ConstraintCheck = {
         return true;
       }
 
-      const listedFiles = parseCapabilitiesEntries(content, { secondColumnOnly: true });
-      // module 模式下目录条目同样构成覆盖依据，与 step 2 判定对齐
-      const entries =
-        capabilitiesMode === 'module'
-          ? parseCapabilitiesEntries(content, { includeDirs: true })
-          : listedFiles;
-      // 有表格但零条目 = 文档什么都没登记，不得直接放行；无表格的散文文档保持历史放行
-      const hasTable = TABLE_SEPARATOR_REGEX.test(content);
+      const sourceRoots = detectSourceRoots(projectPath);
+      const population: string[] = [];
+      for (const root of sourceRoots) {
+        if (existsSync(join(projectPath, root))) {
+          population.push(...env.srcScan(root));
+        }
+      }
 
-      // ── Step 1: Git diff 增量检查 ──
-      const diff = await env.stagedDiffNames();
-      const changedCodeFiles = diff.split('\n').filter(
-        (f: string) => f.endsWith('.ts') || f.endsWith('.tsx') || f.endsWith('.js')
-      );
-      const significantChanges = changedCodeFiles.filter(
-        (f: string) => !f.includes('__tests__') && !f.includes('.test.') && !f.includes('.spec.')
-      );
+      const diffNames = (await env.stagedDiffNames()).split('\n').filter(Boolean);
+      const verdict = reconcileCapabilities({
+        content,
+        populationFiles: population,
+        changedFiles: significantCodeChanges(diffNames),
+        sourceRoots,
+      });
 
-      // 每个变更文件都必须被覆盖（every；some 会让一个命中掩盖其余漏网）
-      if (
-        significantChanges.length > 0 &&
-        (entries.length > 0 || hasTable) &&
-        !significantChanges.every((changed: string) => isCoveredBy(entries, changed))
-      ) {
-        return false;
+      // 无表格的散文文档：历史放行语义
+      if (!verdict.hasTable) return true;
+
+      // 文档退化门：有表格却什么都没登记（限定「源码根下确有文件」——空仓 + 空表没有可登记
+      // 对象，历史行为是放行，本票不顺手扩大 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') {
-        // module 模式：目录条目参与覆盖（isCoveredBy 统一判定）；
-        // 未覆盖文件按源码根下第一级子目录聚合，任一组非空即失败
-        if (entries.length > 0 || hasTable) {
-          const uncoveredDirs = new Set<string>();
-          const sourceRoots = detectSourceRoots(projectPath);
-          for (const root of sourceRoots) {
-            const srcDir = join(projectPath, root);
-            if (existsSync(srcDir)) {
-              for (const file of env.srcScan(root)) {
-                if (!isCoveredBy(entries, file)) {
-                  uncoveredDirs.add(aggregateToSourceSubdir(root, file));
-                }
-              }
-            }
-          }
-          if (uncoveredDirs.size > 0) return false;
-        }
-      } else if (listedFiles.length > 0 || hasTable) {
-        const sourceRoots = detectSourceRoots(projectPath);
-        for (const root of sourceRoots) {
-          const srcDir = join(projectPath, root);
-          if (existsSync(srcDir)) {
-            for (const file of env.srcScan(root)) {
-              if (!isCoveredBy(listedFiles, file)) {
-                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/context-doc-sync.ts

@@ -1,43 +1,33 @@
 /**
  * context_doc_sync：关键目录必须有 CONTEXT.md（工单 21）
  *
- * ADR-0001 存在性探测：项目未配置 governance.context_files 约定
- * （未启用或无 required_dirs）时返回 'skip'，不计 pass/fail。
+ * ADR-0001 存在性探测 + context_files 三态统一口径（工单 84）：
+ * 未配置 / enabled 但无目标（required_dirs 缺失或空）→ 一律 'skip'，
+ * 不计 pass/fail，与 docs_freshness 同构；判定只走 resolveContextFiles
+ * 访问器，不做 governance 手写钻取。
  */
 
 import { existsSync } from 'fs';
 import { join } from 'path';
-import { loadRawProjectConfig } from '../../project-config-loader';
+import { resolveContextFiles } from '../../project-config-loader';
 import type { ConstraintCheck } from './types';
 
 export const contextDocSync: ConstraintCheck = {
   id: 'context_doc_sync',
   async evaluate(env) {
     const projectPath = env.projectPath;
-    try {
-      const config = loadRawProjectConfig(projectPath) ?? {};
-      const governance = config.governance as Record<string, unknown> | undefined;
-      const contextFiles = governance?.context_files as Record<string, unknown> | undefined;
-
-      if (!contextFiles?.enabled || !Array.isArray(contextFiles.required_dirs)) {
-        return 'skip'; // 未配置 context_files 约定，跳过评估
-      }
-
-      const requiredDirs = contextFiles.required_dirs as string[];
-      if (requiredDirs.length === 0) {
-        return 'skip'; // 无目标目录，约定未生效
-      }
+    const resolution = resolveContextFiles(projectPath);
+    if (resolution.state !== 'enabled') {
+      return 'skip'; // 未配置或约定已立但无目标，跳过评估
+    }
 
-      for (const dir of requiredDirs) {
-        const contextPath = join(projectPath, dir, 'CONTEXT.md');
-        if (!existsSync(contextPath)) {
-          return false;
-        }
+    for (const dir of resolution.dirs) {
+      const contextPath = join(projectPath, dir, 'CONTEXT.md');
+      if (!existsSync(contextPath)) {
+        return false;
       }
-
-      return true;
-    } catch {
-      return 'skip'; // 配置不存在或解析失败 = 无法判定约定，跳过
     }
+
+    return true;
   },
 };

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

@@ -9,11 +9,13 @@
 
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
-import { loadRawProjectConfig } from '../../project-config-loader';
+import { getGovernanceConfig, resolveContextFiles } from '../../project-config-loader';
 import { FreshnessRunner, type FreshnessCheckResult } from '../doc-freshness/runner';
 import { detectSourceRoots } from '../../../utils/detect-source-roots';
-import type { DocFreshnessConfig, DocFreshnessCheck } from '../../../types/project-config';
-import type { ConstraintCheck } from './types';
+import { reconcileCapabilities } from '../capabilities-reconcile';
+import type { DocFreshnessCheck } from '../../../types/project-config';
+import type { ConstraintCheck, CheckEnv } from './types';
+import { formatEvidence } from './types';
 
 /**
  * 内置默认文档新鲜度检查配置
@@ -30,45 +32,31 @@ function getBuiltInDocFreshnessConfig(): DocFreshnessCheck[] {
 }
 
 /**
- * CAPABILITIES.md 文件表新鲜度：列出的文件路径必须仍存在。
- * 多根查找：支持不同项目的源码根（harness=src/, studio=apps/api/src/ 等）。
- * 无表格行（能力清单格式）时跳过。
+ * CAPABILITIES.md 文件表新鲜度：登记的条目（文件与目录）必须仍存在（ADR-0009 口径从严）。
+ * 判定逻辑统一走 capabilities-reconcile；多根查找支持不同项目的源码根
+ * （harness=src/, studio=apps/api/src/ 等）。无表格（能力清单格式）时自然零幽灵。
  */
-function checkCapabilitiesFreshness(projectPath: string): boolean {
+function findDeadCapabilityEntries(projectPath: string, env: CheckEnv): string[] {
   try {
     const capabilitiesPath = join(projectPath, 'CAPABILITIES.md');
-    if (!existsSync(capabilitiesPath)) return true;
+    if (!existsSync(capabilitiesPath)) return [];
     const content = readFileSync(capabilitiesPath, 'utf-8');
 
-    const listedFiles: string[] = [];
-    const tableRowRegex = /^\|[^|]+\|\s*([^|]+?\.(?:ts|tsx|js|jsx))\s*\|/gm;
-    let match;
-    while ((match = tableRowRegex.exec(content)) !== null) {
-      listedFiles.push(match[1].trim());
-    }
-
-    if (listedFiles.length === 0) return true;
-
     const sourceRoots = detectSourceRoots(projectPath);
-    const fileExists = (file: string): boolean => {
-      if (existsSync(join(projectPath, file))) return true;
-      for (const root of sourceRoots) {
-        if (existsSync(join(projectPath, root, file))) return true;
-      }
-      return false;
-    };
-
-    const missing = listedFiles.filter(f => !fileExists(f));
-    if (missing.length > 0) {
-      // 报出具体文件名：此前只返回 false，CLI 只能打印通用提示，
-      // 幽灵条目 basename 碰撞时 sync-docs 也不剔除，用户无从定位（2026-08-08 studio CI 4 连红）
-      console.error(`[docs_freshness] CAPABILITIES.md 列出的文件不存在: ${missing.join(', ')}`);
-      return false;
+    const population: string[] = [];
+    for (const root of sourceRoots) {
+      if (existsSync(join(projectPath, root))) population.push(...env.srcScan(root));
     }
 
-    return true;
+    const verdict = reconcileCapabilities({
+      content,
+      populationFiles: population,
+      sourceRoots,
+      fileExists: (rel) => existsSync(join(projectPath, rel)),
+    });
+    return verdict.deadEntries;
   } catch {
-    return true;
+    return [];
   }
 }
 
@@ -77,7 +65,7 @@ function checkCapabilitiesFreshness(projectPath: string): boolean {
  *
  * 判定信号（任一命中即视为采用了文档新鲜度约定）：
  * - 配置了 governance.doc_freshness.checks
- * - 配置了 governance.context_files（enabled + 非空 required_dirs）
+ * - 配置了 governance.context_files 且约定有效（enabled + 非空 required_dirs）
  * - 项目根存在 CAPABILITIES.md
  * - 项目根存在 CHANGELOG.md / CHANGELOG
  *
@@ -89,26 +77,12 @@ function hasFreshnessTargets(projectPath: string): boolean {
     return true;
   }
 
-  try {
-    const raw = loadRawProjectConfig(projectPath);
-    const governance = raw?.governance as Record<string, unknown> | undefined;
-
-    const freshnessConfig = governance?.doc_freshness as DocFreshnessConfig | undefined;
-    if (freshnessConfig?.checks && freshnessConfig.checks.length > 0) return true;
-
-    const contextFiles = governance?.context_files as Record<string, unknown> | undefined;
-    if (
-      contextFiles?.enabled &&
-      Array.isArray(contextFiles.required_dirs) &&
-      (contextFiles.required_dirs as string[]).length > 0
-    ) {
-      return true;
-    }
-  } catch {
-    // 配置不可读视为无配置
+  const governance = getGovernanceConfig(projectPath);
+  if (governance?.doc_freshness?.checks && governance.doc_freshness.checks.length > 0) {
+    return true;
   }
 
-  return false;
+  return resolveContextFiles(projectPath).state === 'enabled';
 }
 
 export const docsFreshness: ConstraintCheck = {
@@ -119,26 +93,27 @@ export const docsFreshness: ConstraintCheck = {
     // ADR-0001 存在性探测：项目无任何 freshness 配置/目标 → skip（不计 pass/fail）
     if (!hasFreshnessTargets(projectPath)) return 'skip';
 
-    // Step 1: 文件表格式 — 检查列出的文件是否还存在
-    if (!checkCapabilitiesFreshness(projectPath)) return false;
+    // Step 1: 文件表格式 — 登记的条目（文件+目录）是否仍存在（ADR-0009）
+    const deadEntries = findDeadCapabilityEntries(projectPath, env);
+    if (deadEntries.length > 0) {
+      // 证据通道点名条目（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
     try {
-      let freshnessConfig: DocFreshnessConfig | undefined;
-      let requiredDirs: string[] | undefined;
-
-      try {
-        const raw = loadRawProjectConfig(projectPath);
-        const governance = raw?.governance as Record<string, unknown> | undefined;
-        freshnessConfig = governance?.doc_freshness as DocFreshnessConfig | undefined;
-
-        const contextFiles = governance?.context_files as Record<string, unknown> | undefined;
-        if (contextFiles?.enabled && Array.isArray(contextFiles.required_dirs)) {
-          requiredDirs = contextFiles.required_dirs as string[];
-        }
-      } catch {
-        // 配置解析失败，使用默认
-      }
+      const freshnessConfig = getGovernanceConfig(projectPath)?.doc_freshness;
+
+      // context_files 三态统一口径（工单 84）：约定已立但无目标（enabled 但
+      // required_dirs 缺失/空）→ skip，与 context_doc_sync 同构；不再静默放行
+      const contextFiles = resolveContextFiles(projectPath);
+      if (contextFiles.state === 'enabled-empty') return 'skip';
+      const requiredDirs = contextFiles.state === 'enabled' ? contextFiles.dirs : undefined;
 
       const runner = new FreshnessRunner();
       let results: FreshnessCheckResult[];
@@ -149,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/governance-presence.ts

@@ -10,42 +10,24 @@
  * 不强制迁移；两处都没有才报违规。
  */
 
-import { readFileSync } from 'fs';
 import { join } from 'path';
 import { loadRawProjectConfig } from '../../project-config-loader';
+import { hasGovernanceContract, hasPreserveBlock, readIfExists } from '../injection-writer';
 import type { ConstraintCheck } from './types';
 
 /** 治理契约 PRESERVE 段名（ADR 落点模型约定） */
 export const GOVERNANCE_PRESERVE_NAME = 'governance';
 
-const GOVERNANCE_BEGIN_RE = /^<!-- PRESERVE:governance -->\s*$/m;
-
-/** AGENTS.md 是否存在非空 PRESERVE:governance 块（标记须独占一行，与 preserve-block.ts 同语义） */
+/** AGENTS.md 是否存在非空 PRESERVE:governance 块（切片判定收口 injection-writer.hasPreserveBlock，#83） */
 export function hasGovernancePreserveBlock(agentsMdPath: string): boolean {
-  let content: string;
-  try {
-    content = readFileSync(agentsMdPath, 'utf-8');
-  } catch {
-    return false;
-  }
-  const beginMatch = GOVERNANCE_BEGIN_RE.exec(content);
-  if (!beginMatch) return false;
-  const rest = content.slice(beginMatch.index + beginMatch[0].length);
-  const endIdx = rest.indexOf(`<!-- /PRESERVE:${GOVERNANCE_PRESERVE_NAME} -->`);
-  if (endIdx === -1) return false;
-  // 块体（首尾标记之间）去空白后非空才算「在场」
-  return rest.slice(0, endIdx).trim().length > 0;
+  const content = readIfExists(agentsMdPath);
+  return content !== null && hasPreserveBlock(content, GOVERNANCE_PRESERVE_NAME);
 }
 
-/** CLAUDE.md 是否存在治理块（与 agents-syncer getGovernanceInfo 同判定，旧模型仓豁免） */
+/** CLAUDE.md 是否有治理契约在场（判定收口 injection-writer.hasGovernanceContract，#83；旧模型仓豁免） */
 export function hasClaudeGovernance(claudeMdPath: string): boolean {
-  let content: string;
-  try {
-    content = readFileSync(claudeMdPath, 'utf-8');
-  } catch {
-    return false;
-  }
-  return /^##\s+Governance Rules/m.test(content) || content.includes('HARNESS_CONSTRAINTS_START');
+  const content = readIfExists(claudeMdPath);
+  return content !== null && hasGovernanceContract(content);
 }
 
 export const governancePresence: ConstraintCheck = {

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/no-test-simplification.ts

@@ -4,10 +4,11 @@
 
 import type { ConstraintCheck } from './types';
 
+// m 标志必需：真实 diff 首行恒为 `diff --git`，缺 m 则 ^ 永不命中删除行（铁律静默失效）
 const DELETED_TEST_PATTERNS = [
-  /^-\s*(test|it|describe)\s*\(/, // 删除 test/it/describe
-  /^-\s*expect\s*\(/,              // 删除 expect
-  /^-\s*\/\/\s*test/,              // 删除注释的 test
+  /^-\s*(test|it|describe)\s*\(/m, // 删除 test/it/describe
+  /^-\s*expect\s*\(/m,              // 删除 expect
+  /^-\s*\/\/\s*test/m,              // 删除注释的 test
 ];
 
 export const noTestSimplification: ConstraintCheck = {

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

@@ -29,8 +29,8 @@ export interface CheckEnv {
 /**
  * 证据提供者组：git diff / 源码扫描的 memoized I/O
  *
- * 由调用方绑定后传入 buildCheckEnv（如 ConstraintChecker 绑实例级
- * run 缓存的方法）；工厂本身不做 memoization。
+ * 由调用方绑定后传入 buildCheckEnv（#87：git 两项绑 GitEvidence adapter 实例，
+ * 一次 run 一份，命令级 memo 在 adapter 层）；工厂本身不做 memoization。
  */
 export interface EvidenceProviders {
   /** staged 全量 diff */
@@ -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;
 }