@dommaker/harness 1.3.0 → 1.5.0

package/src/core/constraints/__tests__/injection-drift.test.ts

@@ -11,7 +11,6 @@
  */
 
 import * as fs from 'fs';
-import * as os from 'os';
 import * as path from 'path';
 import { detectInjectionDrift, INJECTION_DRIFT_FIX_HINT } from '../injection-drift';
 import {
@@ -19,12 +18,11 @@ import {
   CONSTRAINTS_START_MARKER,
 } from '../injection-renderer';
 import { getEffectiveConstraints } from '../../effective-constraints';
+import { createProjectFixture, writeProjectConfig } from '../../../test-setup/project-fixture';
 
 const TEST_VERSION = '9.9.9-test';
 
-function makeTmpProject(): string {
-  return fs.mkdtempSync(path.join(os.tmpdir(), 'harness-drift-test-'));
-}
+const makeTmpProject = (): string => createProjectFixture({ name: 'harness-drift-test' });
 
 /** 写入与当前生效集完全一致的注入段（版本 TEST_VERSION） */
 function writeSyncedClaudeMd(root: string, extra = ''): string {
@@ -102,12 +100,7 @@ describe('detectInjectionDrift', () => {
     const root = makeTmpProject();
     writeSyncedClaudeMd(root);
     // 注入后禁用一条 prompt，但不重跑 init
-    fs.mkdirSync(path.join(root, '.harness'), { recursive: true });
-    fs.writeFileSync(
-      path.join(root, '.harness', 'config.yml'),
-      'constraints:\n  no_fuzzy_completion_claim:\n    enabled: false\n',
-      'utf-8'
-    );
+    writeProjectConfig(root, 'constraints:\n  no_fuzzy_completion_claim:\n    enabled: false\n');
 
     const drift = detectInjectionDrift(root, TEST_VERSION);
 

package/src/core/constraints/__tests__/injection-writer.test.ts

@@ -0,0 +1,231 @@
+/**
+ * injection-writer 旁测（架构评审候选1，ADR-0011）
+ *
+ * 测试面 = 纯函数（字符串进、字符串出）+ 落点路由（真实 fs 临时目录）。
+ * 幂等/半标记守护/两种尾部形状/读写路由优先级全部在此测一次；
+ * 消费方（init/retire/drift）只测各自语义（init-injection.test 行为面）。
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from '@jest/globals';
+import * as fs from 'fs';
+import * as path from 'path';
+import {
+  replaceStandaloneRange,
+  replaceEnclosedRange,
+  cutMarkerBlock,
+  resolveInjectionTarget,
+  resolveGovernanceLanding,
+  GOVERNANCE_HEADING,
+  hasGovernanceContract,
+  countGovernanceHeadings,
+  hasPreserveBlock,
+} from '../injection-writer';
+import {
+  CONSTRAINTS_START_MARKER as CS,
+  CONSTRAINTS_END_MARKER as CE,
+} from '../injection-renderer';
+
+const B = '<!-- B -->';
+const E = '<!-- E -->';
+
+describe('replaceStandaloneRange — 独立成节形状', () => {
+  it('替换含标记区间；尾文多换行折叠为恰好一个空行', () => {
+    const content = `head\n${B}\nold\n${E}\n\n\n\nrest\n`;
+    const r = replaceStandaloneRange(content, B, E, `${B}\nnew\n${E}\n`);
+    expect(r).toEqual({ kind: 'updated', content: `head\n${B}\nnew\n${E}\n\nrest\n` });
+  });
+
+  it('尾文恰好一个空行分隔（含原本无多余换行时）', () => {
+    const content = `${B}\nold\n${E}\nrest\n`;
+    const r = replaceStandaloneRange(content, B, E, `${B}\nnew\n${E}\n`);
+    expect(r).toEqual({ kind: 'updated', content: `${B}\nnew\n${E}\n\nrest\n` });
+  });
+
+  it('区间在文件末尾：不产生尾空行', () => {
+    const content = `head\n${B}\nold\n${E}\n`;
+    const r = replaceStandaloneRange(content, B, E, `${B}\nnew\n${E}\n`);
+    expect(r).toEqual({ kind: 'updated', content: `head\n${B}\nnew\n${E}\n` });
+  });
+
+  it('幂等：重复替换结果不动点', () => {
+    const once = replaceStandaloneRange(`a\n${B}\nx\n${E}\n\n\nb\n`, B, E, `${B}\nnew\n${E}\n`);
+    expect(once.kind).toBe('updated');
+    const twice = replaceStandaloneRange((once as { content: string }).content, B, E, `${B}\nnew\n${E}\n`);
+    expect(twice).toEqual(once);
+  });
+
+  it('两俱无 → absent；单边/乱序 → half（拒写）', () => {
+    expect(replaceStandaloneRange('nothing here', B, E, 'x')).toEqual({ kind: 'absent' });
+    expect(replaceStandaloneRange(`${B}\norphan`, B, E, 'x')).toEqual({ kind: 'half' });
+    expect(replaceStandaloneRange(`orphan ${E}`, B, E, 'x')).toEqual({ kind: 'half' });
+    expect(replaceStandaloneRange(`${E}\n...\n${B}`, B, E, 'x')).toEqual({ kind: 'half' });
+  });
+});
+
+describe('replaceEnclosedRange — 外层收口紧随形状', () => {
+  it('恰好剥一个前导换行，手写余文的额外换行原样保留', () => {
+    const inner = `\n## H\n${CS}\nold\n${CE}\n\n手写余文\n`;
+    const r = replaceEnclosedRange(inner, CS, CE, `${CS}\nnew\n${CE}\n`);
+    expect(r).toEqual({ kind: 'updated', content: `\n## H\n${CS}\nnew\n${CE}\n\n手写余文\n` });
+  });
+
+  it('区间后仅有行尾换行（收口标记直接落行）', () => {
+    const inner = `\n${CS}\nold\n${CE}\n`;
+    const r = replaceEnclosedRange(inner, CS, CE, `${CS}\nnew\n${CE}\n`);
+    expect(r).toEqual({ kind: 'updated', content: `\n${CS}\nnew\n${CE}\n` });
+  });
+
+  it('absent → 调用方走追加；half → 拒写', () => {
+    expect(replaceEnclosedRange('\n纯手写段\n', CS, CE, 'x')).toEqual({ kind: 'absent' });
+    expect(replaceEnclosedRange(`${CS}orphan`, CS, CE, 'x')).toEqual({ kind: 'half' });
+  });
+});
+
+describe('cutMarkerBlock', () => {
+  it('切出 before/inner/after 三段，inner 含首尾标记行间全部文本', () => {
+    const content = `before\n${B}\ninner-body\n${E}\nafter\n`;
+    expect(cutMarkerBlock(content, B, E)).toEqual({
+      before: 'before\n',
+      inner: '\ninner-body\n',
+      after: '\nafter\n',
+    });
+  });
+
+  it('absent / half 与替换函数同一判定', () => {
+    expect(cutMarkerBlock('clean', B, E)).toBe('absent');
+    expect(cutMarkerBlock(`${B} only`, B, E)).toBe('half');
+  });
+});
+
+describe('落点路由（读写两侧，studio #307/#302）', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(process.cwd(), 'temp-test-inj-writer-'));
+  });
+  afterEach(() => fs.rmSync(dir, { recursive: true, force: true }));
+
+  const write = (name: string, content: string) =>
+    fs.writeFileSync(path.join(dir, name), content, 'utf-8');
+
+  it('resolveInjectionTarget：CLAUDE.md 完整标记段优先于 AGENTS.md', () => {
+    write('CLAUDE.md', `x\n${CS}\nbody\n${CE}\n`);
+    write('AGENTS.md', `<!-- PRESERVE:governance -->\n${CS}\nbody2\n${CE}\n`);
+    expect(resolveInjectionTarget(dir)?.file).toBe('CLAUDE.md');
+  });
+
+  it('CLAUDE.md 标记残缺（单边）不算落点 → 落 AGENTS.md', () => {
+    write('CLAUDE.md', `x\n${CS}\nbroken\n`);
+    write('AGENTS.md', `${CS}\nbody\n${CE}\n`);
+    expect(resolveInjectionTarget(dir)?.file).toBe('AGENTS.md');
+  });
+
+  it('两处均无完整标记段 → null（未注入）', () => {
+    write('CLAUDE.md', '# 无约束标记\n');
+    expect(resolveInjectionTarget(dir)).toBeNull();
+  });
+
+  it('resolveGovernanceLanding：CLAUDE.md 有标记或有旧版 Governance Rules 块 → claude-md', () => {
+    write('CLAUDE.md', `${CS}\nbody\n${CE}\n`);
+    expect(resolveGovernanceLanding(dir).target).toBe('claude-md');
+    write('CLAUDE.md', '# CLAUDE.md\n\n## Governance Rules\n\n手写\n');
+    expect(resolveGovernanceLanding(dir).target).toBe('claude-md');
+  });
+
+  it('CLAUDE.md 与治理无关 / 不存在 → agents-md', () => {
+    write('CLAUDE.md', '# CLAUDE.md\n\n@AGENTS.md\n');
+    expect(resolveGovernanceLanding(dir).target).toBe('agents-md');
+    fs.rmSync(path.join(dir, 'CLAUDE.md'));
+    expect(resolveGovernanceLanding(dir).target).toBe('agents-md');
+  });
+
+  it('落点路由消费共享宽松谓词：双空格标题变体也路由 claude-md（fail-open）', () => {
+    write('CLAUDE.md', '# CLAUDE.md\n\n##  Governance Rules\n\n手写\n');
+    expect(resolveGovernanceLanding(dir).target).toBe('claude-md');
+  });
+});
+
+describe('治理契约探测共享符号（#83，ADR-0011 补注：收口范围含探测器）', () => {
+  it('GOVERNANCE_HEADING 是标题字面量单一来源', () => {
+    expect(GOVERNANCE_HEADING).toBe('## Governance Rules');
+  });
+
+  describe('hasGovernanceContract — 宽松谓词（有无契约，fail-open）', () => {
+    it('精确标题 → true', () => {
+      expect(hasGovernanceContract('# doc\n\n## Governance Rules\n\n条款\n')).toBe(true);
+    });
+
+    it('双空格标题变体 → true（宁可信其有）', () => {
+      expect(hasGovernanceContract('# doc\n\n##  Governance Rules\n\n条款\n')).toBe(true);
+    });
+
+    it('HARNESS 约束标记在场 → true（完整注释壳与裸文本皆认）', () => {
+      expect(hasGovernanceContract('<!-- HARNESS_CONSTRAINTS_START -->\nx\n')).toBe(true);
+      expect(hasGovernanceContract('HARNESS_CONSTRAINTS_START\nx\n')).toBe(true);
+    });
+
+    it('两样皆无 → false', () => {
+      expect(hasGovernanceContract('# CLAUDE.md\n\n@AGENTS.md\n')).toBe(false);
+    });
+  });
+
+  describe('countGovernanceHeadings — 严格计数（正本标题，行尾锚定）', () => {
+    it('精确拼写逐个计数', () => {
+      expect(countGovernanceHeadings('## Governance Rules\n')).toBe(1);
+      expect(countGovernanceHeadings('## Governance Rules\n甲\n\n## Governance Rules\n乙\n')).toBe(2);
+    });
+
+    it('行尾空白容忍', () => {
+      expect(countGovernanceHeadings('## Governance Rules  \n')).toBe(1);
+      expect(countGovernanceHeadings('## Governance Rules\t\n')).toBe(1);
+    });
+
+    it('宽松变体不计入：双空格 / 三级标题 / 行中嵌入 → 0', () => {
+      expect(countGovernanceHeadings('##  Governance Rules\n')).toBe(0);
+      expect(countGovernanceHeadings('### Governance Rules\n')).toBe(0);
+      expect(countGovernanceHeadings('前文 ## Governance Rules 行中\n')).toBe(0);
+    });
+  });
+
+  describe('hasPreserveBlock — PRESERVE 块存在性 + 块体非空', () => {
+    const begin = '<!-- PRESERVE:governance -->';
+    const end = '<!-- /PRESERVE:governance -->';
+
+    it('块体非空 + 首尾标记独占一行 → true', () => {
+      expect(hasPreserveBlock(`# t\n${begin}\n## H\n条款\n${end}\n`, 'governance')).toBe(true);
+    });
+
+    it('块体仅空白 → false（被掏空）', () => {
+      expect(hasPreserveBlock(`${begin}\n   \n${end}\n`, 'governance')).toBe(false);
+      expect(hasPreserveBlock(`${begin}\n\n${end}\n`, 'governance')).toBe(false);
+    });
+
+    it('结束标记嵌在行中 = 畸形块 → false（显式收紧，#83）', () => {
+      expect(hasPreserveBlock(`${begin}\n条款 <!-- /PRESERVE:governance --> 尾注\n`, 'governance')).toBe(false);
+    });
+
+    it('结束标记缺失 / 乱序 → false', () => {
+      expect(hasPreserveBlock(`${begin}\n条款\n`, 'governance')).toBe(false);
+      expect(hasPreserveBlock(`${end}\n${begin}\n`, 'governance')).toBe(false);
+    });
+
+    it('开始标记不在 / 名称不符 → false', () => {
+      expect(hasPreserveBlock('没有标记\n', 'governance')).toBe(false);
+      expect(hasPreserveBlock(`${begin}\n条款\n${end}\n`, 'other')).toBe(false);
+    });
+
+    it('标记行行尾空白容忍（独占一行语义）', () => {
+      expect(hasPreserveBlock(`${begin}  \n条款\n${end}  \n`, 'governance')).toBe(true);
+    });
+  });
+
+  it('一致性 fixture：双空格 → 宽松在场 true 且严格计数 0；精确拼写 → 两者均认', () => {
+    const variant = '# CLAUDE.md\n\n##  Governance Rules\n\n条款\n';
+    expect(hasGovernanceContract(variant)).toBe(true);
+    expect(countGovernanceHeadings(variant)).toBe(0);
+
+    const exact = '# CLAUDE.md\n\n## Governance Rules\n\n条款\n';
+    expect(hasGovernanceContract(exact)).toBe(true);
+    expect(countGovernanceHeadings(exact)).toBe(1);
+  });
+});

package/src/core/constraints/__tests__/trace-injection.test.ts

@@ -0,0 +1,71 @@
+/**
+ * trace 记录器注入（工单 15 decycle 收尾 / harness#88）
+ *
+ * 原状态：checker 值导入 monitoring 的 getTraceCollector，并在首次记录时惰性接线
+ * （ADR-0003），`setTraceRecorder` 退化成只有测试在用的假 seam。
+ * 现在：记录器经**构造参数**注入；未注入 = no-op（core 零上行依赖，默认无副作用），
+ * 真实收集器由组合根（CLI 命令 / bootstrap）接线。
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { ConstraintChecker } from '../checker';
+import type { ExecutionTrace } from '../../../types/trace';
+
+jest.mock('../../../monitoring/traces', () => ({
+  getTraceCollector: jest.fn(() => ({ record: jest.fn() })),
+  TraceCollector: jest.fn(),
+  configureTraceCollector: jest.fn(),
+}));
+
+/** 替身收集器工厂（core 侧连测试也不值导入 monitoring，方向由 #88 规则锁） */
+const getTraceCollector = jest.requireMock('../../../monitoring/traces')
+  .getTraceCollector as jest.Mock;
+
+describe('trace 记录器构造注入（harness#88）', () => {
+  let projectDir: string;
+  /** 与 skip-semantics 同族的 fixture：目录不存在 → 存在性探测走 skip，不阻断 */
+  const context = () => ({
+    operation: 'code_implementation' as const,
+    projectPath: path.join(projectDir, 'not-created'),
+  });
+
+  beforeAll(() => {
+    projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-trace-injection-'));
+    getTraceCollector.mockClear();
+  });
+
+  afterAll(() => {
+    try {
+      fs.rmSync(projectDir, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  });
+
+  it('构造注入的记录器收到每条约束的 trace', async () => {
+    const records: ExecutionTrace[] = [];
+    const checker = new ConstraintChecker({ record: (t) => records.push(t) });
+
+    await checker.checkConstraints(context());
+
+    expect(records.map(r => r.constraintId)).toEqual(
+      expect.arrayContaining(['incremental_progress', 'no_implementation_without_requirement'])
+    );
+    expect(records.every(r => ['pass', 'fail', 'skip'].includes(r.result))).toBe(true);
+  });
+
+  it('setTraceRecorder 假 seam 已删除', () => {
+    const checker = new ConstraintChecker({ record: () => undefined });
+    expect((checker as any).setTraceRecorder).toBeUndefined();
+  });
+
+  it('未注入记录器时不记录，也不反向取全局收集器（core 零上行依赖）', async () => {
+    const unwired = new ConstraintChecker();
+
+    await unwired.checkConstraints(context());
+
+    expect(getTraceCollector).not.toHaveBeenCalled();
+  });
+});

package/src/core/constraints/__tests__/usage-report.test.ts

@@ -0,0 +1,112 @@
+/**
+ * traces.log 坏行 fixture（harness#82 + harness#100）
+ *
+ * #82：三种现行响应例证之「静默跳过」（原语义不变）——
+ * traces.log 单行损坏时 report 数据层不失败，返回全部合法 trace。
+ * #100：计数不再断在 module 层——新增 `readProjectTracesReport()` 报告入口，
+ * 并把坏行数挂进 `ConstraintsUsageReport`（与 `traceFileExists` 同一降级维度）。
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { createProjectFixture } from '../../../test-setup/project-fixture';
+import { readJsonl } from '../../../utils/jsonl';
+import {
+  buildConstraintsUsageReport,
+  readProjectTraces,
+  readProjectTracesReport,
+} from '../usage-report';
+import { DEFAULT_TRACE_FILE } from '../../../types/trace';
+
+describe('readProjectTraces 坏行容错（harness#82）', () => {
+  let root: string;
+
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-usage-report-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  function writeTraces(lines: string[]): void {
+    const tracePath = path.join(root, DEFAULT_TRACE_FILE);
+    fs.mkdirSync(path.dirname(tracePath), { recursive: true });
+    fs.writeFileSync(tracePath, lines.join('\n') + '\n', 'utf-8');
+  }
+
+  it('坏行静默跳过，返回全部合法 trace', () => {
+    writeTraces([
+      '{"constraintId":"a","level":"iron_law","timestamp":1,"result":"pass"}',
+      '{"constraintId":"b","broken',
+      '{"constraintId":"c","level":"iron_law","timestamp":3,"result":"fail"}',
+    ]);
+    const traces = readProjectTraces(root);
+    expect(traces.map(t => t.constraintId)).toEqual(['a', 'c']);
+  });
+
+  it('缺文件返回空数组', () => {
+    expect(readProjectTraces(root)).toEqual([]);
+  });
+});
+
+describe('坏行计数透传到 report 数据层（harness#100）', () => {
+  const VALID_A = '{"constraintId":"a","level":"iron_law","timestamp":1,"result":"pass"}';
+  const VALID_B = '{"constraintId":"b","level":"iron_law","timestamp":3,"result":"fail"}';
+  const BAD = '{"constraintId":"x","broken';
+  const TRACE_REL = path.join('.harness', 'logs', 'traces.log');
+
+  function projectWith(lines: string[]): string {
+    return createProjectFixture({
+      name: 'usage-report-skiplines',
+      files: { [TRACE_REL]: lines.join('\n') + '\n' },
+    });
+  }
+
+  it.each([
+    [1, [BAD]],
+    [3, [BAD, 'garbage', '{"half"]  }']],
+  ] as Array<[number, string[]]>)(
+    '%i 行坏数据：readProjectTracesReport 计数与 module 计数对账',
+    (expectedSkipped, badLines) => {
+      const lines = [VALID_A, ...badLines, VALID_B];
+      const root = projectWith(lines);
+
+      const report = readProjectTracesReport(root);
+
+      expect(report.skippedLines).toBe(expectedSkipped);
+      expect(report.skippedLines).toBe(
+        readJsonl(path.join(root, TRACE_REL), 'skip').skippedLines
+      );
+      // 兼容签名不变：旧入口仍只返回合法记录数组
+      expect(readProjectTraces(root)).toEqual(report.traces);
+      expect(report.traces.map(t => t.constraintId)).toEqual(['a', 'b']);
+    }
+  );
+
+  it('buildConstraintsUsageReport 报告体带坏行数（与 traceFileExists 同一降级维度）', () => {
+    const root = projectWith([VALID_A, BAD, VALID_B]);
+
+    const report = buildConstraintsUsageReport(root);
+
+    expect(report.skippedLines).toBe(1);
+    expect(report.traceFileExists).toBe(true);
+  });
+
+  it('无损坏时计数为 0（既有输出零噪声的前提）', () => {
+    const report = buildConstraintsUsageReport(projectWith([VALID_A, VALID_B]));
+
+    expect(report.skippedLines).toBe(0);
+    expect(report.traceFileExists).toBe(true);
+  });
+
+  it('缺 trace 文件：计数 0 且 traceFileExists=false', () => {
+    const report = buildConstraintsUsageReport(
+      createProjectFixture({ name: 'usage-report-notracefile' })
+    );
+
+    expect(report.skippedLines).toBe(0);
+    expect(report.traceFileExists).toBe(false);
+  });
+});

package/src/core/constraints/agent-prompt-renderer.ts

@@ -11,8 +11,8 @@
  * （如 docs_freshness）不渲染。
  */
 
-import type { Constraint, ConstraintLevel, ConstraintTrigger } from '../../types/constraint';
-import { normalizeTriggers } from '../../utils/exec';
+import type { ConstraintLevel, ConstraintTrigger } from '../../types/constraint';
+import { matchesTrigger } from '../../utils/exec';
 import { getEffectiveConstraints } from '../effective-constraints';
 
 /**
@@ -65,7 +65,3 @@ export function renderConstraintsByTrigger(
   }
   return lines.join('\n');
 }
-
-function matchesTrigger(constraint: Constraint, requested: ConstraintTrigger[]): boolean {
-  return normalizeTriggers<ConstraintTrigger>(constraint.trigger).some(t => requested.includes(t));
-}

package/src/core/constraints/capabilities-parser.ts

@@ -5,26 +5,18 @@
  * 各持一份正则，收敛到此处。H2 起能力清单计数（checkCapabilityCounts /
  * updateCapabilityCounts）也从 sync-docs/capabilities-syncer 收敛到此，
  * 使本模块成为 CAPABILITIES.md 解析 + 计数唯一入口。
+ *
+ * 计数所需的命令/门禁定义由调用方注入（harness#88：core 不值导入上层定义表）。
  */
 
 import * as fs from 'fs';
 import { IRON_LAWS, GUIDELINES } from './definitions';
-import { COMMAND_DEFINITIONS } from '../../cli/commands/definitions';
-import { GATE_DEFINITIONS } from '../../gates/definitions';
 import { FreshnessRunner } from './doc-freshness/runner';
 import type { DocFreshnessCheck } from '../../types/project-config';
 
-/** CLI 命令数 = 非门禁命令定义 + 门禁命令定义（ADR-0002：定义表是命令形状单一来源） */
-function cliCommandCount(): number {
-  return COMMAND_DEFINITIONS.length + GATE_DEFINITIONS.filter(g => g.cli).length;
-}
-
 /** 匹配表格单元格中的源码文件条目（如 `src/foo.ts`、`foo.tsx`） */
 const FILE_CELL_REGEX = /\|\s*([^|]+?\.(?:ts|tsx|js|jsx))\s*\|/g;
 
-/** 仅匹配表格第二列的文件条目（checker 的历史语义：第一列为模块名，第二列为文件） */
-const FILE_SECOND_COLUMN_REGEX = /^\|[^|]+\|\s*([^|]+?\.(?:ts|tsx|js|jsx))\s*\|/gm;
-
 /**
  * 匹配表格单元格中的目录条目（如 `agents/`）。
  *
@@ -35,26 +27,25 @@ const FILE_SECOND_COLUMN_REGEX = /^\|[^|]+\|\s*([^|]+?\.(?:ts|tsx|js|jsx))\s*\|/
 const DIR_CELL_REGEX = /\|\s*([\w][\w@./-]*\/)\s*\|/g;
 
 export interface CapabilitiesParseOptions {
-  /** 是否同时收集目录条目（sync-docs 需要；checker 只做文件覆盖比对，不需要） */
+  /** 是否同时收集目录条目，默认 false */
   includeDirs?: boolean;
-  /** 只取表格第二列的文件条目（checker 的历史严格语义），默认 false */
-  secondColumnOnly?: boolean;
 }
 
 /**
  * 从 CAPABILITIES.md 内容中提取表格列出的条目
  *
+ * 解析口径（ADR-0009）：表格所有单元格收集；「只看第二列」的历史读法废弃。
+ *
  * @param content markdown 内容
  * @returns 文件路径原样 + （可选）目录条目，按出现顺序去重
  */
 export function parseCapabilitiesEntries(content: string, options: CapabilitiesParseOptions = {}): string[] {
-  const { includeDirs = false, secondColumnOnly = false } = options;
+  const { includeDirs = false } = options;
   const entries: string[] = [];
 
-  const fileRegex = secondColumnOnly ? FILE_SECOND_COLUMN_REGEX : FILE_CELL_REGEX;
   let match: RegExpExecArray | null;
-  fileRegex.lastIndex = 0;
-  while ((match = fileRegex.exec(content)) !== null) {
+  FILE_CELL_REGEX.lastIndex = 0;
+  while ((match = FILE_CELL_REGEX.exec(content)) !== null) {
     const raw = match[1].trim();
     if (!entries.includes(raw)) entries.push(raw);
   }
@@ -111,6 +102,20 @@ export function aggregateToSourceSubdir(root: string, file: string): string {
 
 // ── 能力清单计数 ────────────────────────────────────────────
 
+/**
+ * 调用方注入的定义源（harness#88）
+ *
+ * core 只消费计数所需的最小形状，不 require 命令表：
+ * - commands：非门禁 CLI 命令定义（仅取长度）
+ * - gates：门禁定义（仅取长度与「是否带 cli 元数据」）
+ *
+ * ADR-0002「定义表是命令形状单一来源」不变，只是表的引用方从 core 移到 cli。
+ */
+export interface CapabilityDefinitionSource {
+  commands: readonly unknown[];
+  gates: readonly { cli?: unknown }[];
+}
+
 /**
  * 能力清单统计规则单份定义（ADR-0008：check/write 两方向共用，
  * 此前 label+pattern 在 buildCapabilityChecks 与 updateCapabilityCounts 各写一遍）
@@ -119,31 +124,40 @@ export function aggregateToSourceSubdir(root: string, file: string): string {
  *   write 的替换文本前缀，如 `Quality Gates (6)`）
  * - pattern：同时供 check（doc_regex_count 字符串 pattern，捕获组为文档计数）
  *   与 write（编译为替换 regex）
- * - actual：定义表实际计数（ADR-0002 单一来源）
+ * - actual：实际计数——命令/门禁来自注入源，约束来自 core 自身定义表
  */
 interface CapabilityCountRule {
   label: string;
   pattern: string;
-  actual: () => number;
+  actual: number;
 }
 
-const CAPABILITY_COUNT_RULES: CapabilityCountRule[] = [
-  { label: 'CLI Commands', pattern: 'CLI Commands\\s*\\((\\d+)\\)', actual: cliCommandCount },
-  { label: 'Quality Gates', pattern: 'Quality Gates?\\s*\\((\\d+)\\)', actual: () => GATE_DEFINITIONS.length },
-  { label: 'Iron Laws', pattern: 'Iron Laws?\\s*\\((\\d+)\\)', actual: () => Object.keys(IRON_LAWS).length },
-  { label: 'Guidelines', pattern: 'Guidelines?\\s*\\((\\d+)\\)', actual: () => Object.keys(GUIDELINES).length },
-];
+/**
+ * 能力清单统计规则（CLI Commands 计数 = 非门禁命令数 + 带 cli 元数据的门禁数）
+ */
+function capabilityCountRules(source: CapabilityDefinitionSource): CapabilityCountRule[] {
+  return [
+    {
+      label: 'CLI Commands',
+      pattern: 'CLI Commands\\s*\\((\\d+)\\)',
+      actual: source.commands.length + source.gates.filter(g => g.cli).length,
+    },
+    { label: 'Quality Gates', pattern: 'Quality Gates?\\s*\\((\\d+)\\)', actual: source.gates.length },
+    { label: 'Iron Laws', pattern: 'Iron Laws?\\s*\\((\\d+)\\)', actual: Object.keys(IRON_LAWS).length },
+    { label: 'Guidelines', pattern: 'Guidelines?\\s*\\((\\d+)\\)', actual: Object.keys(GUIDELINES).length },
+  ];
+}
 
 /**
  * 构建 CAPABILITIES.md 能力清单格式的检查配置
  */
-function buildCapabilityChecks(): DocFreshnessCheck[] {
-  return CAPABILITY_COUNT_RULES.map(rule => ({
+function buildCapabilityChecks(source: CapabilityDefinitionSource): DocFreshnessCheck[] {
+  return capabilityCountRules(source).map(rule => ({
     type: 'doc_regex_count' as const,
     doc: 'CAPABILITIES.md',
     label: rule.label,
     pattern: rule.pattern,
-    actual: { kind: 'const_count' as const, value: rule.actual() },
+    actual: { kind: 'const_count' as const, value: rule.actual },
   }));
 }
 
@@ -151,10 +165,11 @@ function buildCapabilityChecks(): DocFreshnessCheck[] {
  * 使用 FreshnessRunner 检查能力清单计数是否与代码一致（--check 模式）
  */
 export function checkCapabilityCounts(
-  projectPath: string
+  projectPath: string,
+  source: CapabilityDefinitionSource
 ): { match: boolean; mismatches: string[] } {
   const runner = new FreshnessRunner();
-  const checks = buildCapabilityChecks();
+  const checks = buildCapabilityChecks(source);
   const results = runner.runAll({ checks }, projectPath);
 
   const mismatches: string[] = [];
@@ -170,14 +185,17 @@ export function checkCapabilityCounts(
 /**
  * 更新 CAPABILITIES.md 中的能力清单计数（write 模式）
  *
- * 命令/门禁计数取自定义表（ADR-0002 单一来源），regex 替换文档计数行；
- * 规则与 check 方向共用 CAPABILITY_COUNT_RULES（ADR-0008）。
+ * 命令/门禁计数取自注入的定义源（ADR-0002 单一来源在调用方），regex 替换文档计数行；
+ * 规则与 check 方向共用 capabilityCountRules（ADR-0008）。
  */
-export function updateCapabilityCounts(content: string, _projectPath: string): string {
-  for (const rule of CAPABILITY_COUNT_RULES) {
+export function updateCapabilityCounts(
+  content: string,
+  source: CapabilityDefinitionSource
+): string {
+  for (const rule of capabilityCountRules(source)) {
     const regex = new RegExp(rule.pattern);
     if (regex.test(content)) {
-      content = content.replace(regex, `${rule.label} (${rule.actual()})`);
+      content = content.replace(regex, `${rule.label} (${rule.actual})`);
     }
   }