@dommaker/harness 1.3.0 → 1.5.0

package/src/context/session-manager.ts

@@ -8,6 +8,7 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
+import { readJsonl, appendJsonl } from '../utils/jsonl';
 import { ContextTracker } from '../monitoring/context-tracker';
 import type {
   SessionEvent,
@@ -65,20 +66,12 @@ export class SessionManager {
     // 从磁盘恢复
     const eventsPath = path.join(this.getSessionDir(id), 'events.jsonl');
     try {
-      if (!fs.existsSync(eventsPath)) return undefined;
-
-      const content = fs.readFileSync(eventsPath, 'utf-8');
-      const lines = content.trim().split('\n').filter(Boolean);
-      if (lines.length === 0) return undefined;
-
-      const events: SessionEvent[] = [];
-      for (const line of lines) {
-        try {
-          events.push(JSON.parse(line) as SessionEvent);
-        } catch {
-          // 跳过损坏行
-        }
-      }
+      // 坏行策略：skip（原逐行 catch 跳过语义不变，harness#82）；
+      // 空文件判定保持原始非空行数口径（合法 + 坏行 = 0 才算空）
+      // 计数去向：并进空事件判定的原始行数口径（harness#100 记名豁免：会话恢复面只区分
+      // "有没有事件"，单列坏行数不改变任何输出；会话事件写链在本地，损坏=半写入截断）
+      const { records: events, skippedLines } = readJsonl<SessionEvent>(eventsPath, 'skip');
+      if (events.length + skippedLines === 0) return undefined;
 
       const stat = fs.statSync(eventsPath);
       const handle: SessionHandle = {
@@ -178,22 +171,16 @@ export class SessionManager {
           // 从 events.jsonl 恢复事件
           const eventsPath = path.join(sessionsDir, sessionId, 'events.jsonl');
           if (fs.existsSync(eventsPath)) {
-            const content = fs.readFileSync(eventsPath, 'utf-8');
-            const lines = content.trim().split('\n').filter(Boolean);
-
-            // 只恢复 checkpoint 之前的事件
-            const events = lines
-              .slice(0, checkpointData.eventCount)
-              .map(line => {
-                try {
-                  return JSON.parse(line) as SessionEvent;
-                } catch {
-                  return null;
-                }
-              })
-              .filter((e): e is SessionEvent => e !== null);
-
-            handle.events = events;
+            // 坏行策略：skip（原逐行 null-filter 语义不变，harness#82）；
+            // 只恢复 checkpoint 之前的原始行（head 截断在 parse 之前）；
+            // !== null 沿用原过滤口径
+            // 计数去向：豁免（harness#100）——恢复路径没有用户可见输出面（失败即整体抛
+            // `Checkpoint ${id} 不存在`），坏行只会让恢复出的事件少于 checkpoint 声明数；
+            // 告知需要改 loadCheckpoint 的抛错形状，属行为变更不在本票
+            const { records } = readJsonl<SessionEvent>(eventsPath, 'skip', {
+              head: checkpointData.eventCount,
+            });
+            handle.events = records.filter((e): e is SessionEvent => e !== null);
           }
 
           return handle;
@@ -237,9 +224,8 @@ export class SessionManager {
    */
   private appendEvent(sessionId: string, event: SessionEvent): void {
     try {
-      const eventsPath = path.join(this.getSessionDir(sessionId), 'events.jsonl');
-      const line = JSON.stringify(event) + '\n';
-      fs.appendFileSync(eventsPath, line, 'utf-8');
+      // 写链收口：ensureDir + append（harness#82）
+      appendJsonl(path.join(this.getSessionDir(sessionId), 'events.jsonl'), event);
     } catch {
       // 持久化失败，静默处理
     }

package/src/core/CONTEXT.md

@@ -4,27 +4,31 @@
 约束引擎核心：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) + Agent prompt 渲染(agent-prompt-renderer：trigger 参数化分组渲染，role 路由留 studio，H6/G6)/漂移校验(injection-drift：含注入段落点路由 resolveInjectionTarget，CLAUDE.md 有标记优先、否则 AGENTS.md PRESERVE:governance，studio #307)/使用统计(usage-report)；CheckEnv 生产侧唯一构造点 `buildCheckEnv(context, providers|'none')`（checkers/types.ts：providers = 证据接线，'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` 配置诊断
 - `effective-set.ts` — `filterEnabledEntries(knownIds, entries, {onUnknownId})`：约束侧（collect）与门禁侧（throw）共用的 config 条目筛选器
-- `validators/` — checkpoints、passes-gate、CSO 验证器
+- `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/` — 会话管理
 - `spec/validator` — SpecValidator
-- `project-config-loader` — 项目配置加载 + 约束合并（mergeConstraints 内含 preset 裁剪：presets/ 纯数据 + 未知名回落 standard，禁用到未知 id 经 effective-set 共享筛选器 collect 模式）
+- `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/扫描类工具流调用方
 
 ## 依赖关系
 - 被所有模块依赖（基础层，无上层依赖）
 - 依赖 `src/types/` 类型定义
 - 依赖 `src/utils/` 工具函数
-- 依赖 `src/monitoring/traces` TraceCollector
+- 对 `cli/`、`gates/`、`monitoring/` **零值导入**（type-only 允许）：方向由 eslint.config.mjs 的 `@typescript-eslint/no-restricted-imports`（error 级）锁死，守卫测试见 `src/__tests__/layering.test.ts`（harness#88）
 
 ## 约定
 - 约束定义在 `constraints/definitions/{iron-laws,guidelines,prompts}.ts`，不在运行时代码中定义
 - check 层必须带真实 checker（注册表闭环，引用未注册 checker 构建报错）
 - Iron Law 违规必须 throw ConstraintViolationError
-- 检查器使用单例模式(ConstraintChecker.getInstance())
+- 上行数据一律注入，不在 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 既不做成模块级全局也不做成单例字段
 
 ## 注意事项
 - 零 Token 成本：所有分析纯文件操作，无 LLM 调用
 - 约束配置支持 .harness/config.yml 自定义合并（preset 真实生效）
-- 存在性探测约束（capability_sync/docs_freshness/context_doc_sync）在约定文件缺失时 skip，不计 pass/fail
+- 存在性探测约束（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__/capabilities-reconcile.test.ts

@@ -0,0 +1,200 @@
+/**
+ * capabilities-reconcile 纯判定测试（ADR-0009）
+ *
+ * interface 即测试面：喂文档内容与文件清单，断言判定结果；无 fs/git fixture。
+ */
+
+import {
+  reconcileCapabilities,
+  significantCodeChanges,
+  collectSourceFiles,
+} from '../capabilities-reconcile';
+
+const TABLE = [
+  '| 模块 | 文件 | 说明 |',
+  '|------|------|------|',
+  '| Core | src/core/checker.ts | 引擎 |',
+  '| Gates | src/gates/ | 门禁目录 |',
+].join('\n');
+
+function withExtras(extraLines: string[]): string {
+  return [TABLE, ...extraLines].join('\n');
+}
+
+describe('reconcileCapabilities — 解析口径', () => {
+  it('收集所有单元格的文件与目录条目，不再只看第二列', () => {
+    const content = withExtras(['| src/utils/helper.ts | 名字在首列 | x |']);
+    const v = reconcileCapabilities({
+      content,
+      populationFiles: [],
+    });
+    expect(v.fileEntries).toContain('src/core/checker.ts');
+    expect(v.fileEntries).toContain('src/utils/helper.ts');
+    expect(v.dirEntries).toEqual(['src/gates/']);
+  });
+
+  it('hasTable 区分散文文档与有表格零条目；listingFormat 识别计数行', () => {
+    expect(reconcileCapabilities({ content: '随便写点什么', populationFiles: [] }).hasTable).toBe(false);
+    const emptyTable = '| 模块 | 文件 |\n|---|---|';
+    expect(reconcileCapabilities({ content: emptyTable, populationFiles: [] }).hasTable).toBe(true);
+    const listing = '# 能力\nCLI Commands (9)\nIron Laws (3)';
+    expect(reconcileCapabilities({ content: listing, populationFiles: [] }).listingFormat).toBe(true);
+  });
+});
+
+describe('reconcileCapabilities — 代码→文档（漏登记）', () => {
+  const population = ['src/core/checker.ts', 'src/gates/command.ts', 'src/knowledge/store.ts'];
+
+  it('module 模式：目录条目参与覆盖，未覆盖文件聚合为目录', () => {
+    const v = reconcileCapabilities({
+      content: TABLE,
+      populationFiles: population,
+      sourceRoots: ['src'],
+    });
+    expect(v.uncoveredFiles).toEqual(['src/knowledge/store.ts']);
+    expect(v.uncoveredDirs).toEqual(['src/knowledge/']);
+  });
+
+  it('目录条目恒参与覆盖（check/fix 同规则），mode 只是调用方取哪份输出形状', () => {
+    const v = reconcileCapabilities({
+      content: TABLE,
+      populationFiles: population,
+      sourceRoots: ['src'],
+    });
+    expect(v.coverageEntries).toContain('src/gates/');
+    expect(v.uncoveredFiles).toEqual(['src/knowledge/store.ts']);
+    // file 模式调用方读 uncoveredFiles；module 模式读 uncoveredDirs——同一判定两种投影
+    expect(v.uncoveredDirs).toEqual(['src/knowledge/']);
+  });
+
+  it('文件条目路径边界后缀匹配：兼容 basename 登记但拒绝模糊碰撞', () => {
+    const content = withExtras(['| 局部 | core/checker.ts | 相对路径条目 |']);
+    const v = reconcileCapabilities({
+      content,
+      populationFiles: ['src/core/checker.ts', 'src/otherchecker.ts', 'src/docs/src/checked.ts'],
+    });
+    expect(v.uncoveredFiles).toEqual(['src/otherchecker.ts', 'src/docs/src/checked.ts']);
+  });
+
+  it('增量判定独立于全量：changedFiles 未被覆盖的进入 uncoveredChanges', () => {
+    const v = reconcileCapabilities({
+      content: TABLE,
+      populationFiles: population,
+      changedFiles: ['src/core/checker.ts', 'src/knowledge/store.ts'],
+      sourceRoots: ['src'],
+    });
+    expect(v.uncoveredChanges).toEqual(['src/knowledge/store.ts']);
+  });
+});
+
+describe('reconcileCapabilities — 文档→代码（幽灵）', () => {
+  it('文件条目多根相对路径：项目根或任一源码根下存在即算活', () => {
+    const content = '| 模块 | 文件 | 说明 |\n|---|---|---|\n| API | apps/routes.ts | studio 式多根 |';
+    const v = reconcileCapabilities({
+      content,
+      populationFiles: [],
+      sourceRoots: ['src', 'apps/api'],
+      fileExists: (rel) => rel === 'apps/api/apps/routes.ts',
+    });
+    expect(v.deadEntries).toEqual([]);
+  });
+
+  it('目录条目也查幽灵（口径从严，Q6a）：磁盘不存在且实况无文件才算死', () => {
+    const v = reconcileCapabilities({
+      content: TABLE,
+      populationFiles: ['src/core/checker.ts'],
+      fileExists: (rel) => !rel.startsWith('src/gates'),
+    });
+    expect(v.deadEntries).toEqual(['src/gates/']);
+  });
+
+  it('目录条目实况有文件即活（oracle 缺省的纯清单场景）', () => {
+    const v = reconcileCapabilities({
+      content: TABLE,
+      populationFiles: ['src/core/checker.ts', 'src/gates/command.ts'],
+    });
+    expect(v.deadEntries).toEqual([]);
+  });
+
+  it('裸文件名条目按实况兜底：无任何文件命中才算幽灵', () => {
+    const content = withExtras(['| 别名 | routes.ts | 裸 basename |']);
+    const v = reconcileCapabilities({
+      content,
+      populationFiles: [
+        'src/core/checker.ts',
+        'src/gates/command.ts',
+        'src/agent-configs/routes.ts',
+      ],
+    });
+    expect(v.deadEntries).toEqual([]);
+  });
+
+  it(' basename 碰撞场景：全路径幽灵即使同名文件存活仍被报出（2026-08-08 事故回归）', () => {
+    const content = withExtras(['| 旧 | src/agent-configs/routes.ts | 已删 |']);
+    const v = reconcileCapabilities({
+      content,
+      populationFiles: ['src/agents/routes.ts'],
+      fileExists: () => false,
+    });
+    expect(v.deadEntries).toContain('src/agent-configs/routes.ts');
+  });
+});
+
+describe('significantCodeChanges', () => {
+  it('只留有意义的代码变更：扩展名过滤 + 排除测试文件', () => {
+    const names = [
+      'src/core/checker.ts',
+      'src/web/App.tsx',
+      'scripts/run.js',
+      'src/__tests__/checker-extra.test.ts',
+      'src/core/checker.test.ts',
+      'src/core/checker.spec.ts',
+      'docs/readme.md',
+      'package.json',
+    ];
+    expect(significantCodeChanges(names)).toEqual([
+      'src/core/checker.ts',
+      'src/web/App.tsx',
+      'scripts/run.js',
+    ]);
+  });
+});
+
+describe('collectSourceFiles', () => {
+  const fs = require('fs') as typeof import('fs');
+  const os = require('os') as typeof import('os');
+  const path = require('path') as typeof import('path');
+
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'reconcile-scan-'));
+    fs.mkdirSync(path.join(tmpDir, 'src/core'), { recursive: true });
+    fs.mkdirSync(path.join(tmpDir, 'src/__tests__'), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, 'src/core/index.ts'), '');
+    fs.writeFileSync(path.join(tmpDir, 'src/core/foo.ts'), '');
+    fs.writeFileSync(path.join(tmpDir, 'src/core/types.d.ts'), '');
+    fs.writeFileSync(path.join(tmpDir, 'src/core/App.tsx'), '');
+    fs.writeFileSync(path.join(tmpDir, 'src/__tests__/foo.test.ts'), '');
+  });
+
+  it('返回项目相对路径；跳过 barrel/声明文件/测试目录；默认不含 tsx', () => {
+    expect(collectSourceFiles(tmpDir, ['src']).sort()).toEqual(['src/core/foo.ts']);
+  });
+
+  it('includeTsx 时纳入 .tsx', () => {
+    expect(collectSourceFiles(tmpDir, ['src'], { includeTsx: true }).sort()).toEqual([
+      'src/core/App.tsx',
+      'src/core/foo.ts',
+    ]);
+  });
+
+  it('多根收集并集', () => {
+    fs.mkdirSync(path.join(tmpDir, 'apps/api/src'), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, 'apps/api/src/main.ts'), '');
+    expect(collectSourceFiles(tmpDir, ['src', 'apps/api/src']).sort()).toEqual([
+      'apps/api/src/main.ts',
+      'src/core/foo.ts',
+    ]);
+  });
+});

package/src/core/constraints/__tests__/capability-counts.test.ts

@@ -0,0 +1,94 @@
+/**
+ * 能力清单计数注入测试（架构评审 2026-09-02 · 候选9 / harness#88）
+ *
+ * capabilities-parser 属 core，此前**值导入** cli/commands/definitions 与
+ * gates/definitions 来数命令数——core 向上的运行时依赖。现在计数所需的定义
+ * 由调用方（cli 侧）注入，core 只消费最小形状（命令条目集合 + 门禁的 cli 字段）。
+ *
+ * 断言口径：计数由注入源推导，与宿主仓真实定义表无关。
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { IRON_LAWS, GUIDELINES } from '../definitions';
+import {
+  checkCapabilityCounts,
+  updateCapabilityCounts,
+  type CapabilityDefinitionSource,
+} from '../capabilities-parser';
+
+/** 3 条非门禁命令 + 4 条门禁（其中 2 条带 cli 元数据）→ CLI Commands = 5 */
+const SOURCE: CapabilityDefinitionSource = {
+  commands: [{}, {}, {}],
+  gates: [{}, { cli: {} }, { cli: {} }, {}],
+};
+
+describe('能力清单计数（注入定义源，harness#88）', () => {
+  let projectDir: string;
+
+  beforeAll(() => {
+    projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-capability-counts-'));
+  });
+
+  afterAll(() => {
+    try {
+      fs.rmSync(projectDir, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  });
+
+  function writeCapabilities(content: string): string {
+    const dir = fs.mkdtempSync(path.join(projectDir, 'case-'));
+    fs.writeFileSync(path.join(dir, 'CAPABILITIES.md'), content, 'utf-8');
+    return dir;
+  }
+
+  describe('updateCapabilityCounts', () => {
+    it('CLI Commands 计数 = 注入命令数 + 带 cli 的门禁数', () => {
+      const out = updateCapabilityCounts('## CLI Commands (999)\n', SOURCE);
+      expect(out).toContain('CLI Commands (5)');
+    });
+
+    it('Quality Gates 计数 = 注入门禁总数（不看 cli 字段）', () => {
+      const out = updateCapabilityCounts('## Quality Gates (999)\n', SOURCE);
+      expect(out).toContain('Quality Gates (4)');
+    });
+
+    it('Iron Laws / Guidelines 计数仍来自 core 自身定义表（同层，不注入）', () => {
+      const out = updateCapabilityCounts('Iron Laws (999)\nGuidelines (999)\n', SOURCE);
+      expect(out).toContain(`Iron Laws (${Object.keys(IRON_LAWS).length})`);
+      expect(out).toContain(`Guidelines (${Object.keys(GUIDELINES).length})`);
+    });
+
+    it('不触碰文档中不存在的计数行', () => {
+      const out = updateCapabilityCounts('# Harness Capabilities\n\n无计数行\n', SOURCE);
+      expect(out).toBe('# Harness Capabilities\n\n无计数行\n');
+    });
+
+    it('同一注入源下写回幂等', () => {
+      const once = updateCapabilityCounts('CLI Commands (0)\nQuality Gates (0)\n', SOURCE);
+      expect(updateCapabilityCounts(once, SOURCE)).toBe(once);
+    });
+  });
+
+  describe('checkCapabilityCounts', () => {
+    it('计数与注入源一致 → match', () => {
+      const dir = writeCapabilities('## CLI Commands (5)\n## Quality Gates (4)\n');
+      expect(checkCapabilityCounts(dir, SOURCE)).toEqual({ match: true, mismatches: [] });
+    });
+
+    it('计数漂移 → match=false 并报出注入源的 actual', () => {
+      const dir = writeCapabilities('## CLI Commands (999)\n## Quality Gates (4)\n');
+      const { match, mismatches } = checkCapabilityCounts(dir, SOURCE);
+      expect(match).toBe(false);
+      expect(mismatches.join('\n')).toContain('CLI Commands: 文档 999 → 实际 5');
+    });
+
+    it('CAPABILITIES.md 不存在 → 跳过（无 mismatch）', () => {
+      const dir = fs.mkdtempSync(path.join(projectDir, 'empty-'));
+      expect(checkCapabilityCounts(dir, SOURCE)).toEqual({ match: true, mismatches: [] });
+    });
+  });
+});

package/src/core/constraints/__tests__/git-evidence.test.ts

@@ -0,0 +1,208 @@
+/**
+ * git 证据适配器测试（架构评审 #87）
+ *
+ * 覆盖：
+ * - 真 git adapter 在三类证据（staged diff / 变更名 / HEAD 目录）上的取证正确性
+ * - 命令失败语义：diff → ''、ls-tree → null（全部视为新目录）
+ * - memo 落在实例层：同一实例内每条 git 命令至多执行一次
+ * - context-builder 与 checker 共用同一实例 → 一次 run 内无重复 git 命令
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { execSync } from 'child_process';
+
+import {
+  createGitEvidence,
+  parseHeadDirs,
+  realGitCommandRunner,
+  type GitCommandRunner,
+  type GitEvidence,
+} from '../git-evidence';
+import { buildConstraintContext } from '../context-builder';
+import { ConstraintChecker } from '../checker';
+import { GUIDELINES } from '../definitions';
+import type { MergedConstraintsConfig } from '../../../types/project-config';
+
+/** 建一个真 git fixture：committed src/existing.ts + 一个 staged 修改 */
+function makeRepo(options: { stagedChange?: boolean } = {}): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-git-evidence-'));
+  execSync('git init -q', { cwd: dir, stdio: 'pipe' });
+  execSync('git config user.email "test@example.com"', { cwd: dir, stdio: 'pipe' });
+  execSync('git config user.name "Test"', { cwd: dir, stdio: 'pipe' });
+  fs.mkdirSync(path.join(dir, 'src', 'nested'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'src', 'existing.ts'), 'export const a = 1;\n');
+  fs.writeFileSync(path.join(dir, 'src', 'nested', 'deep.ts'), 'export const b = 1;\n');
+  fs.writeFileSync(path.join(dir, 'README.md'), '# fixture\n');
+  execSync('git add .', { cwd: dir, stdio: 'pipe' });
+  execSync('git commit -q -m init', { cwd: dir, stdio: 'pipe' });
+  if (options.stagedChange !== false) {
+    fs.writeFileSync(path.join(dir, 'src', 'existing.ts'), 'export const a = 2;\n');
+    execSync('git add src/existing.ts', { cwd: dir, stdio: 'pipe' });
+  }
+  return dir;
+}
+
+/** 记录每条实际执行的 git 命令，执行本身委托真 adapter */
+function countingRunner(): { runner: GitCommandRunner; commands: string[] } {
+  const commands: string[] = [];
+  return {
+    commands,
+    runner: (command, cwd) => {
+      commands.push(command);
+      return realGitCommandRunner(command, cwd);
+    },
+  };
+}
+
+/** 包住一份证据实例，记录「哪个 phase 调了哪个证据方法」（取证是否同源的可观测面） */
+function recordingEvidence(
+  source: GitEvidence,
+  phase: () => string,
+  calls: string[]
+): GitEvidence {
+  return {
+    projectPath: source.projectPath,
+    stagedDiff: () => {
+      calls.push(`${phase()}:stagedDiff`);
+      return source.stagedDiff();
+    },
+    changedFileNames: (staged: boolean) => {
+      calls.push(`${phase()}:changedFileNames`);
+      return source.changedFileNames(staged);
+    },
+    headDirs: () => {
+      calls.push(`${phase()}:headDirs`);
+      return source.headDirs();
+    },
+  };
+}
+
+describe('git 证据适配器（#87）', () => {
+  describe('真 git adapter 取证', () => {
+    it('stagedDiff 返回 staged 全量 diff；changedFileNames 按 staged 选择命令', () => {
+      const dir = makeRepo();
+      const evidence = createGitEvidence(dir);
+
+      expect(evidence.stagedDiff()).toContain('+export const a = 2;');
+      expect(evidence.changedFileNames(true)).toBe('src/existing.ts');
+      // 无未暂存变更 → unstaged diff 为空
+      expect(evidence.changedFileNames(false)).toBe('');
+
+      fs.writeFileSync(path.join(dir, 'src', 'existing.ts'), 'export const a = 3;\n');
+      expect(evidence.changedFileNames(false)).toBe(''); // 实例已 memo，取同一快照
+      expect(createGitEvidence(dir).changedFileNames(false)).toBe('src/existing.ts');
+    });
+
+    it('headDirs 覆盖已提交目录，未提交目录不在集合内', () => {
+      const dir = makeRepo();
+      const dirs = createGitEvidence(dir).headDirs();
+
+      expect(dirs).not.toBeNull();
+      expect(dirs!.has('src')).toBe(true);
+      expect(dirs!.has('src/nested')).toBe(true);
+      fs.mkdirSync(path.join(dir, 'src', 'brand-new'), { recursive: true });
+      expect(createGitEvidence(dir).headDirs()!.has('src/brand-new')).toBe(false);
+    });
+
+    it('非 git 目录：diff 类证据为空串，headDirs 为 null（不重试、不抛错）', () => {
+      const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-git-evidence-'));
+      const { runner, commands } = countingRunner();
+      const evidence = createGitEvidence(dir, runner);
+
+      expect(evidence.stagedDiff()).toBe('');
+      expect(evidence.changedFileNames(true)).toBe('');
+      expect(evidence.headDirs()).toBeNull();
+      // 失败结果同样 memo：重复调用不再 spawn
+      expect(evidence.headDirs()).toBeNull();
+      expect(evidence.changedFileNames(true)).toBe('');
+      expect(commands.length).toBe(3);
+    });
+  });
+
+  describe('parseHeadDirs', () => {
+    it('逐层展开文件路径的父目录', () => {
+      const dirs = parseHeadDirs('src/a/b.ts\nREADME.md\n');
+      expect([...dirs].sort()).toEqual(['src', 'src/a']);
+    });
+  });
+
+  describe('memo 落在实例层', () => {
+    it('同一实例内同类 git 命令至多执行一次', () => {
+      const dir = makeRepo();
+      const { runner, commands } = countingRunner();
+      const evidence = createGitEvidence(dir, runner);
+
+      const first = evidence.stagedDiff();
+      const stagedNames = evidence.changedFileNames(true);
+      const unstagedNames = evidence.changedFileNames(false);
+      const dirs = evidence.headDirs();
+
+      expect(evidence.stagedDiff()).toBe(first);
+      expect(evidence.changedFileNames(true)).toBe(stagedNames);
+      expect(evidence.changedFileNames(false)).toBe(unstagedNames);
+      expect(evidence.headDirs()).toEqual(dirs);
+
+      expect(commands).toEqual([
+        'git diff --cached',
+        'git diff --cached --name-only',
+        'git diff --name-only',
+        'git ls-tree -r --name-only HEAD',
+      ]);
+      expect(new Set(commands).size).toBe(commands.length);
+    });
+
+    it('两个实例 = 两次取证（memo 不是隐式全局）', () => {
+      const dir = makeRepo();
+      const { runner, commands } = countingRunner();
+
+      createGitEvidence(dir, runner).stagedDiff();
+      createGitEvidence(dir, runner).stagedDiff();
+
+      expect(commands.filter(c => c === 'git diff --cached')).toHaveLength(2);
+    });
+  });
+
+  describe('context-builder 与 checker 共用同一证据来源（#87 验收）', () => {
+    it('一次 check run 内同类 git 命令至多执行一次', async () => {
+      const dir = makeRepo();
+      fs.writeFileSync(
+        path.join(dir, 'CAPABILITIES.md'),
+        '# Capabilities\n\n| 模块 | 文件 | 说明 |\n|------|------|------|\n| existing | src/existing.ts | 条目 |\n'
+      );
+      const { runner, commands } = countingRunner();
+      const shared = createGitEvidence(dir, runner);
+      // 记录器：哪个消费者（phase）调了哪个证据方法
+      const phase = { current: 'context' };
+      const calls: string[] = [];
+      const evidence = recordingEvidence(shared, () => phase.current, calls);
+
+      const context = await buildConstraintContext({ projectPath: dir, staged: true, evidence });
+      // capability_sync 经 CheckEnv.stagedDiffNames() 取同一份 git 证据
+      const merged: MergedConstraintsConfig = {
+        ironLaws: {},
+        guidelines: { capability_sync: GUIDELINES['capability_sync'] },
+        prompts: {},
+        custom: [],
+        disabled: [],
+        unknownIds: [],
+      };
+      const checker = new ConstraintChecker({ record: () => undefined });
+      phase.current = 'checker';
+      const runResult = await checker.checkConstraints(context, merged, evidence);
+
+      // capability_sync 确实被评估（非 skip）→ 它经 env.stagedDiffNames() 取过证据
+      expect(runResult.guidelines.map(r => r.id)).toEqual(['capability_sync']);
+      expect(runResult.guidelines[0].skipped).toBeUndefined();
+      // 两个消费者都从注入的这一份实例取证据（checker 没有另起炉灶）
+      expect(calls).toContain('context:changedFileNames');
+      expect(calls).toContain('checker:changedFileNames');
+      // 两侧各自需要同一份 staged 名单，合计只 spawn 一次
+      expect(commands).toEqual([
+        'git diff --cached --name-only',
+        'git ls-tree -r --name-only HEAD',
+      ]);
+    });
+  });
+});