@dommaker/harness 1.2.3 → 1.4.0

package/src/completion-checkers/tdd-chain.ts

@@ -3,7 +3,7 @@
  *
  * 协议（写死为机制本体，不进配置）：
  * - 实现 commit 必须带 trailer `Tested-By: <sha>`
- * - 被引 sha 须 a) 在本 WU 提交集内 b) 序列位置在本 commit 之前（比位置不比时间戳）c) 其文件清单命中 test_globs
+ * - 被引 sha 须 a) 在本提交集内 b) 序列位置在本 commit 之前（比位置不比时间戳）c) 其文件清单命中 test_globs
  * - 豁免：trailer `Tests: none` → waiver（放行记台账）；纯非代码/纯测试 commit 天然免检
  */
 
@@ -44,7 +44,7 @@ export function verifyTddChain(
     const ref = m[1].toLowerCase();
     const j = commits.findIndex((c) => c.sha.toLowerCase().startsWith(ref));
     if (j === -1) {
-      return { sha: commit.sha, verdict: 'violation', reason: `Tested-By 引用 ${ref} 不在本 WU 提交集内` };
+      return { sha: commit.sha, verdict: 'violation', reason: `Tested-By 引用 ${ref} 不在本提交集内` };
     }
     if (j >= i) {
       return { sha: commit.sha, verdict: 'violation', reason: `Tested-By 引用 ${ref} 位置不在本 commit 之前` };

package/src/completion-checkers/types.ts

@@ -1,12 +1,12 @@
 /**
- * Completion Checkers 类型定义（T7-E1，studio#160）
+ * Completion Checkers 类型定义
  *
  * 三个纯判定函数共享的输入/输出/配置类型。
  * 与 ConstraintCheck 闭环注册表无关：直接 export，不注册、不碰 checkers/index.ts。
- * 函数不碰文件系统与 git，commits 由调用方（studio 侧 git log）供给。
+ * 函数不碰文件系统与 git，commits 由调用方（git log）供给。
  */
 
-/** WU 提交输入（有序，base..HEAD 升序） */
+/** 提交集内的单个提交输入（有序，base..HEAD 升序） */
 export interface CommitInput {
   /** 完整 sha */
   sha: string;
@@ -49,7 +49,7 @@ export interface PhaseFormatResult {
 
 /** verifyContractPresence 上下文（类型→字段的判定方法映射是代码不是配置） */
 export interface ContractPresenceContext {
-  /** review 类型契约：studio agent-loop 已解析的 metadata.reviewReport */
+  /** review 类型契约：调用方已解析的 metadata.reviewReport */
   reviewReport?: unknown;
   [key: string]: unknown;
 }
@@ -62,7 +62,7 @@ export interface ContractPresenceResult {
 }
 
 /**
- * completion_checkers 配置（对应 yml 顶层键 `completion_checkers:`，studio 侧自解）。
+ * completion_checkers 配置（对应 yml 顶层键 `completion_checkers:`，消费方自解）。
  * 只配开关/glob/契约类型清单；协议格式（Tested-By、Tests: none、phase 结构）写死为机制本体。
  * 缺省 = 全开 + 默认 glob。
  */

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,30 @@
 约束引擎核心：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）
+- `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）

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: [] });
+    });
+  });
+});