@dommaker/harness 1.8.0 → 1.9.0

package/src/cli/commands/__tests__/sync-docs-table-layout.test.ts

@@ -0,0 +1,259 @@
+/**
+ * sync-docs 表格排版回归测试（harness#171）
+ *
+ * 症状：撤下 CAPABILITIES.md 的模块登记行时清空该行而非删行，残留空行把
+ * CommonMark 表格切断。判定面 = 「上一行与下一行都是 `|` 表格行、本行为空」不得存在。
+ * 正本修复在写路径（整行删除 + 存量收拢 + 空表收掉），--check 侧必须报待清理
+ * （check/fix 同规则才收敛，ADR-0009 口径）。
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { captureIO, type CapturingIO } from '../../command-contract';
+import { normalizeCapabilitiesTableLayout } from '../sync-docs/capabilities-syncer';
+import { syncDocs } from '../sync-docs';
+
+let io: CapturingIO;
+beforeEach(() => {
+  io = captureIO();
+});
+
+const HEADER = '| 模块 | 文件 | 说明 |\n|------|------|------|\n';
+
+/** 「上一行与下一行都是表格行、本行为空」的行数 —— 本票的判定面 */
+function countBlankRowsInsideTable(content: string): number {
+  const lines = content.split('\n');
+  let n = 0;
+  for (let i = 1; i < lines.length - 1; i++) {
+    if (
+      lines[i].trim() === '' &&
+      /^\s*\|/.test(lines[i - 1]) &&
+      /^\s*\|/.test(lines[i + 1])
+    ) {
+      n++;
+    }
+  }
+  return n;
+}
+
+/** 建一个 file 模式的最小工程：srcFiles 存在，CAPABILITIES.md 由 rows 拼出 */
+function makeProject(
+  name: string,
+  srcFiles: string[],
+  doc: string
+): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), `sync-docs-layout-${name}-`));
+  fs.mkdirSync(path.join(dir, 'src'), { recursive: true });
+  for (const f of srcFiles) {
+    const file = path.join(dir, 'src', f);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, 'export const x = 1;\n');
+  }
+  fs.writeFileSync(path.join(dir, 'CAPABILITIES.md'), doc);
+  return dir;
+}
+const read = (dir: string) => fs.readFileSync(path.join(dir, 'CAPABILITIES.md'), 'utf-8');
+const dataRow = (name: string, file: string, desc = 'D') => `| ${name} | ${file} | ${desc} |`;
+
+describe('sync-docs CAPABILITIES.md 表格排版（#171）', () => {
+  it('撤中间登记行：整行删除，表格保持连续', async () => {
+    const dir = makeProject(
+      'middle',
+      ['a.ts', 'c.ts'],
+      `# Capabilities\n\n${HEADER}${dataRow('a', 'src/a.ts')}\n${dataRow('b', 'src/b.ts')}\n${dataRow('c', 'src/c.ts')}\n`
+    );
+
+    await syncDocs({ projectPath: dir }, io);
+
+    const out = read(dir);
+    expect(out).not.toContain('src/b.ts');
+    expect(countBlankRowsInsideTable(out)).toBe(0);
+    expect(out).toBe(`# Capabilities\n\n${HEADER}${dataRow('a', 'src/a.ts')}\n${dataRow('c', 'src/c.ts')}\n`);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('撤目录条目行（studio 撤登记形状）：同样整行删除', async () => {
+    const dir = makeProject(
+      'dir-entry',
+      ['cli/cli.ts', 'harness/h.ts'],
+      `# Capabilities\n\n${HEADER}` +
+        `${dataRow('cli', 'src/cli/', 'C')}\n` +
+        `${dataRow('hooks', 'src/hooks/', 'H')}\n` +
+        `${dataRow('harness', 'src/harness/', 'A')}\n`
+    );
+
+    await syncDocs({ projectPath: dir }, io);
+
+    const out = read(dir);
+    expect(out).not.toContain('src/hooks/');
+    expect(countBlankRowsInsideTable(out)).toBe(0);
+    expect(out).toContain(`${dataRow('cli', 'src/cli/', 'C')}\n${dataRow('harness', 'src/harness/', 'A')}`);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('撤最后一行：不留文件末尾空行', async () => {
+    const dir = makeProject(
+      'last',
+      ['a.ts'],
+      `# Capabilities\n\n${HEADER}${dataRow('a', 'src/a.ts')}\n${dataRow('gone', 'src/gone.ts')}\n`
+    );
+
+    await syncDocs({ projectPath: dir }, io);
+
+    expect(read(dir)).toBe(`# Capabilities\n\n${HEADER}${dataRow('a', 'src/a.ts')}\n`);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('存量脏行（无其它漂移）：--check 报待清理，写模式收拢且收拢后 check 转绿', async () => {
+    const dirty = `# Capabilities\n\n${HEADER}${dataRow('a', 'src/a.ts')}\n\n${dataRow('z', 'src/z.ts')}\n`;
+    const dir = makeProject('legacy', ['a.ts', 'z.ts'], dirty);
+
+    expect(countBlankRowsInsideTable(read(dir))).toBe(1);
+    const check = await syncDocs({ projectPath: dir, check: true }, io);
+    expect(check).toEqual({ kind: 'fail', reason: expect.stringContaining('表格') });
+
+    await syncDocs({ projectPath: dir }, io);
+    const out = read(dir);
+    expect(countBlankRowsInsideTable(out)).toBe(0);
+    expect(out).toContain('src/a.ts');
+    expect(out).toContain('src/z.ts');
+    expect(await syncDocs({ projectPath: dir, check: true }, io)).toEqual({ kind: 'ok' });
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('表格被撤空：连表头/分隔行一起收掉', async () => {
+    const dir = makeProject(
+      'empty-table',
+      [],
+      `# Capabilities\n\n${HEADER}${dataRow('gone1', 'src/gone1.ts')}\n${dataRow('gone2', 'src/gone2.ts')}\n`
+    );
+
+    await syncDocs({ projectPath: dir }, io);
+
+    const out = read(dir);
+    expect(out).not.toContain('|------|');
+    expect(out).not.toContain('模块 | 文件');
+    expect(out).not.toMatch(/\n{3,}/);
+    expect(await syncDocs({ projectPath: dir, check: true }, io)).toEqual({ kind: 'ok' });
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('撤登同时有新增：不得把仍要使用的表头收掉', async () => {
+    const dir = makeProject(
+      'remove-and-add',
+      ['b.ts', 'fresh.ts'],
+      `# Capabilities\n\n${HEADER}${dataRow('a', 'src/gone.ts')}\n${dataRow('b', 'src/b.ts')}\n`
+    );
+
+    await syncDocs({ projectPath: dir }, io);
+
+    const out = read(dir);
+    expect(out).toContain('模块 | 文件 | 说明');
+    expect(out).toContain('fresh.ts');
+    expect(countBlankRowsInsideTable(out)).toBe(0);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('表格外的空行不动（段落分隔不是脏行）', async () => {
+    const doc = `# Capabilities\n\n${HEADER}${dataRow('a', 'src/a.ts')}\n\n## 说明\n\n散文。\n`;
+    const dir = makeProject('prose', ['a.ts'], doc);
+
+    const check = await syncDocs({ projectPath: dir, check: true }, io);
+    expect(check).toEqual({ kind: 'ok' });
+    expect(read(dir)).toBe(doc);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('代码块内「表头+分隔行无数据行」的示例不被收掉', async () => {
+    const doc =
+      `# Capabilities\n\n${HEADER}${dataRow('a', 'src/a.ts')}\n\n` +
+      `登记格式：\n\n\`\`\`markdown\n| 模块 | 文件 | 说明 |\n|------|------|------|\n\`\`\`\n\n散文。\n`;
+    const dir = makeProject('fenced-empty-table', ['a.ts'], doc);
+
+    expect(await syncDocs({ projectPath: dir, check: true }, io)).toEqual({ kind: 'ok' });
+
+    await syncDocs({ projectPath: dir }, io);
+    expect(read(dir)).toBe(doc);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('代码块内的表格样式行不被收拢（含块内空行）', async () => {
+    const doc =
+      `# Capabilities\n\n${HEADER}${dataRow('a', 'src/a.ts')}\n\n` +
+      `示例：\n\n\`\`\`\n| x | y |\n\n| z | w |\n\`\`\`\n`;
+    const dir = makeProject('fenced-blank-row', ['a.ts'], doc);
+
+    expect(await syncDocs({ projectPath: dir, check: true }, io)).toEqual({ kind: 'ok' });
+
+    await syncDocs({ projectPath: dir }, io);
+    expect(read(dir)).toBe(doc);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('两张空表相邻：一次收拢即干净（规则互相制造触发点，须跑到不动点）', () => {
+    // 规则①先吃掉两张空表之间的那个空行（两侧都是表格行），规则②在同一轮里
+    // 只看得到「表头+分隔行后面还有表格行」的前一张，收得掉后一张。不迭代就收不干净。
+    const first = normalizeCapabilitiesTableLayout(`${HEADER}\n${HEADER}`);
+
+    expect(first).toEqual({ content: '', blankLines: 1, emptyTables: 2 });
+    // 不动点：再跑一次零改动，`--check` 才不会修完还红
+    expect(normalizeCapabilitiesTableLayout(first.content)).toEqual({
+      content: '',
+      blankLines: 0,
+      emptyTables: 0,
+    });
+  });
+
+  it('收掉空表后不留三个以上连续换行（写模式收干净）', async () => {
+    const dir = makeProject(
+      'no-triple-newline',
+      [],
+      `# Capabilities\n\n${HEADER}${dataRow('gone', 'src/gone.ts')}\n\n## 说明\n\n散文。\n`
+    );
+
+    await syncDocs({ projectPath: dir }, io);
+
+    const out = read(dir);
+    expect(out).not.toMatch(/\n{3,}/);
+    expect(out).toContain('## 说明');
+    expect(out).toContain('散文。');
+    expect(await syncDocs({ projectPath: dir, check: true }, io)).toEqual({ kind: 'ok' });
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('围栏内示例行引用已删文件：随幽灵行一起删掉，且 check 收敛（取舍见实现注释）', async () => {
+    // 登记条目由 capabilities-parser 全文扫描得出（ADR-0009），块内行也算登记项；
+    // 只让幽灵行删除豁免围栏，这个示例会永远被报成已删模块且修不掉。
+    const doc =
+      `# Capabilities\n\n${HEADER}${dataRow('a', 'src/a.ts')}\n\n` +
+      `登记格式示例：\n\n\`\`\`markdown\n${HEADER}${dataRow('gone', 'src/gone.ts')}\n\`\`\`\n`;
+    const dir = makeProject('fenced-ghost-entry', ['a.ts'], doc);
+
+    expect(await syncDocs({ projectPath: dir, check: true }, io)).toMatchObject({ kind: 'fail' });
+    expect(io.outText()).toContain('src/gone.ts');
+
+    await syncDocs({ projectPath: dir }, io);
+
+    const out = read(dir);
+    expect(out).not.toContain('src/gone.ts');
+    expect(out).toContain(dataRow('a', 'src/a.ts'));
+    // 只吃掉引用已删文件的那一行，块内其余正文留着（不是「把围栏里所有行一起删」）
+    expect(out).toContain('```markdown\n' + HEADER);
+    expect(countBlankRowsInsideTable(out)).toBe(0);
+    expect(await syncDocs({ projectPath: dir, check: true }, io)).toEqual({ kind: 'ok' });
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('CRLF 文档撤行：整行连行尾一起删除', async () => {
+    const doc = `# Capabilities\r\n\r\n${HEADER.replace(/\n/g, '\r\n')}${dataRow('a', 'src/a.ts')}\r\n${dataRow('gone', 'src/gone.ts')}\r\n`;
+    const dir = makeProject('crlf', ['a.ts'], doc);
+
+    await syncDocs({ projectPath: dir }, io);
+
+    const out = read(dir);
+    expect(out).not.toContain('src/gone.ts');
+    expect(out.endsWith(`${dataRow('a', 'src/a.ts')}\r\n`)).toBe(true);
+    expect(countBlankRowsInsideTable(out)).toBe(0);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+});

package/src/cli/commands/check.ts

@@ -9,7 +9,6 @@
  */
 
 import chalk from 'chalk';
-import * as fs from 'fs';
 import * as path from 'path';
 import { ConstraintChecker } from '../../core/constraints/checker';
 import { IRON_LAWS, GUIDELINES, PROMPTS } from '../../core/constraints/definitions';
@@ -24,6 +23,7 @@ import { readJsonl } from '../../utils/jsonl';
 import { DEFAULT_TRACE_FILE, type ExecutionTrace } from '../../types/trace';
 import type { ConstraintResult, ConstraintTrigger } from '../../types/constraint';
 import { log, processIO, type CommandIO, type CommandResult } from '../command-contract';
+import { fileStateIO, type StateIO } from '../state-io';
 
 /** 证据行着色（与调用处所属结论块一致） */
 const EVIDENCE_PAINT = {
@@ -74,6 +74,13 @@ export interface CheckOptions {
    * 测试据此断言「同一次运行内同一项目文件至多读一次」。
    */
   runEnv?: RunEnv;
+  /**
+   * 状态文件接缝（非 CLI flag；ADR-0026）
+   *
+   * 缺省 = 真实 fs 实现（fileStateIO）。注入则 `.harness/.state.json` 的读写
+   * 走替身，测试据此不碰真文件系统。
+   */
+  stateIO?: StateIO;
 }
 
 /**
@@ -91,6 +98,7 @@ export async function check(
     // 一次 run 一份证据与观察面（#87 / ADR-0023）：入口构造，沿生效集、context、checker 向下传
     const evidence = options.evidence ?? createGitEvidence(projectPath);
     const runEnv = options.runEnv ?? createRunEnv(projectPath);
+    const stateIO = options.stateIO ?? fileStateIO(projectPath);
 
     // 生效约束集（ADR-0001）：内置 → preset → config.yml 禁用 → custom 追加 → scenes 过滤。
     // --preset 仅在没有项目自定义配置时覆盖 config.yml 的 preset（工单 23 语义：
@@ -221,7 +229,7 @@ export async function check(
     log(io, chalk.green('✅ 约束检查通过'));
 
     // 智能提示
-    const hint = await getSmartHint(projectPath);
+    const hint = await getSmartHint(projectPath, stateIO);
     if (hint) {
       log(io);
       log(io, chalk.gray('────────────────────────────────────'));
@@ -241,10 +249,12 @@ const TRACE_HINT_THRESHOLD = 50;
 
 /**
  * 智能提示：检查是否需要提示用户下一步操作
+ *
+ * 状态读写经 StateIO（ADR-0026）：读-改-写，`status` 不再把 `shownHints` 抹掉，
+ * 「首次达到阈值」的去重自此真生效。
  */
-async function getSmartHint(projectPath: string): Promise<string | null> {
+async function getSmartHint(projectPath: string, stateIO: StateIO): Promise<string | null> {
   const tracesPath = path.join(projectPath, DEFAULT_TRACE_FILE);
-  const statePath = path.join(projectPath, '.harness', '.state.json');
 
   // 只读够 TRACE_HINT_THRESHOLD 行即停（坏行照旧占位，条数口径与改前的纯计数逐字一致）——
   // traces.log 是 append-only 无上限文件，为一个比较符整读不成立
@@ -256,19 +266,12 @@ async function getSmartHint(projectPath: string): Promise<string | null> {
   if (traceCount === 0) {
     return null;
   }
-  // 读取状态
-  let state: { 
-    shownHints?: string[];
-    lastStatusRun?: string;
-    lastDiagnoseRun?: string;
-  } = {};
-  if (fs.existsSync(statePath)) {
-    state = JSON.parse(fs.readFileSync(statePath, 'utf-8'));
-  }
+  // 读取状态（经接缝；文件缺失 → {}）
+  const state = stateIO.read();
   state.shownHints = state.shownHints || [];
-  
+
   const hints: string[] = [];
-  
+
   // 条件 1: 记录数首次达到阈值
   if (traceCount >= TRACE_HINT_THRESHOLD && !state.shownHints.includes('trace_50')) {
     hints.push('📊 记录已足够，运行 harness status 查看统计');
@@ -277,11 +280,10 @@ async function getSmartHint(projectPath: string): Promise<string | null> {
 
   // 保存状态
   if (hints.length > 0) {
-    fs.mkdirSync(path.dirname(statePath), { recursive: true });
-    fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
+    stateIO.write(state);
     return hints.join('\n');
   }
-  
+
   return null;
 }
 

package/src/cli/commands/status.ts

@@ -13,6 +13,7 @@ import { DEFAULT_TRACE_FILE } from '../../types/trace';
 import type { ExecutionTrace } from '../../types/trace';
 import type { TraceSummary, TraceAnomaly } from '../../types/trace';
 import { log, logError, processIO, type CommandIO, type CommandResult } from '../command-contract';
+import { fileStateIO, type StateIO } from '../state-io';
 
 export interface StatusOptions {
   /** 项目路径 */
@@ -23,6 +24,13 @@ export interface StatusOptions {
   anomalies?: boolean;
   /** 时间范围（小时） */
   hours?: number;
+  /**
+   * 状态文件接缝（非 CLI flag；ADR-0026）
+   *
+   * 缺省 = 真实 fs 实现（fileStateIO）。注入则 `.harness/.state.json` 的读写
+   * 走替身，测试据此不碰真文件系统。
+   */
+  stateIO?: StateIO;
 }
 
 /**
@@ -32,7 +40,7 @@ export async function status(options: StatusOptions, io: CommandIO = processIO):
   const projectPath = options.projectPath || process.cwd();
   const harnessDir = path.join(projectPath, '.harness');
   const tracesPath = path.join(projectPath, DEFAULT_TRACE_FILE);
-  const statePath = path.join(harnessDir, '.state.json');
+  const stateIO = options.stateIO ?? fileStateIO(projectPath);
 
   log(io, chalk.blue('📊 Harness 状态'));
   log(io);
@@ -139,12 +147,9 @@ export async function status(options: StatusOptions, io: CommandIO = processIO):
     log(io);
   }
 
-  // 更新状态文件
-  const state = {
-    lastStatusRun: new Date().toISOString(),
-  };
-  fs.mkdirSync(path.dirname(statePath), { recursive: true });
-  fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
+  // 更新状态文件：读-改-写（ADR-0026 决策 2）——不再整文件重写，
+  // 否则 check 写入的 shownHints 会被抹掉、智能提示去重失效
+  stateIO.write({ ...stateIO.read(), lastStatusRun: new Date().toISOString() });
 
   // 下一步建议
   log(io, chalk.blue('💡 下一步建议:'));

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

@@ -54,12 +54,22 @@ export async function updateCapabilitiesFile(
 
   // 如果有表格行，更新表格
   if (existingFiles.length > 0) {
-    // 移除已删除文件的行
-    for (const removed of result.removed) {
-      const escapedFile = removed.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-      // 第二列存完整路径，basename 只在末尾出现，用 [^|]* 匹配路径前缀
-      const rowRegex = new RegExp(`^\\|[^|]*\\|[^|]*\\b${escapedFile}\\s*\\|.*$`, 'gm');
-      content = content.replace(rowRegex, '');
+    // 移除已删除文件的行（整行连行尾一起删——只清行内容会留一个空行，
+    // CommonMark 据此把一张表切成若干小表，harness#171）。
+    // 这里**不**豁免围栏代码块，与下方排版收拢刻意不同口径：登记条目由
+    // capabilities-parser 全文扫描得出（ADR-0009），围栏内的行同样算登记项；
+    // 只让删除认围栏而条目不认，块内示例行会一直被解析成幽灵条目，`--check`
+    // 从此每轮都报同一个已删文件且永远修不掉。豁免要生效得连登记面一起改。
+    if (result.removed.length > 0) {
+      const deadRowRegexes = result.removed.map((removed) => {
+        const escapedFile = removed.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        // 第二列存完整路径，basename 只在末尾出现，用 [^|]* 匹配路径前缀
+        return new RegExp(`^\\|[^|]*\\|[^|]*\\b${escapedFile}\\s*\\|.*\\r?$`);
+      });
+      content = content
+        .split('\n')
+        .filter((line) => !deadRowRegexes.some((rowRegex) => rowRegex.test(line)))
+        .join('\n');
     }
 
     // 添加新文件的行（在最后一个表格行之后）；module 模式跳过
@@ -80,14 +90,17 @@ export async function updateCapabilitiesFile(
         content = content.replace(lastTableRow, lastTableRow + '\n' + newRows);
       }
     }
-
-    // 清理多余空行
-    content = content.replace(/\n{3,}/g, '\n\n');
   } else {
     // 没有表格，追加模块表格（module 模式按目录聚合）
     content += '\n\n' + (mode === 'module' ? generateDirTable(currentModules) : generateModuleTable(currentModules));
   }
 
+  // 表格排版收拢放在增删之后：有新行的表不会被误判为空表（#171）
+  content = normalizeCapabilitiesTableLayout(content).content;
+  // 多余空行的清理收在收拢之后一处：收拢本身会新产出连续空行
+  // （收掉一张夹在两段散文之间的空表就留下 `\n\n\n`，#171）
+  content = content.replace(/\n{3,}/g, '\n\n');
+
   // 更新最后更新时间
   const now = new Date().toISOString().split('T')[0];
   content = content.replace(
@@ -98,6 +111,123 @@ export async function updateCapabilitiesFile(
   await fs.writeFile(capabilitiesPath, content, 'utf-8');
 }
 
+/** 表格行：以 `|` 起始（表头、分隔行、数据行都算） */
+const TABLE_ROW_REGEX = /^\s*\|/;
+
+/** 表格分隔行（|------|------|） */
+const TABLE_SEPARATOR_REGEX = /^\s*\|[\s:|-]+\|\s*$/;
+
+/** 围栏代码块的起止行（``` / ~~~，允许缩进与信息串） */
+const FENCE_LINE_REGEX = /^\s*(?:```|~~~)/;
+
+export interface TableLayoutNormalization {
+  /** 收拢后的内容 */
+  content: string;
+  /** 被删掉的「表格内空行」行数 */
+  blankLines: number;
+  /** 被收掉的「空表」（表头+分隔行且无数据行）张数 */
+  emptyTables: number;
+}
+
+/** 参与排版判定的行：正文 + 是否落在围栏代码块内 */
+interface LayoutLine {
+  text: string;
+  fenced: boolean;
+}
+
+/**
+ * 按行切开并标出围栏代码块（``` / ~~~）内的行
+ *
+ * 只服务排版收拢：CAPABILITIES.md 是手写文档，块内长得像表格的示例行不是排版脏行，
+ * 收它就是删用户正文（harness#171）。登记条目面不在此列——见 `updateCapabilitiesFile`
+ * 里「幽灵行删除不豁免围栏」的取舍注释。
+ */
+function parseLayoutLines(content: string): LayoutLine[] {
+  const parsed: LayoutLine[] = [];
+  let inFence = false;
+  for (const text of content.split('\n')) {
+    if (FENCE_LINE_REGEX.test(text)) {
+      parsed.push({ text, fenced: true });
+      inFence = !inFence;
+      continue;
+    }
+    parsed.push({ text, fenced: inFence });
+  }
+  return parsed;
+}
+
+const isTableRow = (line: LayoutLine | undefined): line is LayoutLine =>
+  line !== undefined && !line.fenced && TABLE_ROW_REGEX.test(line.text);
+
+const isTableSeparator = (line: LayoutLine | undefined): boolean =>
+  line !== undefined && !line.fenced && TABLE_SEPARATOR_REGEX.test(line.text);
+
+/** 走一遍两条收拢规则（不迭代） */
+function collapseTableLayoutOnce(content: string): TableLayoutNormalization {
+  const parsed = parseLayoutLines(content);
+
+  // ① 收拢表格内空行：一段连续空行，两侧最近非空行都是表格行 → 整段丢弃
+  const kept: LayoutLine[] = [];
+  let blankLines = 0;
+  for (let i = 0; i < parsed.length; ) {
+    if (parsed[i].text.trim() !== '') {
+      kept.push(parsed[i]);
+      i++;
+      continue;
+    }
+    let end = i;
+    while (end < parsed.length && parsed[end].text.trim() === '') end++;
+    if (isTableRow(kept[kept.length - 1]) && isTableRow(parsed[end])) {
+      blankLines += end - i;
+    } else {
+      kept.push(...parsed.slice(i, end));
+    }
+    i = end;
+  }
+
+  // ② 收掉空表：表头 + 分隔行后面没有数据行
+  const out: string[] = [];
+  let emptyTables = 0;
+  for (let i = 0; i < kept.length; i++) {
+    if (isTableRow(kept[i]) && isTableSeparator(kept[i + 1]) && !isTableRow(kept[i + 2])) {
+      emptyTables++;
+      i++;
+      continue;
+    }
+    out.push(kept[i].text);
+  }
+
+  return { content: out.join('\n'), blankLines, emptyTables };
+}
+
+/**
+ * 收拢 CAPABILITIES.md 的表格排版（harness#171）
+ *
+ * 两条规则：① 删掉夹在两个表格行之间的空行（CommonMark 会在此切断表格）；
+ * ② 收掉没有数据行的表头+分隔行。表格外的空行（段落分隔）不动；围栏代码块内的行整体豁免。
+ *
+ * 规则互相制造对方的触发点（①把两张空表之间的那个空行吃掉后，②一轮只收得掉后一张），
+ * 所以跑到不动点：**一次 `sync-docs` 必须把 `--check` 报出来的东西全清掉**，
+ * 否则下游 CI 修完还是红的。计数 = 各轮合计（每轮只删当轮存在的行，不会重计）。
+ *
+ * 幂等，且 `--check` 与写模式共用此正本——判定面就是「返回内容与入参是否不同」，
+ * 因此不存在「check 报了 fix 修不掉」的不收敛（ADR-0009 口径）。
+ */
+export function normalizeCapabilitiesTableLayout(content: string): TableLayoutNormalization {
+  let current = content;
+  let blankLines = 0;
+  let emptyTables = 0;
+  for (;;) {
+    const pass = collapseTableLayoutOnce(current);
+    if (pass.blankLines === 0 && pass.emptyTables === 0) {
+      return { content: current, blankLines, emptyTables };
+    }
+    blankLines += pass.blankLines;
+    emptyTables += pass.emptyTables;
+    current = pass.content;
+  }
+}
+
 /**
  * 生成 CAPABILITIES.md 内容
  */

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

@@ -34,6 +34,7 @@ import {
   parseCapabilitiesFiles,
   updateCapabilitiesFile,
   compactCapabilitiesContent,
+  normalizeCapabilitiesTableLayout,
 } from './capabilities-syncer';
 import {
   createContextMd,
@@ -264,7 +265,15 @@ export async function syncDocs(
   }
   const hasAgentsIssues = options.agents === true && agentsMdStale;
 
-  const hasTableIssues = result.added.length > 0 || result.removed.length > 0;
+  // 表格排版脏行（#171）：撤登记时残留的空行会把 CAPABILITIES.md 的表格切断。
+  // 判定与修复共用 normalizeCapabilitiesTableLayout 正本——同一份规则，check 报的 fix 必清得掉。
+  const tableLayout = capsIsCapabilityListing
+    ? { blankLines: 0, emptyTables: 0 }
+    : normalizeCapabilitiesTableLayout(capsContent);
+  const hasTableLayoutIssues = tableLayout.blankLines > 0 || tableLayout.emptyTables > 0;
+
+  const hasTableEntryIssues = result.added.length > 0 || result.removed.length > 0;
+  const hasTableIssues = hasTableEntryIssues || hasTableLayoutIssues;
   const hasCapIssues = capCountMismatches.length > 0;
   // mtime 只作提示，不参与判定（harness#142）：判定面是内容漂移与缺失
   const hasContextIssues = result.contextMissing.length > 0 || result.contextContentDrift.length > 0;
@@ -287,6 +296,7 @@ export async function syncDocs(
         contextMissing: result.contextMissing.length,
         contextStale: result.contextStale.length,
         contextContentDrift: result.contextContentDrift.length,
+        tableLayoutDirty: hasTableLayoutIssues,
       },
       contextMissing: result.contextMissing.map(d => ({
         dir: d,
@@ -314,7 +324,7 @@ export async function syncDocs(
       });
     }
 
-    if (!capsIsCapabilityListing && hasTableIssues) {
+    if (!capsIsCapabilityListing && hasTableEntryIssues) {
       if (capsMode === 'module') {
         // module 模式：added 为聚合后的未覆盖目录，需人工登记目录条目
         jsonOutput.added = result.added.map(d => ({ dir: d }));
@@ -341,6 +351,19 @@ export async function syncDocs(
       }
     }
 
+    if (hasTableLayoutIssues) {
+      jsonOutput.tableLayout = {
+        blankLines: tableLayout.blankLines,
+        emptyTables: tableLayout.emptyTables,
+      };
+      (jsonOutput.resolution as Array<Record<string, unknown>>).push({
+        action: 'sync-capabilities-table-layout',
+        command: 'harness sync-docs',
+        details:
+          'CAPABILITIES.md 的表格被空行切断、或残留无数据行的空表头，运行 harness sync-docs 收拢',
+      });
+    }
+
     if (hasContextIssues) {
       (jsonOutput.resolution as Array<Record<string, unknown>>).push(
         ...(result.contextMissing.length > 0
@@ -400,6 +423,16 @@ export async function syncDocs(
     result.removed.forEach(f => log(io, chalk.gray(`  - ${f}`)));
   }
 
+  if (hasTableLayoutIssues) {
+    log(io, chalk.yellow(`\n🧹 CAPABILITIES.md 表格排版待收拢:`));
+    if (tableLayout.blankLines > 0) {
+      log(io, chalk.gray(`  - 表格内空行 ${tableLayout.blankLines} 处（CommonMark 会在此把表格切断）`));
+    }
+    if (tableLayout.emptyTables > 0) {
+      log(io, chalk.gray(`  - 无数据行的空表 ${tableLayout.emptyTables} 张（连表头/分隔行一起收掉）`));
+    }
+  }
+
   if (result.contextMissing.length > 0) {
     log(io, chalk.yellow(`\n📋 缺少 CONTEXT.md:`));
     result.contextMissing.forEach(d => log(io, chalk.gray(`  - ${d}/CONTEXT.md`)));
@@ -450,10 +483,14 @@ export async function syncDocs(
   if (isCheck) {
     log(io, chalk.red('\n❌ 文档不是最新的，请运行 harness sync-docs 更新'));
     // reason 必须可定位（harness#142）：CI 判红时要直接拿到文件与符号，不靠翻 stdout
+    const tableLayoutReason = hasTableLayoutIssues
+      ? `；CAPABILITIES.md 表格排版待收拢（表格内空行 ${tableLayout.blankLines} 处、`
+        + `空表 ${tableLayout.emptyTables} 张）`
+      : '';
     return drift(
       contextDriftReason
-        ? `文档不是最新的（CONTEXT.md 与实现漂移：${contextDriftReason}）`
-        : '文档不是最新的，请运行 harness sync-docs 更新'
+        ? `文档不是最新的（CONTEXT.md 与实现漂移：${contextDriftReason}）${tableLayoutReason}`
+        : `文档不是最新的，请运行 harness sync-docs 更新${tableLayoutReason}`
     );
   }