@dommaker/harness 0.18.0 → 1.0.0

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

@@ -0,0 +1,129 @@
+/**
+ * trigger 参数化约束分组渲染 API 测试（H6/G6，收编 studio prompt-injection.ts）
+ *
+ * 语义：
+ * - 入参 = 触发条件（单 trigger 或数组），无 role 概念（role→trigger 路由留 studio）
+ * - 数据源 = getEffectiveConstraints（内置 → preset → config.yml 禁用 → custom 追加 → scenes 过滤）
+ * - 输出按层级分组：铁律 → 指导原则 → 行为提示；无 promptInjection 的约束不渲染
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { renderConstraintsByTrigger } from '../agent-prompt-renderer';
+import { renderConstraintsByTrigger as PublicRenderConstraintsByTrigger } from '../../../index';
+
+describe('公开导出（根 barrel）', () => {
+  test('renderConstraintsByTrigger 经 src/index.ts 公开导出', () => {
+    expect(PublicRenderConstraintsByTrigger).toBe(renderConstraintsByTrigger);
+  });
+});
+
+/** 创建临时项目目录，可按相对路径写入 .harness/config.yml 等夹具文件 */
+function makeProject(files: Record<string, string>): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'h6-render-'));
+  for (const [rel, content] of Object.entries(files)) {
+    const target = path.join(dir, rel);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content, 'utf-8');
+  }
+  return dir;
+}
+
+describe('renderConstraintsByTrigger', () => {
+  test('内置约束按层级分组渲染：铁律 → 指导原则 → 行为提示', () => {
+    const projectRoot = makeProject({});
+    const out = renderConstraintsByTrigger('code_implementation', { projectRoot });
+
+    expect(out).toContain('## 行为约束（前置声明）');
+    expect(out).toContain('### 铁律（绝对禁止，无例外）');
+    expect(out).toContain('- **no_completion_without_verification**:');
+    expect(out).toContain('### 指导原则（优先建议）');
+    expect(out).toContain('- **no_hardcoded_credentials**:');
+    expect(out).toContain('### 行为提示');
+    expect(out).toContain('- **no_code_without_test**:');
+
+    // 分组顺序：铁律 < 指导原则 < 行为提示
+    const ironIdx = out.indexOf('### 铁律（绝对禁止，无例外）');
+    const guideIdx = out.indexOf('### 指导原则（优先建议）');
+    const promptIdx = out.indexOf('### 行为提示');
+    expect(ironIdx).toBeGreaterThanOrEqual(0);
+    expect(guideIdx).toBeGreaterThan(ironIdx);
+    expect(promptIdx).toBeGreaterThan(guideIdx);
+  });
+
+  test('无 promptInjection 的约束不渲染（即使 trigger 匹配）', () => {
+    const projectRoot = makeProject({});
+    // docs_freshness / capability_sync / context_doc_sync 无 promptInjection
+    const out = renderConstraintsByTrigger('module_modification', { projectRoot });
+
+    expect(out).not.toContain('- **docs_freshness**:');
+    expect(out).not.toContain('- **capability_sync**:');
+    expect(out).not.toContain('- **context_doc_sync**:');
+  });
+
+  test('支持 trigger 数组入参，仅匹配交集约束', () => {
+    const projectRoot = makeProject({});
+    const out = renderConstraintsByTrigger(['test_creation'], { projectRoot });
+
+    expect(out).toContain('- **no_test_simplification**:');
+    // no_completion_without_verification 的 trigger 为 code_implementation，不匹配
+    expect(out).not.toContain('- **no_completion_without_verification**:');
+  });
+
+  test('无匹配约束返回空字符串', () => {
+    const projectRoot = makeProject({});
+    expect(renderConstraintsByTrigger('nonexistent_trigger_xyz', { projectRoot })).toBe('');
+    expect(renderConstraintsByTrigger([], { projectRoot })).toBe('');
+  });
+
+  test('config.yml 禁用的约束不进入渲染（生效集数据源）', () => {
+    const projectRoot = makeProject({
+      '.harness/config.yml': [
+        'constraints:',
+        '  no_hardcoded_credentials:',
+        '    enabled: false',
+        '',
+      ].join('\n'),
+    });
+    const out = renderConstraintsByTrigger('code_implementation', { projectRoot });
+
+    expect(out).not.toContain('- **no_hardcoded_credentials**:');
+    // 同 trigger 的其它约束仍渲染
+    expect(out).toContain('- **no_completion_without_verification**:');
+  });
+
+  test('custom 约束追加进生效集并参与分组渲染', () => {
+    const projectRoot = makeProject({
+      '.harness/config.yml': [
+        'custom_constraints:',
+        '  my_custom_rule:',
+        '    level: prompt',
+        '    trigger: code_implementation',
+        '    rule: CUSTOM RULE',
+        '    message: 自定义约束消息',
+        '    promptInjection: 自定义行为提示文本',
+        '',
+      ].join('\n'),
+    });
+    const out = renderConstraintsByTrigger('code_implementation', { projectRoot });
+
+    expect(out).toContain('- **my_custom_rule**: 自定义行为提示文本');
+    const promptIdx = out.indexOf('### 行为提示');
+    const customIdx = out.indexOf('- **my_custom_rule**:');
+    expect(customIdx).toBeGreaterThan(promptIdx);
+  });
+
+  test('scenes 过滤：带 appliesTo 的场景专属 prompt 默认不渲染，声明场景后渲染', () => {
+    // no_skill_without_test：appliesTo ['agent-skill']，trigger module_creation
+    const plain = makeProject({});
+    expect(renderConstraintsByTrigger('module_creation', { projectRoot: plain }))
+      .not.toContain('- **no_skill_without_test**:');
+
+    const withScene = makeProject({
+      '.harness/config.yml': 'scenes:\n  - agent-skill\n',
+    });
+    expect(renderConstraintsByTrigger('module_creation', { projectRoot: withScene }))
+      .toContain('- **no_skill_without_test**:');
+  });
+});

package/src/core/constraints/__tests__/check-cache.test.ts

@@ -0,0 +1,227 @@
+/**
+ * CheckCache 测试（H6/G5：TTL 缓存既有行为 + 计数采样扩展）
+ *
+ * 计数采样语义（与 studio runtime/cache.ts 收编对齐）：
+ * - 每个 (namespace, key) 独立计数
+ * - 第 1 次调用必执行（采样轮），此后每 N 次执行 1 次
+ * - 非采样轮：缓存命中（未过期）返回缓存值；未命中/已过期返回 defaultValueOnMiss，不执行 fn
+ */
+
+import { CheckCache } from '../check-cache';
+import { CheckCache as PublicCheckCache } from '../../../index';
+
+describe('公开导出（根 barrel）', () => {
+  test('CheckCache 经 src/index.ts 公开导出', () => {
+    expect(PublicCheckCache).toBe(CheckCache);
+  });
+});
+
+describe('CheckCache', () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+    jest.setSystemTime(new Date('2026-01-01T00:00:00.000Z'));
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  describe('TTL 缓存（既有行为，不传 sampling 参数）', () => {
+    test('缓存命中不重复执行 fn，过期后重新执行', async () => {
+      const cache = new CheckCache({ ttlMs: 1000 });
+      const fn = jest.fn(async () => 'v1');
+
+      expect(await cache.get('ns', 'k', fn)).toBe('v1');
+      expect(await cache.get('ns', 'k', fn)).toBe('v1');
+      expect(fn).toHaveBeenCalledTimes(1);
+
+      jest.advanceTimersByTime(1001);
+      expect(await cache.get('ns', 'k', fn)).toBe('v1');
+      expect(fn).toHaveBeenCalledTimes(2);
+    });
+
+    test('getSync 命中/过期行为一致', () => {
+      const cache = new CheckCache({ ttlMs: 1000 });
+      const fn = jest.fn(() => 'sync');
+
+      expect(cache.getSync('ns', 'k', fn)).toBe('sync');
+      expect(cache.getSync('ns', 'k', fn)).toBe('sync');
+      expect(fn).toHaveBeenCalledTimes(1);
+
+      jest.advanceTimersByTime(1001);
+      expect(cache.getSync('ns', 'k', fn)).toBe('sync');
+      expect(fn).toHaveBeenCalledTimes(2);
+    });
+
+    test('缺省构造使用默认 TTL 5000ms', async () => {
+      const cache = new CheckCache();
+      const fn = jest.fn(async () => 'v');
+
+      await cache.get('ns', 'k', fn);
+      jest.advanceTimersByTime(4999);
+      await cache.get('ns', 'k', fn);
+      expect(fn).toHaveBeenCalledTimes(1);
+
+      jest.advanceTimersByTime(2); // 累计 5001ms，已过期
+      await cache.get('ns', 'k', fn);
+      expect(fn).toHaveBeenCalledTimes(2);
+    });
+
+    test('命名空间隔离：不同 namespace 相同 key 互不影响', async () => {
+      const cache = new CheckCache({ ttlMs: 1000 });
+      const f1 = jest.fn(async () => 'a');
+      const f2 = jest.fn(async () => 'b');
+
+      expect(await cache.get('ns1', 'k', f1)).toBe('a');
+      expect(await cache.get('ns2', 'k', f2)).toBe('b');
+      expect(f1).toHaveBeenCalledTimes(1);
+      expect(f2).toHaveBeenCalledTimes(1);
+    });
+
+    test('invalidate(namespace) 仅清除指定命名空间', async () => {
+      const cache = new CheckCache({ ttlMs: 1000 });
+      const f1 = jest.fn(async () => 'a');
+      const f2 = jest.fn(async () => 'b');
+
+      await cache.get('ns1', 'k', f1);
+      await cache.get('ns2', 'k', f2);
+      cache.invalidate('ns1');
+
+      expect(await cache.get('ns1', 'k', f1)).toBe('a');
+      expect(await cache.get('ns2', 'k', f2)).toBe('b');
+      expect(f1).toHaveBeenCalledTimes(2);
+      expect(f2).toHaveBeenCalledTimes(1);
+    });
+
+    test('invalidate() 清除全部缓存', async () => {
+      const cache = new CheckCache({ ttlMs: 1000 });
+      const fn = jest.fn(async () => 'v');
+
+      await cache.get('ns', 'k1', fn);
+      await cache.get('ns', 'k2', fn);
+      cache.invalidate();
+
+      await cache.get('ns', 'k1', fn);
+      await cache.get('ns', 'k2', fn);
+      expect(fn).toHaveBeenCalledTimes(4);
+    });
+  });
+
+  describe('计数采样（声明式配置）', () => {
+    test('第 1 次调用必执行，此后每 N 次执行 1 次，其余复用缓存结果', async () => {
+      const cache = new CheckCache({ ttlMs: 60_000 });
+      let runs = 0;
+      const fn = jest.fn(async () => `run-${++runs}`);
+      const sampling = { sampleRate: 3, defaultValueOnMiss: 'skip' };
+
+      // 第 1 次：采样轮 → 执行
+      expect(await cache.get('ns', 'k', fn, sampling)).toBe('run-1');
+      // 第 2、3 次：非采样轮 → 复用缓存
+      expect(await cache.get('ns', 'k', fn, sampling)).toBe('run-1');
+      expect(await cache.get('ns', 'k', fn, sampling)).toBe('run-1');
+      expect(fn).toHaveBeenCalledTimes(1);
+      // 第 4 次：采样轮 → 执行
+      expect(await cache.get('ns', 'k', fn, sampling)).toBe('run-2');
+      expect(fn).toHaveBeenCalledTimes(2);
+    });
+
+    test('非采样轮缓存已过期：返回 defaultValueOnMiss，不执行 fn', async () => {
+      const cache = new CheckCache({ ttlMs: 1000 });
+      const fn = jest.fn(async () => 'fresh');
+      const sampling = { sampleRate: 3, defaultValueOnMiss: 'skip' };
+
+      expect(await cache.get('ns', 'k', fn, sampling)).toBe('fresh'); // 采样轮，TTL=1s 缓存
+      jest.advanceTimersByTime(1001);
+
+      expect(await cache.get('ns', 'k', fn, sampling)).toBe('skip'); // 过期 + 非采样轮
+      expect(await cache.get('ns', 'k', fn, sampling)).toBe('skip');
+      expect(fn).toHaveBeenCalledTimes(1);
+
+      // 第 4 次：采样轮 → 重新执行
+      expect(await cache.get('ns', 'k', fn, sampling)).toBe('fresh');
+      expect(fn).toHaveBeenCalledTimes(2);
+    });
+
+    test('采样计数器按 key 独立', async () => {
+      const cache = new CheckCache({ ttlMs: 60_000 });
+      const f1 = jest.fn(async () => 'a');
+      const f2 = jest.fn(async () => 'b');
+      const sampling = { sampleRate: 3, defaultValueOnMiss: 'x' };
+
+      await cache.get('ns', 'k1', f1, sampling);
+      await cache.get('ns', 'k2', f2, sampling);
+      expect(f1).toHaveBeenCalledTimes(1);
+      expect(f2).toHaveBeenCalledTimes(1);
+
+      await cache.get('ns', 'k1', f1, sampling); // k1 非采样轮
+      expect(f1).toHaveBeenCalledTimes(1);
+    });
+
+    test('invalidate 重置计数器：失效后下一次调用恢复为采样轮', async () => {
+      const cache = new CheckCache({ ttlMs: 60_000 });
+      const fn = jest.fn(async () => 'v');
+      const sampling = { sampleRate: 3, defaultValueOnMiss: 'd' };
+
+      await cache.get('ns', 'k', fn, sampling); // count=1 采样
+      await cache.get('ns', 'k', fn, sampling); // count=2 跳过
+      cache.invalidate('ns');
+      await cache.get('ns', 'k', fn, sampling); // 重置后 count=1 采样
+      expect(fn).toHaveBeenCalledTimes(2);
+    });
+
+    test('invalidate() 全量同样重置计数器', async () => {
+      const cache = new CheckCache({ ttlMs: 60_000 });
+      const fn = jest.fn(async () => 'v');
+      const sampling = { sampleRate: 2, defaultValueOnMiss: 'd' };
+
+      await cache.get('ns', 'k', fn, sampling); // count=1 采样
+      cache.invalidate();
+      await cache.get('ns', 'k', fn, sampling); // 重置后 count=1 采样
+      expect(fn).toHaveBeenCalledTimes(2);
+    });
+
+    test('sampleRate <= 1 视为不采样：回退为普通 TTL 缓存语义', async () => {
+      const cache = new CheckCache({ ttlMs: 60_000 });
+      const fn = jest.fn(async () => 'v');
+
+      await cache.get('ns', 'k', fn, { sampleRate: 1, defaultValueOnMiss: 'd' });
+      await cache.get('ns', 'k', fn, { sampleRate: 0, defaultValueOnMiss: 'd' });
+      expect(fn).toHaveBeenCalledTimes(1); // TTL 命中，无采样短路
+    });
+
+    test('getSync 同样支持计数采样', () => {
+      const cache = new CheckCache({ ttlMs: 60_000 });
+      const fn = jest.fn(() => 'sync');
+      const sampling = { sampleRate: 3, defaultValueOnMiss: 'skip' };
+
+      expect(cache.getSync('ns', 'k', fn, sampling)).toBe('sync'); // 采样轮
+      expect(cache.getSync('ns', 'k', fn, sampling)).toBe('sync'); // 复用缓存
+      expect(cache.getSync('ns', 'k', fn, sampling)).toBe('sync'); // 复用缓存
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    test('getSync 非采样轮缓存过期返回默认值', () => {
+      const cache = new CheckCache({ ttlMs: 1000 });
+      const fn = jest.fn(() => 'sync');
+      const sampling = { sampleRate: 3, defaultValueOnMiss: 'skip' };
+
+      expect(cache.getSync('ns', 'k', fn, sampling)).toBe('sync'); // 采样轮 @t0
+      jest.advanceTimersByTime(1001);
+      expect(cache.getSync('ns', 'k', fn, sampling)).toBe('skip'); // 过期 + 非采样轮
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    test('采样轮执行结果以正常 TTL 写入缓存，非采样轮不刷新 TTL', async () => {
+      const cache = new CheckCache({ ttlMs: 1000 });
+      const fn = jest.fn(async () => 'v');
+      const sampling = { sampleRate: 3, defaultValueOnMiss: 'd' };
+
+      await cache.get('ns', 'k', fn, sampling); // 采样轮 @t0
+      jest.advanceTimersByTime(500);
+      await cache.get('ns', 'k', fn, sampling); // 非采样轮 @t0+500（不应刷新过期时间）
+      jest.advanceTimersByTime(600); // t0+1100：若 TTL 被刷新则仍命中
+      expect(await cache.get('ns', 'k', fn, sampling)).toBe('d'); // 已过期 → 默认值
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+  });
+});

package/src/core/constraints/__tests__/interceptor.test.ts

@@ -64,7 +64,6 @@ describe('ConstraintInterceptor', () => {
     mockChecker.getConstraints.mockReturnValue({
       ironLaws: { test_iron_law: mockIronLaw },
       guidelines: { test_guideline: mockGuideline },
-      tips: {},
       prompts: {},
     });
   });
@@ -202,7 +201,6 @@ describe('ConstraintInterceptor', () => {
       mockChecker.getConstraints.mockReturnValue({
         ironLaws: {},
         guidelines: {},
-        tips: {},
         prompts: {},
       });
 

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

@@ -0,0 +1,71 @@
+/**
+ * Agent prompt 约束段渲染（H6/G6：trigger 参数化分组渲染 API）
+ *
+ * 收编 studio prompt-injection.ts 的渲染层：role→trigger 路由留在 studio，
+ * 本模块只做 trigger 参数化 + 生效集过滤 + 层级分组渲染。
+ *
+ * 数据源 = getEffectiveConstraints（内置 → preset → config.yml 禁用 →
+ * custom 追加 → scenes 过滤），与 init 注入、harness check 同一来源。
+ *
+ * 输出按层级分组：铁律 → 指导原则 → 行为提示；无 promptInjection 的约束
+ * （如 docs_freshness）不渲染。
+ */
+
+import type { Constraint, ConstraintLevel, ConstraintTrigger } from '../../types/constraint';
+import { normalizeTriggers } from '../../utils/exec';
+import { getEffectiveConstraints } from '../effective-constraints';
+
+/**
+ * renderConstraintsByTrigger 选项
+ */
+export interface RenderConstraintsByTriggerOptions {
+  /** 项目根路径（决定 config.yml 生效集），缺省 process.cwd() */
+  projectRoot?: string;
+}
+
+/** 层级分组定义（渲染顺序即声明顺序） */
+const LEVEL_GROUPS: ReadonlyArray<{ level: ConstraintLevel; heading: string }> = [
+  { level: 'iron_law', heading: '### 铁律（绝对禁止，无例外）' },
+  { level: 'guideline', heading: '### 指导原则（优先建议）' },
+  { level: 'prompt', heading: '### 行为提示' },
+];
+
+/**
+ * 按触发条件渲染约束分组文本（注入 Agent system prompt 用）
+ *
+ * 过滤：生效集内 trigger 与入参存在交集的约束；无 promptInjection 的不渲染。
+ * 分组：按层级 iron_law → guideline → prompt 顺序渲染为标题 + 条目列表；
+ * 无适用约束时返回空字符串。
+ *
+ * @param triggers 触发条件（单个或多个；空数组返回空字符串）
+ * @param options.projectRoot 项目根路径（决定 config.yml 生效集）
+ */
+export function renderConstraintsByTrigger(
+  triggers: ConstraintTrigger | ConstraintTrigger[],
+  options?: RenderConstraintsByTriggerOptions,
+): string {
+  const requested = Array.isArray(triggers) ? triggers : [triggers];
+  if (requested.length === 0) return '';
+
+  const constraints = getEffectiveConstraints(options?.projectRoot);
+  const applicable = constraints.filter(
+    c => c.promptInjection && matchesTrigger(c, requested)
+  );
+  if (applicable.length === 0) return '';
+
+  const lines: string[] = ['\n## 行为约束（前置声明）\n'];
+  for (const group of LEVEL_GROUPS) {
+    const items = applicable.filter(c => c.level === group.level);
+    if (items.length === 0) continue;
+    lines.push(`${group.heading}\n`);
+    for (const c of items) {
+      lines.push(`- **${c.id}**: ${c.promptInjection}`);
+    }
+    lines.push('');
+  }
+  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

@@ -1,11 +1,16 @@
 /**
- * CAPABILITIES.md 表格解析（工单 19-B）
+ * CAPABILITIES.md 解析与能力清单计数（工单 19-B / H2 O10-R3）
  *
  * 此前 checker.parseCapabilitiesFiles 与 sync-docs.parseCapabilitiesFiles
- * 各持一份正则，收敛到此处。
+ * 各持一份正则，收敛到此处。H2 起能力清单计数（checkCapabilityCounts /
+ * updateCapabilityCounts）也从 sync-docs/capabilities-syncer 收敛到此，
+ * 使本模块成为 CAPABILITIES.md 解析 + 计数唯一入口。
  */
 
 import * as fs from 'fs';
+import { IRON_LAWS, GUIDELINES } from './definitions';
+import { FreshnessRunner } from './doc-freshness/runner';
+import type { DocFreshnessCheck } from '../../types/project-config';
 
 /** 匹配表格单元格中的源码文件条目（如 `src/foo.ts`、`foo.tsx`） */
 const FILE_CELL_REGEX = /\|\s*([^|]+?\.(?:ts|tsx|js|jsx))\s*\|/g;
@@ -96,3 +101,91 @@ export function aggregateToSourceSubdir(root: string, file: string): string {
   if (idx === -1) return prefix;
   return prefix + rest.slice(0, idx) + '/';
 }
+
+// ── 能力清单计数 ────────────────────────────────────────────
+
+/**
+ * 构建 CAPABILITIES.md 能力清单格式的检查配置
+ */
+function buildCapabilityChecks(): DocFreshnessCheck[] {
+  return [
+    {
+      type: 'doc_regex_count',
+      doc: 'CAPABILITIES.md',
+      label: 'CLI Commands',
+      pattern: 'CLI Commands\\s*\\((\\d+)\\)',
+      // index.ts（已删 barrel）与 definitions.ts（命令注册表纯数据）不是命令实现，不计入
+      actual: { kind: 'dir_count', path: 'src/cli/commands', extension: '.ts', exclude: ['index.ts', 'definitions.ts'] },
+    },
+    {
+      type: 'doc_regex_count',
+      doc: 'CAPABILITIES.md',
+      label: 'Quality Gates',
+      pattern: 'Quality Gates?\\s*\\((\\d+)\\)',
+      actual: { kind: 'dir_count', path: 'src/gates', extension: '.ts', exclude: ['index.ts', 'types.ts'] },
+    },
+    {
+      type: 'doc_regex_count',
+      doc: 'CAPABILITIES.md',
+      label: 'Iron Laws',
+      pattern: 'Iron Laws?\\s*\\((\\d+)\\)',
+      actual: { kind: 'const_count', value: Object.keys(IRON_LAWS).length },
+    },
+    {
+      type: 'doc_regex_count',
+      doc: 'CAPABILITIES.md',
+      label: 'Guidelines',
+      pattern: 'Guidelines?\\s*\\((\\d+)\\)',
+      actual: { kind: 'const_count', value: Object.keys(GUIDELINES).length },
+    },
+  ];
+}
+
+/**
+ * 使用 FreshnessRunner 检查能力清单计数是否与代码一致（--check 模式）
+ */
+export function checkCapabilityCounts(
+  projectPath: string
+): { match: boolean; mismatches: string[] } {
+  const runner = new FreshnessRunner();
+  const checks = buildCapabilityChecks();
+  const results = runner.runAll({ checks }, projectPath);
+
+  const mismatches: string[] = [];
+  for (const r of results) {
+    if (!r.pass && r.message) {
+      mismatches.push(r.message);
+    }
+  }
+
+  return { match: mismatches.length === 0, mismatches };
+}
+
+/**
+ * 更新 CAPABILITIES.md 中的能力清单计数（write 模式）
+ *
+ * 使用 FreshnessRunner 获取实际计数，然后 regex 替换文档计数行。
+ */
+export function updateCapabilityCounts(content: string, projectPath: string): string {
+  const runner = new FreshnessRunner();
+
+  const cliCount = runner.countFromDir('src/cli/commands', '.ts', ['index.ts', 'definitions.ts'], projectPath);
+  const gateCount = runner.countFromDir('src/gates', '.ts', ['index.ts', 'types.ts'], projectPath);
+  const ironCount = Object.keys(IRON_LAWS).length;
+  const guideCount = Object.keys(GUIDELINES).length;
+
+  const replacements: [RegExp, string][] = [
+    [/CLI Commands\s*\(\d+\)/, `CLI Commands (${cliCount})`],
+    [/Quality Gates?\s*\(\d+\)/, `Quality Gates (${gateCount})`],
+    [/Iron Laws?\s*\(\d+\)/, `Iron Laws (${ironCount})`],
+    [/Guidelines?\s*\(\d+\)/, `Guidelines (${guideCount})`],
+  ];
+
+  for (const [regex, replacement] of replacements) {
+    if (regex.test(content)) {
+      content = content.replace(regex, replacement);
+    }
+  }
+
+  return content;
+}