@dommaker/harness 0.16.8 → 0.17.0

package/src/cli/commands/init.ts

@@ -11,7 +11,12 @@ import * as path from 'path';
 import * as yaml from 'js-yaml';
 import { createExampleCheckpoint, createExampleResolutions } from './validate';
 import { detectSourceRoots } from '../../utils/detect-source-roots';
-import { IRON_LAWS, GUIDELINES, TIPS } from '../../core/constraints/definitions';
+import { getEffectiveConstraints } from '../../core/effective-constraints';
+import {
+  CONSTRAINTS_START_MARKER,
+  CONSTRAINTS_END_MARKER,
+  renderConstraintsSection,
+} from '../../core/constraints/injection-renderer';
 
 export interface InitOptions {
   /** 项目路径 */
@@ -507,18 +512,15 @@ custom_constraints:
 }
 
 /**
- * 在 CLAUDE.md 中写入/更新 Governance Rules 约束段
- *
- * - 如果 CLAUDE.md 不存在，创建并写入完整约束段
- * - 如果存在 HARNESS_CONSTRAINTS_START/END 标记，替换标记间内容
- * - 如果不存在标记，在文件末尾追加约束段
- *
-/**
- * 在 CLAUDE.md 顶部写入 Output Style 段（仅首次创建，后续不覆盖）
+ * Output Style 段标记（ADR-0001：init 只写标记区间内，标记外只读）
  */
-const OUTPUT_STYLE_SECTION = [
-  '## Output Style',
-  '',
+const OUTPUT_STYLE_START = '<!-- HARNESS_OUTPUT_STYLE_START -->';
+const OUTPUT_STYLE_END = '<!-- HARNESS_OUTPUT_STYLE_END -->';
+
+/** 旧版 harness 无标记 Output Style 段的特征串（用于区分 harness 写入 vs 用户自写） */
+const LEGACY_OUTPUT_STYLE_FINGERPRINT = 'Terse like caveman';
+
+const OUTPUT_STYLE_BODY = [
   'Terse like caveman. Technical substance exact. Only fluff die.',
   'Drop: articles, filler (just/really/basically), pleasantries (sure/certainly/happy to), hedging.',
   'Fragments OK. Short synonyms. Code blocks unchanged. Error messages quoted exact.',
@@ -527,25 +529,87 @@ const OUTPUT_STYLE_SECTION = [
   'Read existing files before writing. Don\'t re-read unless changed.',
   'Skip files over 100KB unless required.',
   'Don\'t guess APIs, versions, flags, commit SHAs, or package names. Verify before asserting.',
-  '',
 ].join('\n');
 
-async function setupClaudeMdOutputStyle(projectPath: string): Promise<void> {
+/** 渲染带标记的 Output Style 段（含 `## Output Style` 标题，以换行结尾） */
+function renderOutputStyleSection(): string {
+  return `${OUTPUT_STYLE_START}\n## Output Style\n\n${OUTPUT_STYLE_BODY}\n${OUTPUT_STYLE_END}\n`;
+}
+
+/**
+ * 在 CLAUDE.md 顶部写入 Output Style 段（标记化、幂等）
+ *
+ * - 已有 HARNESS_OUTPUT_STYLE 标记：替换标记间内容
+ * - 无标记但存在旧版 harness 写入的无标记段（特征串匹配）：原位置换为标记版
+ * - 无标记且 `## Output Style` 段为用户自写（特征串不匹配）：跳过并提示，不重复追加
+ * - 完全没有该段：在文件顶部插入标记版
+ */
+export async function setupClaudeMdOutputStyle(projectPath: string): Promise<void> {
   const claudeMdPath = path.join(projectPath, 'CLAUDE.md');
+  let content: string;
   try {
-    const content = await fs.readFile(claudeMdPath, 'utf-8');
-    if (content.includes('## Output Style')) return; // 已存在，不覆盖
-    const newContent = OUTPUT_STYLE_SECTION + '\n' + content;
-    await fs.writeFile(claudeMdPath, newContent, 'utf-8');
+    content = await fs.readFile(claudeMdPath, 'utf-8');
   } catch {
     // CLAUDE.md 不存在——setupClaudeMdConstraints 会创建它
+    return;
+  }
+
+  const section = renderOutputStyleSection();
+  const startIdx = content.indexOf(OUTPUT_STYLE_START);
+  const endIdx = content.indexOf(OUTPUT_STYLE_END);
+
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    // 替换标记间内容（标记本身也替换，保持最新文本）。
+    // 尾部换行规范化：标记后恰好保留一个换行分隔，保证重复运行幂等。
+    const after = content.slice(endIdx + OUTPUT_STYLE_END.length).replace(/^\n+/, '');
+    const newContent = content.slice(0, startIdx) + section + (after ? '\n' + after : '');
+    if (newContent !== content) {
+      await fs.writeFile(claudeMdPath, newContent, 'utf-8');
+      console.log(chalk.green('✅ 已更新 CLAUDE.md Output Style 段'));
+    }
+    return;
+  }
+
+  // 检测旧版无标记 `## Output Style` 段
+  const legacyMatch = /^## Output Style[ \t]*$/m.exec(content);
+  if (legacyMatch) {
+    const sectionStart = legacyMatch.index;
+    const afterHeading = sectionStart + legacyMatch[0].length;
+    const nextHeadingOffset = content.slice(afterHeading).search(/^#{1,6} /m);
+    const sectionEnd = nextHeadingOffset === -1 ? content.length : afterHeading + nextHeadingOffset;
+    const legacySection = content.slice(sectionStart, sectionEnd);
+
+    if (!legacySection.includes(LEGACY_OUTPUT_STYLE_FINGERPRINT)) {
+      // 用户自写的同名 section：不动，也不追加（避免重复）
+      console.log(chalk.yellow('⚠️  CLAUDE.md 已存在自定义 "## Output Style" 段，跳过 harness Output Style 注入'));
+      return;
+    }
+
+    // 旧版 harness 写入：原位置换为标记版
+    const before = content.slice(0, sectionStart);
+    const after = content.slice(sectionEnd);
+    const newContent = before + section + (after.length > 0 ? '\n' + after : '');
+    await fs.writeFile(claudeMdPath, newContent, 'utf-8');
+    console.log(chalk.green('✅ 已将 CLAUDE.md Output Style 段迁移为标记化管理'));
+    return;
   }
+
+  // 完全没有该段：插入文件顶部
+  await fs.writeFile(claudeMdPath, section + '\n' + content, 'utf-8');
+  console.log(chalk.green('✅ 已在 CLAUDE.md 顶部写入 Output Style 段'));
 }
 
 /**
- * 只写入包含 promptInjection 文本的约束
+ * 在 CLAUDE.md 中写入/更新 Governance Rules 约束段
+ *
+ * - 约束集来自 getEffectiveConstraints（ADR-0001）：preset 裁剪、config.yml
+ *   禁用、custom 追加、scenes 过滤全部反映在注入文本里
+ * - 期望段文本由纯函数 renderConstraintsSection 渲染（P6 漂移校验复用）
+ * - 如果 CLAUDE.md 不存在，创建并写入完整约束段
+ * - 如果存在 HARNESS_CONSTRAINTS_START/END 标记，替换标记间内容
+ * - 如果不存在标记，在文件末尾追加约束段
  */
-async function setupClaudeMdConstraints(projectPath: string): Promise<void> {
+export async function setupClaudeMdConstraints(projectPath: string): Promise<void> {
   const claudeMdPath = path.join(projectPath, 'CLAUDE.md');
 
   // 读取 harness 版本
@@ -558,44 +622,10 @@ async function setupClaudeMdConstraints(projectPath: string): Promise<void> {
     // fallback to 'unknown'
   }
 
-  // 构建约束段正文（不含 ## Governance Rules 标题，因为替换时标题已在外部）
-  const bodyLines: string[] = [];
-  bodyLines.push('<!-- HARNESS_CONSTRAINTS_START -->');
-  bodyLines.push(`<!-- version: ${version} -->`);
-
-  // Iron Laws
-  const ironLawItems = Object.entries(IRON_LAWS).filter(([, c]) => c.promptInjection);
-  if (ironLawItems.length > 0) {
-    bodyLines.push('### Iron Laws (违反将阻断)');
-    for (const [id, c] of ironLawItems) {
-      bodyLines.push(`- **${id}**: ${c.promptInjection}`);
-    }
-  }
-
-  // Guidelines
-  const guidelineItems = Object.entries(GUIDELINES).filter(([, c]) => c.promptInjection);
-  if (guidelineItems.length > 0) {
-    bodyLines.push('');
-    bodyLines.push('### Guidelines (应遵循)');
-    for (const [id, c] of guidelineItems) {
-      bodyLines.push(`- **${id}**: ${c.promptInjection}`);
-    }
-  }
-
-  // Tips
-  const tipItems = Object.entries(TIPS).filter(([, c]) => c.promptInjection);
-  if (tipItems.length > 0) {
-    bodyLines.push('');
-    bodyLines.push('### Tips');
-    for (const [id, c] of tipItems) {
-      bodyLines.push(`- **${id}**: ${c.promptInjection}`);
-    }
-  }
-
-  bodyLines.push('<!-- HARNESS_CONSTRAINTS_END -->');
-
-  const fullSection = '## Governance Rules\n' + bodyLines.join('\n') + '\n';
-  const bodyOnly = bodyLines.join('\n') + '\n';
+  // 生效约束集 → 渲染期望段（纯函数，与写文件分离）
+  const constraints = getEffectiveConstraints(projectPath);
+  const bodyOnly = renderConstraintsSection(constraints, version);
+  const fullSection = '## Governance Rules\n' + bodyOnly;
 
   // 检查 CLAUDE.md 是否存在
   let existingContent: string;
@@ -607,9 +637,6 @@ async function setupClaudeMdConstraints(projectPath: string): Promise<void> {
     existingContent = '';
   }
 
-  const startMarker = '<!-- HARNESS_CONSTRAINTS_START -->';
-  const endMarker = '<!-- HARNESS_CONSTRAINTS_END -->';
-
   if (!fileExists) {
     // 创建新文件
     await fs.writeFile(claudeMdPath, fullSection, 'utf-8');
@@ -617,14 +644,15 @@ async function setupClaudeMdConstraints(projectPath: string): Promise<void> {
     return;
   }
 
-  const startIdx = existingContent.indexOf(startMarker);
-  const endIdx = existingContent.indexOf(endMarker);
+  const startIdx = existingContent.indexOf(CONSTRAINTS_START_MARKER);
+  const endIdx = existingContent.indexOf(CONSTRAINTS_END_MARKER);
 
   if (startIdx !== -1 && endIdx !== -1) {
-    // 替换标记间内容（标记本身也替换，保持包括最新版本号）
+    // 替换标记间内容（标记本身也替换，保持包括最新版本号）。
+    // 尾部换行规范化：标记后恰好保留一个换行分隔，保证重复运行幂等。
     const before = existingContent.slice(0, startIdx);
-    const after = existingContent.slice(endIdx + endMarker.length);
-    const newContent = before + bodyOnly + after;
+    const after = existingContent.slice(endIdx + CONSTRAINTS_END_MARKER.length).replace(/^\n+/, '');
+    const newContent = before + bodyOnly + (after ? '\n' + after : '');
     await fs.writeFile(claudeMdPath, newContent, 'utf-8');
     console.log(chalk.green(`✅ 已更新 CLAUDE.md 治理约束 (v${version})`));
   } else {

package/src/cli/commands/report.ts

@@ -8,7 +8,7 @@ import chalk from 'chalk';
 import * as fs from 'fs/promises';
 import { ConstraintChecker } from '../../core/constraints/checker';
 import { getTraceCollector } from '../../monitoring/traces';
-import { IRON_LAWS, GUIDELINES, TIPS } from '../../core/constraints/definitions';
+import { IRON_LAWS, GUIDELINES, PROMPTS } from '../../core/constraints/definitions';
 import { executeWithCollect } from '../../failure/constraint-handler';
 import type { ConstraintContext } from '../../types/constraint';
 
@@ -28,7 +28,7 @@ interface ReportData {
     total: number;
     ironLaws: number;
     guidelines: number;
-    tips: number;
+    prompts: number;
     passed: number;
     failed: number;
     warnings: number;
@@ -50,7 +50,7 @@ export async function report(options: ReportOptions): Promise<void> {
   const checker = ConstraintChecker.getInstance();
   checker.setTraceRecorder(getTraceCollector());
 
-  const allConstraints = { ...IRON_LAWS, ...GUIDELINES, ...TIPS };
+  const allConstraints = { ...IRON_LAWS, ...GUIDELINES, ...PROMPTS };
   const totalConstraints = Object.keys(allConstraints).length;
 
   const context: ConstraintContext = {
@@ -81,7 +81,7 @@ export async function report(options: ReportOptions): Promise<void> {
       total: totalConstraints,
       ironLaws: Object.keys(IRON_LAWS).length,
       guidelines: Object.keys(GUIDELINES).length,
-      tips: Object.keys(TIPS).length,
+      prompts: Object.keys(PROMPTS).length,
       passed: result.passed ? totalConstraints : totalConstraints - violations.length,
       failed: failedIronLaws.length,
       warnings: failedGuidelines.length,
@@ -129,7 +129,7 @@ function generateMarkdownReport(data: ReportData): string {
     `| 总约束 | ${data.constraints.total} |`,
     `| Iron Laws | ${data.constraints.ironLaws} |`,
     `| Guidelines | ${data.constraints.guidelines} |`,
-    `| Tips | ${data.constraints.tips} |`,
+    `| Prompts | ${data.constraints.prompts} |`,
     `| 通过 | ${data.constraints.passed} |`,
     `| 失败 (error) | ${data.constraints.failed} |`,
     `| 警告 (warning) | ${data.constraints.warnings} |`,
@@ -184,7 +184,7 @@ function generateHtmlReport(data: ReportData): string {
     <tr><td>总约束</td><td>${data.constraints.total}</td></tr>
     <tr><td>Iron Laws</td><td>${data.constraints.ironLaws}</td></tr>
     <tr><td>Guidelines</td><td>${data.constraints.guidelines}</td></tr>
-    <tr><td>Tips</td><td>${data.constraints.tips}</td></tr>
+    <tr><td>Prompts</td><td>${data.constraints.prompts}</td></tr>
     <tr><td>通过</td><td class="passed">${data.constraints.passed}</td></tr>
     <tr><td>失败</td><td class="failed">${data.constraints.failed}</td></tr>
     <tr><td>警告</td><td>${data.constraints.warnings}</td></tr>

package/src/cli/commands/status.ts

@@ -9,6 +9,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { TraceCollector } from '../../monitoring/traces';
 import { TraceAnalyzer } from '../../monitoring/trace-analyzer';
+import { DEFAULT_TRACE_FILE } from '../../types/trace';
 import type { TraceSummary, TraceAnomaly } from '../../types/trace';
 
 export interface StatusOptions {
@@ -28,7 +29,7 @@ export interface StatusOptions {
 export async function status(options: StatusOptions): Promise<void> {
   const projectPath = options.projectPath || process.cwd();
   const harnessDir = path.join(projectPath, '.harness');
-  const tracesPath = path.join(harnessDir, 'traces', 'execution.log');
+  const tracesPath = path.join(projectPath, DEFAULT_TRACE_FILE);
   const statePath = path.join(harnessDir, '.state.json');
 
   console.log(chalk.blue('📊 Harness 状态'));
@@ -91,8 +92,7 @@ export async function status(options: StatusOptions): Promise<void> {
 
       // 下一步建议
       console.log(chalk.blue('💡 下一步建议:'));
-      console.log(chalk.gray('  1. 运行 harness flow 一键诊断 + 提案'));
-      console.log(chalk.gray('  2. 运行 harness status --detail 查看详情'));
+      console.log(chalk.gray('  运行 harness status --detail 查看详情'));
     }
     return;
   }
@@ -159,7 +159,6 @@ export async function status(options: StatusOptions): Promise<void> {
   // 下一步建议
   console.log(chalk.blue('💡 下一步建议:'));
   if (anomalies.length > 0) {
-    console.log(chalk.gray('  harness flow            # 一键执行诊断+提案'));
     console.log(chalk.gray('  harness status --detail # 查看详细状态'));
   } else if (traceCount >= 100) {
     console.log(chalk.gray('  • 状态良好，继续保持！'));

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

@@ -7,9 +7,11 @@
  */
 
 import * as fs from 'fs/promises';
+import * as path from 'path';
 import { IRON_LAWS, GUIDELINES, TIPS } from '../../../core/constraints/definitions';
-import { readCapabilitiesEntries } from '../../../core/constraints/capabilities-parser';
+import { isCapabilityListingFormat, readCapabilitiesEntries } from '../../../core/constraints/capabilities-parser';
 import { FreshnessRunner } from '../../../core/constraints/doc-freshness/runner';
+import type { CapabilitiesMode } from '../../../core/project-config-loader';
 import type { DocFreshnessCheck } from '../../../types/project-config';
 import type { ModuleInfo, SyncResult } from './project-reader';
 
@@ -33,13 +35,11 @@ export async function parseCapabilitiesFiles(capabilitiesPath: string): Promise<
 
 /**
  * 检测 CAPABILITIES.md 是否使用能力清单格式（计数行），而非文件表格格式
+ *
+ * @deprecated 实现已收敛到 core/constraints/capabilities-parser（与工单 19-B 同方向），
+ * 此处保留 re-export 兼容现有调用方
  */
-export 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);
-}
+export { isCapabilityListingFormat };
 
 /**
  * 构建 CAPABILITIES.md 能力清单格式的检查配置
@@ -137,19 +137,23 @@ export function updateCapabilityCounts(content: string, projectPath: string): st
 
 /**
  * 更新 CAPABILITIES.md 文件
+ *
+ * module 模式（governance.capabilities.mode=module）下不再为新文件自动加表格行
+ * （目录条目需人工策划登记），幽灵行剔除与「最后更新」刷新保留。
  */
 export async function updateCapabilitiesFile(
   capabilitiesPath: string,
   currentModules: ModuleInfo[],
   existingFiles: string[],
   result: SyncResult,
+  mode: CapabilitiesMode = 'file',
 ): Promise<void> {
   let content: string;
   try {
     content = await fs.readFile(capabilitiesPath, 'utf-8');
   } catch {
-    // 文件不存在，创建新的
-    content = generateCapabilitiesContent(currentModules);
+    // 文件不存在，创建新的（module 模式生成按目录聚合的模板）
+    content = generateCapabilitiesContent(currentModules, mode);
     await fs.writeFile(capabilitiesPath, content, 'utf-8');
     return;
   }
@@ -164,8 +168,8 @@ export async function updateCapabilitiesFile(
       content = content.replace(rowRegex, '');
     }
 
-    // 添加新文件的行（在最后一个表格行之后）
-    if (result.added.length > 0) {
+    // 添加新文件的行（在最后一个表格行之后）；module 模式跳过
+    if (mode !== 'module' && 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;
@@ -186,8 +190,8 @@ export async function updateCapabilitiesFile(
     // 清理多余空行
     content = content.replace(/\n{3,}/g, '\n\n');
   } else {
-    // 没有表格，追加模块表格
-    content += '\n\n' + generateModuleTable(currentModules);
+    // 没有表格，追加模块表格（module 模式按目录聚合）
+    content += '\n\n' + (mode === 'module' ? generateDirTable(currentModules) : generateModuleTable(currentModules));
   }
 
   // 更新最后更新时间
@@ -203,7 +207,7 @@ export async function updateCapabilitiesFile(
 /**
  * 生成 CAPABILITIES.md 内容
  */
-function generateCapabilitiesContent(modules: ModuleInfo[]): string {
+function generateCapabilitiesContent(modules: ModuleInfo[], mode: CapabilitiesMode = 'file'): string {
   const now = new Date().toISOString().split('T')[0];
   return `# CAPABILITIES.md
 
@@ -211,7 +215,7 @@ function generateCapabilitiesContent(modules: ModuleInfo[]): string {
 
 ---
 
-${generateModuleTable(modules)}
+${mode === 'module' ? generateDirTable(modules) : generateModuleTable(modules)}
 `;
 }
 
@@ -227,3 +231,74 @@ function generateModuleTable(modules: ModuleInfo[]): string {
 
   return `| 模块 | 文件 | 说明 |\n|------|------|------|\n${rows}`;
 }
+
+/**
+ * 生成按目录聚合的模块表格（module 模式模板）
+ *
+ * 每个源码子目录一行目录条目（| core | src/core/ | core |），
+ * 文件直接位于源码根时聚到根目录一行。
+ */
+function generateDirTable(modules: ModuleInfo[]): string {
+  if (modules.length === 0) return '';
+
+  const dirs: string[] = [];
+  for (const m of modules) {
+    const dir = path.posix.dirname(m.file);
+    const key = dir === '.' ? '' : dir + '/';
+    if (key && !dirs.includes(key)) dirs.push(key);
+  }
+
+  const rows = dirs.map(d => {
+    const name = d.replace(/\/$/, '').split('/').pop()!;
+    return `| ${name} | ${d} | ${name} |`;
+  }).join('\n');
+
+  return `| 模块 | 文件 | 说明 |\n|------|------|------|\n${rows}`;
+}
+
+/**
+ * 将 CAPABILITIES.md 文件表格折叠为目录条目（--compact 一次性迁移）
+ *
+ * 按文件条目（第二列）的 dirname 分组：同组 ≥2 个文件条目折叠为一行目录条目
+ * （替换组内第一行、删除其余行，说明取组内第一行，为空则用目录名）；
+ * 单独成组的文件行、表头、非表格文本、PRESERVE 块原样保留。
+ * 已折叠的目录条目行不再匹配文件条目，故幂等。
+ */
+export function compactCapabilitiesContent(content: string): string {
+  const lines = content.split('\n');
+  const fileEntryRegex = /\.(?:ts|tsx|js|jsx)$/;
+  const rowRegex = /^\|[^|]+\|[^|]+\|[^|]+\|\s*$/;
+
+  interface TableRow {
+    lineIndex: number;
+    file: string;
+    desc: string;
+  }
+
+  // 收集文件条目行，按 dirname 分组（无目录前缀的条目不参与折叠）
+  const groups = new Map<string, TableRow[]>();
+  for (let i = 0; i < lines.length; i++) {
+    if (!rowRegex.test(lines[i])) continue;
+    const cells = lines[i].split('|').map(c => c.trim());
+    const file = cells[2] ?? '';
+    if (!fileEntryRegex.test(file)) continue;
+    const dir = path.posix.dirname(file);
+    if (dir === '.') continue;
+    const group = groups.get(dir) ?? [];
+    group.push({ lineIndex: i, file, desc: cells[3] ?? '' });
+    groups.set(dir, group);
+  }
+
+  const deleteLines = new Set<number>();
+  for (const [dir, rows] of groups) {
+    if (rows.length < 2) continue;
+    const name = dir.split('/').pop()!;
+    const desc = rows[0].desc || name;
+    lines[rows[0].lineIndex] = `| ${name} | ${dir}/ | ${desc} |`;
+    for (const row of rows.slice(1)) {
+      deleteLines.add(row.lineIndex);
+    }
+  }
+
+  return lines.filter((_, i) => !deleteLines.has(i)).join('\n');
+}

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

@@ -16,8 +16,9 @@ import chalk from 'chalk';
 import * as fs from 'fs/promises';
 import { existsSync } from 'fs';
 import * as path from 'path';
-import { readCapabilitiesEntries } from '../../../core/constraints/capabilities-parser';
+import { aggregateToSourceSubdir, readCapabilitiesEntries } from '../../../core/constraints/capabilities-parser';
 import { detectSourceRoots } from '../../../utils/detect-source-roots';
+import { getCapabilitiesMode } from '../../../core/project-config-loader';
 import { getSourceDirs, scanSourceModules, getRequiredContextDirs } from './project-reader';
 import type { ModuleInfo, SyncResult } from './project-reader';
 import {
@@ -26,6 +27,7 @@ import {
   checkCapabilityCounts,
   updateCapabilityCounts,
   updateCapabilitiesFile,
+  compactCapabilitiesContent,
 } from './capabilities-syncer';
 import { createContextMd, findExistingContextFiles, getLatestTsMtime } from './context-syncer';
 import { buildAgentsMd } from './agents-syncer';
@@ -42,6 +44,8 @@ export interface SyncDocsOptions {
   json?: boolean;
   /** 同步 AGENTS.md（agent 导读）；PRESERVE 标记段在重新生成时原样保留 */
   agents?: boolean;
+  /** 一次性迁移：将 CAPABILITIES.md 文件表格折叠为目录条目 */
+  compact?: boolean;
 }
 
 /**
@@ -51,6 +55,26 @@ export async function syncDocs(options: SyncDocsOptions): Promise<boolean> {
   const projectPath = options.projectPath || process.cwd();
   const isCheck = options.check === true;
   const isJson = options.json === true;
+  const capsMode = getCapabilitiesMode(projectPath);
+
+  // --compact：一次性迁移，将文件表格折叠为目录条目后直接返回
+  if (options.compact) {
+    const capsPath = path.join(projectPath, 'CAPABILITIES.md');
+    try {
+      const content = await fs.readFile(capsPath, 'utf-8');
+      const compacted = compactCapabilitiesContent(content);
+      if (compacted !== content) {
+        await fs.writeFile(capsPath, compacted, 'utf-8');
+        if (!isJson) console.log(chalk.green('✅ 已将 CAPABILITIES.md 文件表格折叠为目录条目'));
+      } else {
+        if (!isJson) console.log(chalk.green('✅ CAPABILITIES.md 无需折叠'));
+      }
+      return true;
+    } catch {
+      if (!isJson) console.log(chalk.red('❌ CAPABILITIES.md 不存在，无法折叠'));
+      return false;
+    }
+  }
 
   if (!isJson) {
     if (isCheck) {
@@ -88,7 +112,8 @@ export async function syncDocs(options: SyncDocsOptions): Promise<boolean> {
   let capsIsCapabilityListing = false;
   try {
     capsContent = await fs.readFile(capabilitiesPath, 'utf-8');
-    if (isCapabilityListingFormat(capsContent)) {
+    // mode=listing 是清单格式的显式声明，与嗅探结果等价
+    if (capsMode === 'listing' || isCapabilityListingFormat(capsContent)) {
       capsIsCapabilityListing = true;
     } else {
       existingFiles = await parseCapabilitiesFiles(capabilitiesPath);
@@ -116,13 +141,31 @@ export async function syncDocs(options: SyncDocsOptions): Promise<boolean> {
     // （basename 列表里永远不会有目录，直接对比会把目录行误报为「已删除的模块」）
     const existingDirs = existingFiles.filter(f => f.endsWith('/'));
     const existingFileNames = existingFiles.filter(f => !f.endsWith('/'));
-    result.added = currentModules
-      .filter(
-        m =>
-          !existingDirs.some(d => m.file.startsWith(d)) &&
-          !existingFileNames.includes(getBasename(m.file))
-      )
-      .map(m => getBasename(m.file));
+    if (capsMode === 'module') {
+      // module 模式：文件条目精确匹配或目录条目前缀覆盖；
+      // added 不再是逐文件列表，聚合为「未覆盖目录」（与 capability_sync checker 同规则）
+      const entries = readCapabilitiesEntries(capabilitiesPath, { includeDirs: true });
+      const fileEntries = entries.filter(e => !e.endsWith('/'));
+      const dirEntries = entries.filter(e => e.endsWith('/'));
+      const uncoveredDirs = new Set<string>();
+      for (const m of currentModules) {
+        const covered =
+          fileEntries.includes(m.file) || dirEntries.some(d => m.file.startsWith(d));
+        if (!covered) {
+          const root = srcDirs.find(d => m.file.startsWith(d + '/')) || srcDirs[0] || '';
+          uncoveredDirs.add(aggregateToSourceSubdir(root, m.file));
+        }
+      }
+      result.added = [...uncoveredDirs];
+    } else {
+      result.added = currentModules
+        .filter(
+          m =>
+            !existingDirs.some(d => m.file.startsWith(d)) &&
+            !existingFileNames.includes(getBasename(m.file))
+        )
+        .map(m => getBasename(m.file));
+    }
     result.removed = existingFileNames.filter(f => !currentBasenames.includes(f));
 
     // 幽灵条目清扫（2026-08-08 studio CI 4 连红事故）：上方按 basename 对比，
@@ -235,18 +278,30 @@ export async function syncDocs(options: SyncDocsOptions): Promise<boolean> {
     }
 
     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 (capsMode === 'module') {
+        // module 模式：added 为聚合后的未覆盖目录，需人工登记目录条目
+        jsonOutput.added = result.added.map(d => ({ dir: d }));
+        jsonOutput.removed = result.removed.map(f => ({ file: f }));
+        (jsonOutput.resolution as Array<Record<string, unknown>>).push({
+          action: 'register-capability-dirs',
+          details:
+            '在 CAPABILITIES.md 中为这些目录登记一行目录条目（如 `| 模块名 | src/xxx/ | 说明 |`）',
+          dirs: result.added,
+        });
+      } else {
+        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) {
@@ -282,8 +337,16 @@ export async function syncDocs(options: SyncDocsOptions): Promise<boolean> {
   }
 
   if (result.added.length > 0) {
-    console.log(chalk.yellow(`\n📄 CAPABILITIES.md 缺少以下模块:`));
-    result.added.forEach(f => console.log(chalk.gray(`  + ${f}`)));
+    if (capsMode === 'module') {
+      console.log(chalk.yellow(`\n📄 CAPABILITIES.md 未登记以下模块（目录）:`));
+      result.added.forEach(d => console.log(chalk.gray(`  + ${d}`)));
+      console.log(
+        chalk.gray('  请在 CAPABILITIES.md 中为这些目录登记一行目录条目（如 `| 模块名 | src/xxx/ | 说明 |`）')
+      );
+    } else {
+      console.log(chalk.yellow(`\n📄 CAPABILITIES.md 缺少以下模块:`));
+      result.added.forEach(f => console.log(chalk.gray(`  + ${f}`)));
+    }
   }
 
   if (result.removed.length > 0) {
@@ -337,7 +400,7 @@ export async function syncDocs(options: SyncDocsOptions): Promise<boolean> {
   }
 
   if (!capsIsCapabilityListing && hasTableIssues) {
-    await updateCapabilitiesFile(capabilitiesPath, currentModules, existingFiles, result);
+    await updateCapabilitiesFile(capabilitiesPath, currentModules, existingFiles, result, capsMode);
     console.log(chalk.green(`\n✅ 已更新 CAPABILITIES.md`));
   }
 

package/src/cli/commands/validate.ts

@@ -163,7 +163,7 @@ export async function createExampleCheckpoint(projectPath: string): Promise<void
  * 默认 Resolutions（RKB — 约束 → 已知解法映射）
  */
 const DEFAULT_RESOLUTIONS = {
-  no_claim_without_evidence: {
+  no_fuzzy_completion_claim: {
     title: 'commit message 缺少验证证据',
     fix: '在 commit message body 中附上验证输出:\n`npx harness check --staged` | `npx harness validate` | `npm test -- --coverage`\n确认全部通过后重新 commit。',
   },
@@ -175,10 +175,6 @@ const DEFAULT_RESOLUTIONS = {
     title: '关键目录缺少 CONTEXT.md',
     fix: '在 required_dirs 目录下创建 CONTEXT.md。运行 `npx harness sync-docs` 可自动生成模板。',
   },
-  no_coverage_decrease: {
-    title: '测试覆盖率下降',
-    fix: '运行 `npm test -- --coverage` 查看当前覆盖率。新增文件必须有对应的测试文件。',
-  },
 };
 
 /**