@dommaker/harness 0.13.0 → 0.13.2

package/src/cli/commands/sync-docs.ts

@@ -0,0 +1,743 @@
+/**
+ * harness sync-docs 命令
+ *
+ * 自动同步项目文档：CAPABILITIES.md、CONTEXT.md 检查、CHANGELOG 辅助
+ * --check 模式输出结构化信息，供 LLM 或 CI 消费
+ */
+
+import chalk from 'chalk';
+import * as fs from 'fs/promises';
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import { IRON_LAWS, GUIDELINES, TIPS } from '../../core/constraints/definitions';
+import { FreshnessRunner } from '../../core/constraints/doc-freshness/runner';
+import { FreshnessAutoFix } from '../../core/constraints/doc-freshness/auto-fix';
+import { detectSourceRoots } from '../../utils/detect-source-roots';
+import type { DocFreshnessCheck } from '../../types/project-config';
+
+export interface SyncDocsOptions {
+  /** 项目路径 */
+  projectPath?: string;
+  /** 只检查，不写入（CI 模式） */
+  check?: boolean;
+  /** 是否生成 CHANGELOG 条目 */
+  changelog?: boolean;
+  /** 输出 JSON 格式（供 LLM 消费） */
+  json?: boolean;
+}
+
+interface ModuleInfo {
+  name: string;
+  file: string;
+  description: string;
+}
+
+interface SyncResult {
+  added: string[];
+  removed: string[];
+  contextMissing: string[];
+  contextStale: string[];
+}
+
+/**
+ * 同步文档
+ */
+export async function syncDocs(options: SyncDocsOptions): Promise<boolean> {
+  const projectPath = options.projectPath || process.cwd();
+  const isCheck = options.check === true;
+  const isJson = options.json === true;
+
+  if (!isJson) {
+    if (isCheck) {
+      console.log(chalk.blue('🔍 检查文档新鲜度...'));
+    } else {
+      console.log(chalk.blue('📝 同步文档...'));
+    }
+  }
+
+  const result: SyncResult = {
+    added: [],
+    removed: [],
+    contextMissing: [],
+    contextStale: [],
+  };
+
+  // 1. 扫描源码模块（从 governance config 读取目录列表，默认 src/）
+  const srcDirs = await getSourceDirs(projectPath);
+  let currentModules: ModuleInfo[] = [];
+  for (const srcDir of srcDirs) {
+    try {
+      const modules = await scanSourceModules(path.join(projectPath, srcDir), projectPath);
+      currentModules.push(...modules);
+    } catch {
+      if (!isJson) {
+        console.log(chalk.yellow(`⚠️  未找到 ${srcDir} 目录，跳过`));
+      }
+    }
+  }
+
+  // 2. 解析现有 CAPABILITIES.md，检测格式
+  const capabilitiesPath = path.join(projectPath, 'CAPABILITIES.md');
+  let existingFiles: string[] = [];
+  let capsContent = '';
+  let capsIsCapabilityListing = false;
+  try {
+    capsContent = await fs.readFile(capabilitiesPath, 'utf-8');
+    if (isCapabilityListingFormat(capsContent)) {
+      capsIsCapabilityListing = true;
+    } else {
+      existingFiles = await parseCapabilitiesFiles(capabilitiesPath);
+    }
+  } catch {
+    // CAPABILITIES.md 不存在，将创建
+  }
+
+  // 3. 对比差异（分两种格式）
+  let capCountMismatches: string[] = [];
+
+  if (capsIsCapabilityListing) {
+    // 能力清单格式：委托 FreshnessRunner 对比计数
+    const countCheck = checkCapabilityCounts(projectPath);
+    capCountMismatches = countCheck.mismatches;
+    // 不填充 result.added/removed（文件级对比不适用于此格式）
+  } else {
+    // 传统的文件表格格式
+    const getBasename = (f: string) => {
+      const clean = f.endsWith('/') ? f.slice(0, -1) : f;
+      return clean.split('/').pop()!;
+    };
+    const currentBasenames = currentModules.map(m => getBasename(m.file));
+    result.added = currentBasenames.filter(f => !existingFiles.includes(f));
+    result.removed = existingFiles.filter(f => !currentBasenames.includes(f));
+  }
+
+  // 4. 检查 CONTEXT.md（缺失 + 过时）
+  // 4a. 配置中要求的目录：检查缺失
+  const contextDirs = await getRequiredContextDirs(projectPath);
+  for (const dir of contextDirs) {
+    const contextPath = path.join(projectPath, dir, 'CONTEXT.md');
+    try {
+      await fs.access(contextPath);
+    } catch {
+      result.contextMissing.push(dir);
+    }
+  }
+
+  // 4b. 自动发现已有的 CONTEXT.md：检查过时
+  const existingContextFiles = await findExistingContextFiles(projectPath, srcDirs);
+  for (const dir of existingContextFiles) {
+    const contextPath = path.join(projectPath, dir, 'CONTEXT.md');
+    try {
+      const contextStat = await fs.stat(contextPath);
+      const dirPath = path.join(projectPath, dir);
+      const latestTsMtime = await getLatestTsMtime(dirPath);
+      if (latestTsMtime && latestTsMtime > contextStat.mtimeMs) {
+        result.contextStale.push(dir);
+      }
+    } catch {
+      // 目录不存在或无法访问，跳过
+    }
+  }
+
+  const hasTableIssues = result.added.length > 0 || result.removed.length > 0;
+  const hasCapIssues = capCountMismatches.length > 0;
+  const hasContextIssues = result.contextMissing.length > 0 || result.contextStale.length > 0;
+  const hasIssues = hasTableIssues || hasCapIssues || hasContextIssues;
+
+  // 5. JSON 输出模式：结构化输出供 LLM 消费
+  if (isJson) {
+    const jsonOutput: Record<string, unknown> = {
+      stale: hasIssues,
+      format: capsIsCapabilityListing ? 'capability-listing' : 'file-table',
+      summary: {
+        added: result.added.length,
+        removed: result.removed.length,
+        capCountMismatches: capCountMismatches.length,
+        contextMissing: result.contextMissing.length,
+        contextStale: result.contextStale.length,
+      },
+      contextMissing: result.contextMissing.map(d => ({
+        dir: d,
+        file: `${d}/CONTEXT.md`,
+      })),
+      contextStale: result.contextStale.map(d => ({
+        dir: d,
+        file: `${d}/CONTEXT.md`,
+      })),
+      resolution: [] as Array<Record<string, unknown>>,
+    };
+
+    if (capsIsCapabilityListing && hasCapIssues) {
+      jsonOutput.capCountMismatches = capCountMismatches.map(m => ({ mismatch: m }));
+      (jsonOutput.resolution as Array<Record<string, unknown>>).push({
+        action: 'sync-capability-counts',
+        command: 'harness sync-docs',
+        details: 'CAPABILITIES.md 计数与代码不一致，运行 harness sync-docs 自动更新',
+      });
+    }
+
+    if (!capsIsCapabilityListing && hasTableIssues) {
+      jsonOutput.added = result.added.map(f => {
+        const getBasenameLocal = (s: string) => s.split('/').pop()!;
+        return {
+          file: f,
+          module: currentModules.find(m => getBasenameLocal(m.file) === f),
+        };
+      });
+      jsonOutput.removed = result.removed.map(f => ({ file: f }));
+      (jsonOutput.resolution as Array<Record<string, unknown>>).push({
+        action: 'sync-capabilities',
+        command: 'harness sync-docs',
+      });
+    }
+
+    if (hasContextIssues) {
+      (jsonOutput.resolution as Array<Record<string, unknown>>).push(
+        ...(result.contextMissing.length > 0
+          ? [{ action: 'create-context-md', command: 'harness sync-docs', dirs: result.contextMissing }]
+          : []),
+        ...(result.contextStale.length > 0
+          ? [{ action: 'update-context-md', command: 'harness sync-docs', dirs: result.contextStale }]
+          : []),
+      );
+    }
+
+    console.log(JSON.stringify(jsonOutput, null, 2));
+    return !hasIssues;
+  }
+
+  // 6. 人读输出模式
+  if (capsIsCapabilityListing && hasCapIssues) {
+    console.log(chalk.yellow(`\n📊 CAPABILITIES.md 计数不一致:`));
+    capCountMismatches.forEach(m => console.log(chalk.gray(`  - ${m}`)));
+  }
+
+  if (result.added.length > 0) {
+    console.log(chalk.yellow(`\n📄 CAPABILITIES.md 缺少以下模块:`));
+    result.added.forEach(f => console.log(chalk.gray(`  + ${f}`)));
+  }
+
+  if (result.removed.length > 0) {
+    console.log(chalk.yellow(`\n📄 CAPABILITIES.md 包含已删除的模块:`));
+    result.removed.forEach(f => console.log(chalk.gray(`  - ${f}`)));
+  }
+
+  if (result.contextMissing.length > 0) {
+    console.log(chalk.yellow(`\n📋 缺少 CONTEXT.md:`));
+    result.contextMissing.forEach(d => console.log(chalk.gray(`  - ${d}/CONTEXT.md`)));
+  }
+
+  if (result.contextStale.length > 0) {
+    console.log(chalk.yellow(`\n📋 CONTEXT.md 可能过时（源码比文档新）:`));
+    result.contextStale.forEach(d => console.log(chalk.gray(`  - ${d}/CONTEXT.md`)));
+  }
+
+  if (!hasIssues) {
+    console.log(chalk.green('✅ 所有文档都是最新的'));
+    return true;
+  }
+
+  // 7. 检查模式：只报告，不修改
+  if (isCheck) {
+    console.log(chalk.red('\n❌ 文档不是最新的，请运行 harness sync-docs 更新'));
+    return false;
+  }
+
+  // 8. 写入模式：更新文档
+  if (capsIsCapabilityListing && hasCapIssues) {
+    capsContent = updateCapabilityCounts(capsContent, projectPath);
+    await fs.writeFile(capabilitiesPath, capsContent, 'utf-8');
+    console.log(chalk.green(`\n✅ 已更新 CAPABILITIES.md 计数`));
+  }
+
+  if (!capsIsCapabilityListing && hasTableIssues) {
+    await updateCapabilitiesFile(capabilitiesPath, currentModules, existingFiles, result);
+    console.log(chalk.green(`\n✅ 已更新 CAPABILITIES.md`));
+  }
+
+  for (const dir of result.contextMissing) {
+    await createContextMd(projectPath, dir);
+    console.log(chalk.green(`✅ 已创建 ${dir}/CONTEXT.md`));
+  }
+
+  return !hasIssues;
+}
+
+/**
+ * 扫描源码目录，提取模块信息
+ */
+async function scanSourceModules(srcDir: string, projectPath: string): Promise<ModuleInfo[]> {
+  const modules: ModuleInfo[] = [];
+
+  let entries: string[];
+  try {
+    entries = await fs.readdir(srcDir);
+  } catch {
+    return [];
+  }
+
+  for (const entry of entries) {
+    // 跳过测试目录和非源码目录
+    if (entry === '__tests__' || entry === 'node_modules' || entry === 'dist') continue;
+
+    const entryPath = path.join(srcDir, entry);
+    const stat = await fs.stat(entryPath);
+
+    if (stat.isDirectory()) {
+      // 子目录：递归扫描 .ts 文件（不报告目录条目本身）
+      const subFiles = await findTsFiles(entryPath);
+      for (const f of subFiles) {
+        modules.push({
+          name: path.basename(f, '.ts'),
+          file: path.relative(projectPath, f),
+          description: await extractFileDescription(f),
+        });
+      }
+    } else if (entry.endsWith('.ts') && !entry.endsWith('.d.ts') && entry !== 'index.ts') {
+      modules.push({
+        name: path.basename(entry, '.ts'),
+        file: path.relative(projectPath, entryPath),
+        description: await extractFileDescription(entryPath),
+      });
+    }
+  }
+
+  return modules;
+}
+
+/**
+ * 递归查找 .ts 文件
+ */
+async function findTsFiles(dir: string): Promise<string[]> {
+  const results: string[] = [];
+  let entries: string[];
+  try {
+    entries = await fs.readdir(dir);
+  } catch {
+    return [];
+  }
+
+  for (const entry of entries) {
+    if (entry === 'node_modules' || entry === '__tests__' || entry === 'dist') continue;
+    if (entry === 'index.ts') continue; // barrel export
+    const entryPath = path.join(dir, entry);
+    const stat = await fs.stat(entryPath);
+    if (stat.isDirectory()) {
+      results.push(...await findTsFiles(entryPath));
+    } else if (entry.endsWith('.ts') && !entry.endsWith('.d.ts')) {
+      results.push(entryPath);
+    }
+  }
+  return results;
+}
+
+/**
+ * 从文件提取描述
+ */
+async function extractFileDescription(filePath: string): Promise<string> {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return extractFirstComment(content) || path.basename(filePath, '.ts');
+  } catch {
+    return path.basename(filePath, '.ts');
+  }
+}
+
+/**
+ * 提取文件第一行注释
+ */
+function extractFirstComment(content: string): string | null {
+  // 匹配 /** ... */ 或 // ...
+  const jsdocMatch = content.match(/\/\*\*\s*\n\s*\*\s*(.+?)\s*\n/);
+  if (jsdocMatch) return jsdocMatch[1];
+
+  const lineMatch = content.match(/^\/\/\s*(.+)$/m);
+  if (lineMatch) return lineMatch[1];
+
+  return null;
+}
+
+/**
+ * 解析 CAPABILITIES.md 中的文件路径
+ *
+ * 提取所有表格行中提到的 .ts/.tsx/.js/.jsx 文件名（不含路径前缀）
+ * 用于模糊匹配：只要文档中提到了该文件名就算已记录
+ */
+async function parseCapabilitiesFiles(capabilitiesPath: string): Promise<string[]> {
+  const content = await fs.readFile(capabilitiesPath, 'utf-8');
+  const files: string[] = [];
+  // 匹配表格行中的文件名（可能带路径前缀）
+  const tableRowRegex = /\|\s*([^|]+?\.(?:ts|tsx|js|jsx))\s*\|/g;
+  let match;
+  while ((match = tableRowRegex.exec(content)) !== null) {
+    const raw = match[1].trim();
+    // 提取基础文件名（如 core/constraints/definitions.ts → definitions.ts）
+    const basename = raw.split('/').pop()!;
+    if (!files.includes(basename)) {
+      files.push(basename);
+    }
+  }
+  // 也匹配目录条目（如 agents/、gates/）
+  const dirRegex = /\|\s*([^|]+?\/)\s*\|/g;
+  while ((match = dirRegex.exec(content)) !== null) {
+    const dir = match[1].trim();
+    if (!files.includes(dir)) {
+      files.push(dir);
+    }
+  }
+  return files;
+}
+
+/**
+ * 自动发现已有 CONTEXT.md 文件的目录（相对于 projectPath）
+ */
+async function findExistingContextFiles(projectPath: string, srcDirs: string[]): Promise<string[]> {
+  const dirs: string[] = [];
+
+  async function scan(dir: string): Promise<void> {
+    let entries: string[];
+    try {
+      entries = await fs.readdir(dir);
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry === 'node_modules' || entry === '__tests__' || entry === 'dist') continue;
+      const entryPath = path.join(dir, entry);
+      const stat = await fs.stat(entryPath);
+      if (stat.isDirectory()) {
+        // 检查该目录是否有 CONTEXT.md
+        try {
+          await fs.access(path.join(entryPath, 'CONTEXT.md'));
+          dirs.push(path.relative(projectPath, entryPath));
+        } catch {
+          // 没有，继续递归
+        }
+        await scan(entryPath);
+      }
+    }
+  }
+
+  for (const srcDir of srcDirs) {
+    await scan(path.join(projectPath, srcDir));
+  }
+  return dirs;
+}
+
+/**
+ * 获取目录下最新 .ts 文件的修改时间
+ * 返回 null 如果目录不存在或没有 .ts 文件
+ */
+async function getLatestTsMtime(dirPath: string): Promise<number | null> {
+  let latest: number | null = null;
+
+  async function scan(dir: string): Promise<void> {
+    let entries: string[];
+    try {
+      entries = await fs.readdir(dir);
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry === 'node_modules' || entry === '__tests__' || entry === 'dist') continue;
+      const entryPath = path.join(dir, entry);
+      const stat = await fs.stat(entryPath);
+      if (stat.isDirectory()) {
+        await scan(entryPath);
+      } else if (entry.endsWith('.ts') && !entry.endsWith('.d.ts')) {
+        if (latest === null || stat.mtimeMs > latest) {
+          latest = stat.mtimeMs;
+        }
+      }
+    }
+  }
+
+  await scan(dirPath);
+  return latest;
+}
+
+/**
+ * 获取需要 CONTEXT.md 的目录列表
+ */
+async function getRequiredContextDirs(projectPath: string): Promise<string[]> {
+  const configPath = path.join(projectPath, '.harness', 'config.yml');
+  try {
+    const content = await fs.readFile(configPath, 'utf-8');
+    const config = yaml.load(content) as Record<string, unknown>;
+    const governance = config.governance as Record<string, unknown> | undefined;
+    const contextFiles = governance?.context_files as Record<string, unknown> | undefined;
+    if (contextFiles?.enabled) {
+      if (Array.isArray(contextFiles.required_dirs) && contextFiles.required_dirs.length > 0) {
+        return contextFiles.required_dirs as string[];
+      }
+      // Fallback: auto-discover from source roots
+      return detectSourceRoots(projectPath);
+    }
+  } catch {
+    // 配置不存在或无法解析
+  }
+  return [];
+}
+
+/**
+ * 获取源码扫描目录列表
+ * 优先从 governance.context_files.required_dirs 读取，默认 ['src']
+ */
+async function getSourceDirs(projectPath: string): Promise<string[]> {
+  const requiredDirs = await getRequiredContextDirs(projectPath);
+  if (requiredDirs.length > 0) return requiredDirs;
+  return detectSourceRoots(projectPath);
+}
+
+/**
+ * 更新 CAPABILITIES.md 文件
+ */
+async function updateCapabilitiesFile(
+  capabilitiesPath: string,
+  currentModules: ModuleInfo[],
+  existingFiles: string[],
+  result: SyncResult,
+): Promise<void> {
+  let content: string;
+  try {
+    content = await fs.readFile(capabilitiesPath, 'utf-8');
+  } catch {
+    // 文件不存在，创建新的
+    content = generateCapabilitiesContent(currentModules);
+    await fs.writeFile(capabilitiesPath, content, 'utf-8');
+    return;
+  }
+
+  // 如果有表格行，更新表格
+  if (existingFiles.length > 0) {
+    // 移除已删除文件的行
+    for (const removed of result.removed) {
+      const escapedFile = removed.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const rowRegex = new RegExp(`^\\|[^|]*\\|\\s*${escapedFile}\\s*\\|.*$`, 'gm');
+      content = content.replace(rowRegex, '');
+    }
+
+    // 添加新文件的行（在最后一个表格行之后）
+    if (result.added.length > 0) {
+      const getBasenameLocal = (f: string) => f.split('/').pop()!;
+      const addedModules = currentModules.filter(m => result.added.includes(getBasenameLocal(m.file)));
+      const tableEndRegex = /(^\|[^|]+\|[^|]+\|[^|]+\|\s*$)/gm;
+      let lastTableRow = '';
+      let match;
+      while ((match = tableEndRegex.exec(content)) !== null) {
+        lastTableRow = match[0];
+      }
+
+      if (lastTableRow) {
+        const newRows = addedModules.map(m =>
+          `| ${m.name} | ${m.file} | ${m.description} |`
+        ).join('\n');
+        content = content.replace(lastTableRow, lastTableRow + '\n' + newRows);
+      }
+    }
+
+    // 清理多余空行
+    content = content.replace(/\n{3,}/g, '\n\n');
+  } else {
+    // 没有表格，追加模块表格
+    content += '\n\n' + generateModuleTable(currentModules);
+  }
+
+  // 更新最后更新时间
+  const now = new Date().toISOString().split('T')[0];
+  content = content.replace(
+    /最后更新[:：].*/,
+    `最后更新: ${now}`
+  );
+
+  await fs.writeFile(capabilitiesPath, content, 'utf-8');
+}
+
+/**
+ * 生成 CAPABILITIES.md 内容
+ */
+function generateCapabilitiesContent(modules: ModuleInfo[]): string {
+  const now = new Date().toISOString().split('T')[0];
+  return `# CAPABILITIES.md
+
+> 最后更新: ${now}
+
+---
+
+${generateModuleTable(modules)}
+`;
+}
+
+/**
+ * 生成模块表格
+ */
+function generateModuleTable(modules: ModuleInfo[]): string {
+  if (modules.length === 0) return '';
+
+  const rows = modules.map(m =>
+    `| ${m.name} | ${m.file} | ${m.description} |`
+  ).join('\n');
+
+  return `| 模块 | 文件 | 说明 |\n|------|------|------|\n${rows}`;
+}
+
+/**
+ * 创建 CONTEXT.md 模板
+ */
+async function createContextMd(projectPath: string, dir: string): Promise<void> {
+  const contextPath = path.join(projectPath, dir, 'CONTEXT.md');
+  const dirName = path.basename(dir);
+
+  const content = `# ${dirName}
+
+> 此文件描述 ${dir} 目录的职责和上下文。
+> 请阅读本目录的源代码，然后填写以下各节。
+> 如果使用 AI 编码助手，将本文件内容作为 prompt 请求它分析并填写。
+
+## 职责
+
+本目录的核心职责是？
+
+## 核心导出
+
+本目录对外暴露的主要模块/函数：
+
+## 依赖关系
+
+本目录依赖哪些其他模块，谁依赖本目录？
+
+## 注意事项
+
+开发时需要注意的约束或约定：
+`;
+
+  await fs.mkdir(path.join(projectPath, dir), { recursive: true });
+  await fs.writeFile(contextPath, content, 'utf-8');
+}
+
+// ========================================
+// 能力清单格式支持 (capability-listing)
+// ========================================
+
+/**
+ * 检测 CAPABILITIES.md 是否使用能力清单格式（计数行），而非文件表格格式
+ */
+function isCapabilityListingFormat(content: string): boolean {
+  // 能力清单格式特征：包含 "CLI Commands (N)" / "Iron Laws (N)" 等计数行
+  return /CLI Commands\s*\(\d+\)/.test(content) ||
+    /Iron Laws?\s*\(\d+\)/.test(content) ||
+    /Guidelines?\s*\(\d+\)/.test(content);
+}
+
+/**
+ * 从文件表格格式中提取文件路径
+ */
+function extractTableFiles(content: string): string[] {
+  const files: string[] = [];
+  const tableRowRegex = /\|\s*([^|]+?\.(?:ts|tsx|js|jsx))\s*\|/g;
+  let match;
+  while ((match = tableRowRegex.exec(content)) !== null) {
+    const raw = match[1].trim();
+    const basename = raw.split('/').pop()!;
+    if (!files.includes(basename)) {
+      files.push(basename);
+    }
+  }
+  return files;
+}
+
+/**
+ * 构建 CAPABILITIES.md 能力清单格式的检查配置
+ */
+function buildCapabilityChecks(): DocFreshnessCheck[] {
+  return [
+    {
+      type: 'doc_regex_count',
+      doc: 'CAPABILITIES.md',
+      label: 'CLI Commands',
+      pattern: 'CLI Commands\\s*\\((\\d+)\\)',
+      actual: { kind: 'dir_count', path: 'src/cli/commands', extension: '.ts', exclude: ['index.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 },
+    },
+    {
+      type: 'doc_regex_count',
+      doc: 'CAPABILITIES.md',
+      label: 'Tips',
+      pattern: 'Tips?\\s*\\((\\d+)\\)',
+      actual: { kind: 'const_count', value: Object.keys(TIPS).length },
+    },
+  ];
+}
+
+/**
+ * 使用 FreshnessRunner 检查能力清单计数是否与代码一致（--check 模式）
+ */
+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 替换文档计数行。
+ */
+function updateCapabilityCounts(content: string, projectPath: string): string {
+  const runner = new FreshnessRunner();
+
+  const cliCount = runner.countFromDir('src/cli/commands', '.ts', ['index.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 tipsCount = Object.keys(TIPS).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})`],
+    [/Tips?\s*\(\d+\)/, `Tips (${tipsCount})`],
+  ];
+
+  for (const [regex, replacement] of replacements) {
+    if (regex.test(content)) {
+      content = content.replace(regex, replacement);
+    }
+  }
+
+  return content;
+}
+