@dommaker/harness 1.4.0 → 1.5.0

package/src/cli/commands/check.ts

@@ -21,9 +21,35 @@ import { GOVERNANCE_HEADING } from '../../core/constraints/injection-writer';
 import { getTraceCollector } from '../../monitoring/traces';
 import { countJsonlLines } from '../../utils/jsonl';
 import { DEFAULT_TRACE_FILE } from '../../types/trace';
-import type { ConstraintTrigger } from '../../types/constraint';
+import type { ConstraintResult, ConstraintTrigger } from '../../types/constraint';
 import { log, processIO, type CommandIO, type CommandResult } from '../command-contract';
 
+/** 证据行着色（与调用处所属结论块一致） */
+const EVIDENCE_PAINT = {
+  red: chalk.red,
+  yellow: chalk.yellow,
+  gray: chalk.gray,
+} as const;
+
+/**
+ * 打印 checker 的判定证据行（harness#119）
+ *
+ * 文案由 checker 自行措辞（每行自描述），CLI 只负责缩进与着色——
+ * 不在这里解释内容，否则证据形状与措辞会两头漂移。
+ * 传 id 时首行挂上约束 id（提示块里没有父级结论行可依附）。
+ */
+function logEvidence(
+  io: CommandIO,
+  result: ConstraintResult,
+  color: keyof typeof EVIDENCE_PAINT,
+  id?: string
+): void {
+  const paint = EVIDENCE_PAINT[color];
+  (result.evidence ?? []).forEach((line, index) => {
+    log(io, paint(index === 0 && id ? `   - ${id}: ${line}` : `     ${line}`));
+  });
+}
+
 export interface CheckOptions {
   /** 预设名称 */
   preset: string;
@@ -110,6 +136,7 @@ export async function check(
         if (r.constraint) {
           log(io, chalk.red(`   - ${r.constraint.id}: ${r.constraint.message}`));
           log(io, chalk.red(`     ${r.constraint.rule}`));
+          logEvidence(io, r, 'red');
         }
       });
       log(io);
@@ -126,6 +153,7 @@ export async function check(
       result.guidelines.filter(r => !r.satisfied).forEach(r => {
         if (r.constraint) {
           log(io, chalk.yellow(`   - ${r.constraint.id}: ${r.constraint.message}`));
+          logEvidence(io, r, 'yellow');
         }
       });
     } else if (result.guidelines.length > 0) {
@@ -134,6 +162,16 @@ export async function check(
       log(io, chalk.green(`✅ 指导原则: ${passedGuidelines}/${evaluatedGuidelines.length} 通过`));
     }
 
+    // 提示：通过但带证据（harness#119）——与本次变更无因果的仓库级漂移在此露出，
+    // 不判违规、不改 exit code，只保证「看得见且能自己修」
+    const hints = [...result.ironLaws, ...result.guidelines].filter(
+      r => !r.skipped && r.satisfied && (r.evidence?.length ?? 0) > 0
+    );
+    if (hints.length > 0) {
+      log(io, chalk.gray(`💡 提示: ${hints.length} 条（不判违规，供参考）`));
+      hints.forEach(r => logEvidence(io, r, 'gray', r.id));
+    }
+
     // Skipped：约定未采用 / 证据未接线，未评估（不计通过/失败）
     if (skippedResults.length > 0) {
       log(io, chalk.gray(`⏭️  跳过评估: ${skippedResults.length} 条（约定未采用或证据未接线，不计通过/失败）`));

package/src/cli/commands/definitions.ts

@@ -235,11 +235,6 @@ export const COMMAND_DEFINITIONS: CommandDefinition[] = [
       { flags: '--sources <sources>', description: '导入源（逗号分隔: code,git,docs）' },
       { flags: '--limit <n>', description: '结果数量限制', defaultValue: '20' },
       { flags: '--reset', description: '重置导入状态', defaultValue: false },
-      { flags: '--scope <scope>', description: '知识范围（用于 upsert 去重）' },
-      { flags: '--title <title>', description: '知识标题（用于 upsert）' },
-      { flags: '--content <content>', description: '知识内容 Markdown（用于 upsert）' },
-      { flags: '--file <path>', description: '从文件读取内容（用于 upsert）' },
-      { flags: '--source <source>', description: '知识来源 (cli/design)', defaultValue: 'cli' },
       { flags: '--fix', description: '自动修复（用于 audit）', defaultValue: false },
       { flags: '--dry-run', description: '只输出报告不修改（用于 audit）', defaultValue: false },
       { flags: '--threshold <n>', description: '短内容阈值（字符数，用于 audit）', defaultValue: '50' },
@@ -258,8 +253,6 @@ export const COMMAND_DEFINITIONS: CommandDefinition[] = [
       decay: { impl: { module: 'knowledge', export: 'knowledgeDecay' }, aliases: ['d'] },
       stats: { impl: { module: 'knowledge', export: 'knowledgeStats' }, aliases: ['st'] },
       'sync-rag': { impl: { module: 'knowledge', export: 'knowledgeSyncRag' } },
-      'sync-status': { impl: { module: 'knowledge', export: 'knowledgeSyncStatus' }, aliases: ['sync'] },
-      upsert: { impl: { module: 'knowledge', export: 'knowledgeUpsert' }, aliases: ['up'] },
       audit: { impl: { module: 'knowledge', export: 'knowledgeAudit' }, aliases: ['a'] },
       snapshot: { impl: { module: 'knowledge', export: 'knowledgeSnapshot' } },
       migrate: { impl: { module: 'knowledge', export: 'knowledgeMigrate' } },

package/src/cli/commands/knowledge.ts

@@ -281,76 +281,6 @@ export async function knowledgeStats(options: KnowledgeOptions, io: CommandIO =
   return { kind: 'ok' };
 }
 
-export interface KnowledgeUpsertOptions {
-  scope?: string;
-  title?: string;
-  content?: string;
-  file?: string;
-  type?: string;
-  source?: string;
-}
-
-/**
- * 设计时知识沉淀：写入 KnowledgeStore + 同步 Prisma Document（Studio UI 可见）
- *
- * 调用 Studio API POST /api/knowledge/upsert（内部端点，无 auth）
- */
-export async function knowledgeUpsert(options: KnowledgeUpsertOptions, io: CommandIO = processIO): Promise<CommandResult> {
-  const apiPort = process.env.API_PORT || '3001';
-  const url = `http://localhost:${apiPort}/api/knowledge/upsert`;
-
-  // Read content from file if --file specified
-  let content = options.content || '';
-  if (options.file && !content) {
-    try {
-      content = fs.readFileSync(options.file, 'utf-8');
-    } catch (e: any) {
-      logError(io, chalk.red(`Failed to read file: ${options.file}`));
-      logError(io, chalk.red(String(e)));
-      return { kind: 'fail', reason: `无法读取 --file ${options.file}: ${String(e)}` };
-    }
-  }
-
-  if (!options.scope || !options.title || !content) {
-    logError(io, chalk.red('--scope, --title, and --content (or --file) are required'));
-    return { kind: 'usage-error', reason: '--scope/--title/--content(--file) 缺一不可' };
-  }
-
-  try {
-    const res = await fetch(url, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        scope: options.scope,
-        title: options.title,
-        content,
-        type: options.type || 'architecture',
-        source: options.source || 'cli',
-      }),
-    });
-
-    if (!res.ok) {
-      const err: any = await res.json().catch(() => ({ error: res.statusText }));
-      logError(io, chalk.red(`API error ${res.status}: ${err.error || res.statusText}`));
-      return { kind: 'fail', reason: `upsert API error ${res.status}: ${err.error || res.statusText}` };
-    }
-
-    const result: any = await res.json();
-    log(io, chalk.green(`✅ Knowledge upserted`));
-    log(io, `   KnowledgeStore: ${result.knowledgeStore?.action} → ${result.knowledgeStore?.entryId}`);
-    log(io, `   Studio UI: ${result.prismaDocument?.action} → ${result.prismaDocument?.docId || 'skipped'}`);
-    return { kind: 'ok' };
-  } catch (e: any) {
-    if (e?.code === 'ECONNREFUSED') {
-      logError(io, chalk.red(`Cannot reach Studio API at ${url}. Is the API running?`));
-    } else {
-      logError(io, chalk.red(`Upsert failed: ${e.message}`));
-    }
-    return { kind: 'fail', reason: `knowledge upsert 失败: ${e?.code === 'ECONNREFUSED' ? `Studio API 不可达 ${url}` : e.message}` };
-  }
-}
-
-/**
 /**
  * RAG 同步：扫描 .harness/knowledge-docs/ 输出需要 ingest 的文件列表
  */
@@ -383,55 +313,6 @@ export async function knowledgeSyncRag(options: KnowledgeOptions, io: CommandIO
   return { kind: 'ok' };
 }
 
-/**
- * 知识同步状态：检测所有 tracked scope 的新鲜度
- */
-export async function knowledgeSyncStatus(options: KnowledgeOptions, io: CommandIO = processIO): Promise<CommandResult> {
-  const apiPort = process.env.API_PORT || '3001';
-  const url = `http://localhost:${apiPort}/api/knowledge/sync-status`;
-
-  try {
-    const res = await fetch(url);
-    if (!res.ok) {
-      const err: any = await res.json().catch(() => ({ error: res.statusText }));
-      logError(io, chalk.red(`API error ${res.status}: ${err.error || res.statusText}`));
-      return { kind: 'fail', reason: `sync-status API error ${res.status}: ${err.error || res.statusText}` };
-    }
-
-    const data: any = await res.json();
-
-    if (options.json) {
-      log(io, JSON.stringify(data, null, 2));
-      return { kind: 'ok' };
-    }
-
-    log(io, chalk.blue(`🔄 KnowledgeSync Status\n`));
-    log(io, chalk.bold(`Tracked scopes: ${data.trackedScopes?.join(', ') || 'none'}`));
-    log(io, chalk.bold(`Stale entries: ${data.stale?.length || 0}`));
-
-    if (data.stale?.length > 0) {
-      log(io, chalk.yellow(`\n⚠️  Stale knowledge:\n`));
-      for (const s of data.stale) {
-        log(io, chalk.yellow(`  ${s.scope} (${s.title}): ${s.stalenessHours}h old, files changed: ${s.changedFiles.join(', ')}`));
-      }
-    } else {
-      log(io, chalk.green('\n✅ All knowledge fresh'));
-    }
-
-    if (data.healed?.length > 0) {
-      log(io, chalk.cyan(`\n🩹 Auto-healed: ${data.healed.join(', ')}`));
-    }
-  } catch (e: any) {
-    if (e?.code === 'ECONNREFUSED') {
-      logError(io, chalk.red(`Cannot reach Studio API at ${url}`));
-    } else {
-      logError(io, chalk.red(`Sync check failed: ${e.message}`));
-    }
-    return { kind: 'fail', reason: `knowledge sync status 检查失败: ${e?.code === 'ECONNREFUSED' ? `Studio API 不可达 ${url}` : e.message}` };
-  }
-  return { kind: 'ok' };
-}
-
 /**
  * 飞轮健康检查 — 零 token 检测知识飞轮数据流状态
  */

package/src/cli/commands/update-user-model.ts

@@ -10,8 +10,8 @@
  *   studio/.harness/knowledge/                 (知识新鲜度)
  *   ~/.claude/projects/-root-projects/memory/  (规则库)
  *
- * 模型状态: ~/.claude/user-model-state.json
- * 画像输出: ~/.claude/projects/-root-projects/memory/user_profile.md
+ * 模型状态: $HARNESS_UUM_STATE_FILE，默认 ~/.claude/user-model-state.json
+ * 画像输出: $HARNESS_UUM_PROFILE_FILE，默认 ~/.claude/projects/-root-projects/memory/user_profile.md
  *
  * 工单 19-C：transcript 解析/纠正模式/相似度收敛至 cli/session-mining/。
  */
@@ -50,15 +50,30 @@ interface ModelState {
   evolutionLog: Array<{ date: string; change: string }>;
 }
 
-const STATE_FILE = path.join(os.homedir(), '.claude', 'user-model-state.json');
-const PROFILE_FILE = path.join(os.homedir(), '.claude', 'projects', '-root-projects', 'memory', 'user_profile.md');
+// 路径集中解析（harness#116）：默认值保持原行为，env 可覆盖（多工作区/测试隔离）。
+// 运行时解析而非模块加载期常量，保证 env 设置后生效。
+export interface UserModelPaths {
+  stateFile: string;
+  profileFile: string;
+}
+
+export function resolveUserModelPaths(env: NodeJS.ProcessEnv = process.env): UserModelPaths {
+  const home = os.homedir();
+  return {
+    stateFile: env.HARNESS_UUM_STATE_FILE
+      || path.join(home, '.claude', 'user-model-state.json'),
+    profileFile: env.HARNESS_UUM_PROFILE_FILE
+      || path.join(home, '.claude', 'projects', '-root-projects', 'memory', 'user_profile.md'),
+  };
+}
 
 export async function updateUserModel(options: UpdateUserModelOptions, io: CommandIO = processIO): Promise<CommandResult> {
   const transcriptDir = process.env.CLAUDE_TRANSCRIPTS_DIR
     || path.join(os.homedir(), '.claude', 'projects', '-root--claude');
 
   // 1. Load previous state
-  const state = loadState();
+  const paths = resolveUserModelPaths();
+  const state = loadState(paths);
 
   // 2. Scan new data
   const newSessions = findNewSessions(transcriptDir, state.sessionsProcessed, options.days);
@@ -90,8 +105,8 @@ export async function updateUserModel(options: UpdateUserModelOptions, io: Comma
       state.sessionsProcessed = state.sessionsProcessed.slice(-200);
     }
 
-    saveState(state);
-    updateProfile(state);
+    saveState(state, paths);
+    updateProfile(state, paths);
   }
 
   // 6. Output
@@ -107,10 +122,10 @@ export async function updateUserModel(options: UpdateUserModelOptions, io: Comma
 
 // ── State I/O ──
 
-function loadState(): ModelState {
+function loadState(paths: UserModelPaths): ModelState {
   try {
-    if (fs.existsSync(STATE_FILE)) {
-      return JSON.parse(fs.readFileSync(STATE_FILE, 'utf-8'));
+    if (fs.existsSync(paths.stateFile)) {
+      return JSON.parse(fs.readFileSync(paths.stateFile, 'utf-8'));
     }
   } catch {}
   return {
@@ -123,11 +138,11 @@ function loadState(): ModelState {
   };
 }
 
-function saveState(state: ModelState): void {
+function saveState(state: ModelState, paths: UserModelPaths): void {
   try {
-    const dir = path.dirname(STATE_FILE);
+    const dir = path.dirname(paths.stateFile);
     if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(STATE_FILE, JSON.stringify(state, null, 2), 'utf-8');
+    fs.writeFileSync(paths.stateFile, JSON.stringify(state, null, 2), 'utf-8');
   } catch {}
 }
 
@@ -373,9 +388,9 @@ function applySignals(state: ModelState, signals: SessionSignals[], mergedConcep
 
 // ── Profile update ──
 
-function updateProfile(state: ModelState): void {
+function updateProfile(state: ModelState, paths: UserModelPaths): void {
   try {
-    let content = fs.readFileSync(PROFILE_FILE, 'utf-8');
+    let content = fs.readFileSync(paths.profileFile, 'utf-8');
 
     // Replace Derived Rules section
     const derivedStart = '## Derived Rules';
@@ -410,7 +425,7 @@ function updateProfile(state: ModelState): void {
       }
     }
 
-    fs.writeFileSync(PROFILE_FILE, content, 'utf-8');
+    fs.writeFileSync(paths.profileFile, content, 'utf-8');
   } catch (e) {
     // Profile file might not exist yet — skip
   }

package/src/core/CONTEXT.md

@@ -4,7 +4,7 @@
 约束引擎核心：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）
+- `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，异常文案是其证据唯一外溢面）
 - `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/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` 配置诊断
@@ -31,3 +31,4 @@
 - 零 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/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,
     });
   }
 

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();
   });