@dommaker/harness 1.7.0 → 1.8.1

package/src/cli/commands/__tests__/status.test.ts

@@ -3,10 +3,12 @@
  *
  * ADR-0020 起不再 mock TraceAnalyzer/TraceCollector：统计与异常由 trace-analyzer
  * 的模块级纯函数真算，用例喂合法 trace 行、断言真实输出。
+ * ADR-0026 起状态文件读写经注入的 StateIO 假件，不碰（被 mock 的）fs。
  */
 
-import { status } from '../status';
-import { captureIO, type CapturingIO } from '../../command-contract';
+import { status, type StatusOptions } from '../status';
+import { captureIO, type CapturingIO, type CommandResult } from '../../command-contract';
+import type { HarnessState, StateIO } from '../../state-io';
 import * as fs from 'fs';
 import type { ExecutionTrace } from '../../../types/trace';
 
@@ -42,10 +44,27 @@ function repeats(constraintId: string, n: number, result: ExecutionTrace['result
 }
 
 let io: CapturingIO;
+let stateIO: ReturnType<typeof memoryStateIO>;
 beforeEach(() => {
   io = captureIO();
+  stateIO = memoryStateIO();
 });
 
+/** 内存 StateIO 假件（ADR-0026）：状态读写走注入面，缺省 fileStateIO 在全 mock 的 fs 下会吃到 trace 假数据 */
+function memoryStateIO(initial: HarnessState = {}): StateIO & { snapshot(): HarnessState } {
+  let state = initial;
+  return {
+    read: () => state,
+    write: (next: HarnessState) => { state = next; },
+    snapshot: () => state,
+  };
+}
+
+/** 全部用例经注入假件调用 status（stateIO 可被单例覆盖以预置状态） */
+function runStatus(options: StatusOptions = {}): Promise<CommandResult> {
+  return status({ stateIO, ...options }, io);
+}
+
 describe('status command', () => {
 
   beforeEach(() => {
@@ -59,7 +78,7 @@ describe('status command', () => {
   describe('未初始化情况', () => {
     it('应该显示未初始化提示', async () => {
       mockFs.existsSync.mockReturnValue(false);
-      await status({}, io);
+      await runStatus();
       expect(io.outText()).toContain('未初始化');
     });
   });
@@ -71,7 +90,7 @@ describe('status command', () => {
         .mockReturnValueOnce(true) // .harness dir
         .mockReturnValueOnce(false); // traces file
 
-      await status({}, io);
+      await runStatus();
       expect(io.outText()).toContain('暂无 Trace');
     });
   });
@@ -83,7 +102,7 @@ describe('status command', () => {
         { constraintId: 'test2', level: 'guideline' },
       ]));
 
-      await status({}, io);
+      await runStatus();
       expect(io.outText()).toContain('记录数: 2 条');
       expect(io.outText()).toContain('📈 约束统计:');
     });
@@ -93,7 +112,7 @@ describe('status command', () => {
         { constraintId: 'no_bypass_checkpoint' },
       ]));
 
-      await status({ detail: true }, io);
+      await runStatus({ detail: true });
       expect(io.outText()).toContain('🔴 Iron Laws:');
       expect(io.outText()).toContain('✅ no_bypass_checkpoint');
       expect(io.outText()).toContain('检查: 1 | 通过: 100% | 失败: 0%');
@@ -106,7 +125,7 @@ describe('status command', () => {
         { constraintId: 'test1', result: 'fail' },
       ]));
 
-      await status({ anomalies: true }, io);
+      await runStatus({ anomalies: true });
       expect(io.outText()).toContain('发现 1 个异常');
       expect(io.outText()).toContain('  test1');
       expect(io.outText()).toContain('类型: low_pass_rate');
@@ -120,17 +139,26 @@ describe('status command', () => {
         { constraintId: 'test1', result: 'fail' },
       ]));
 
-      await status({ detail: true }, io);
+      await runStatus({ detail: true });
       expect(io.outText()).toContain('检查: 5 | 通过: 80% | 失败: 20%');
     });
   });
 
   describe('状态文件更新', () => {
-    it('应该更新 .state.json', async () => {
+    it('应该经 StateIO 写入 lastStatusRun', async () => {
+      mockFs.readFileSync.mockReturnValue(traceFile([{ constraintId: 'test' }]));
+
+      await runStatus();
+      expect(stateIO.snapshot().lastStatusRun).toBeTruthy();
+    });
+
+    it('读-改-写：已有的 shownHints 不被 status 抹掉（ADR-0026 决策 2 的行为修复）', async () => {
       mockFs.readFileSync.mockReturnValue(traceFile([{ constraintId: 'test' }]));
+      stateIO = memoryStateIO({ shownHints: ['trace_50'] });
 
-      await status({}, io);
-      expect(mockFs.writeFileSync).toHaveBeenCalled();
+      await runStatus();
+      expect(stateIO.snapshot().shownHints).toEqual(['trace_50']);
+      expect(stateIO.snapshot().lastStatusRun).toBeTruthy();
     });
   });
 
@@ -140,7 +168,7 @@ describe('status command', () => {
         { constraintId: 'test_guide', level: 'guideline' },
       ]));
 
-      await status({}, io);
+      await runStatus();
       expect(io.outText()).toContain('🟡 Guidelines:');
       expect(io.outText()).toContain('✅ test_guide');
     });
@@ -150,7 +178,7 @@ describe('status command', () => {
     it('应该显示未发现异常当无异常', async () => {
       mockFs.readFileSync.mockReturnValue(traceFile([{ constraintId: 'test' }]));
 
-      await status({ anomalies: true }, io);
+      await runStatus({ anomalies: true });
       expect(io.outText()).toContain('✅ 未发现异常');
     });
 
@@ -159,7 +187,7 @@ describe('status command', () => {
         { constraintId: 'test', result: 'fail' },
       ]));
 
-      await status({ anomalies: true }, io);
+      await runStatus({ anomalies: true });
       expect(io.outText()).toContain('当前值: 0');
       expect(io.outText()).toContain('阈值: 0.3');
       expect(io.outText()).toContain('下一步建议');
@@ -170,7 +198,7 @@ describe('status command', () => {
     it('应该显示良好建议当 trace >= 100', async () => {
       mockFs.readFileSync.mockReturnValue(traceFile(repeats('test', 100, 'pass')));
 
-      await status({}, io);
+      await runStatus();
       expect(io.outText()).toContain('记录数: 100 条');
       expect(io.outText()).toContain('状态良好');
     });
@@ -178,7 +206,7 @@ describe('status command', () => {
     it('应该显示积累数据建议当 trace < 100', async () => {
       mockFs.readFileSync.mockReturnValue(traceFile([{ constraintId: 'test' }]));
 
-      await status({}, io);
+      await runStatus();
       expect(io.outText()).toContain('继续积累数据');
     });
 
@@ -187,7 +215,7 @@ describe('status command', () => {
         { constraintId: 'test', result: 'fail' },
       ]));
 
-      await status({ anomalies: true }, io);
+      await runStatus({ anomalies: true });
       expect(io.outText()).toContain('harness status --detail');
     });
   });
@@ -199,7 +227,7 @@ describe('status command', () => {
         ...repeats('test_guide', 2, 'fail'),
       ].map(t => ({ ...t, level: 'guideline' as const }))));
 
-      await status({ detail: true }, io);
+      await runStatus({ detail: true });
       expect(io.outText()).toContain('⚠️ test_guide');
       expect(io.outText()).toContain('检查: 5 | 通过: 60% | 失败: 40%');
     });

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

@@ -5,18 +5,33 @@
 import * as fs from 'fs';
 import { captureIO, type CapturingIO } from '../../command-contract';
 import * as path from 'path';
+import * as os from 'os';
 import { syncDocs } from '../sync-docs';
 
+/**
+ * 环境固定：CONTEXT.md 的 mtime 过时判定在 CI 下被有意关掉（#142——全新 checkout 的 mtime
+ * 由 clone 顺序决定，比出来的「过时」是假灯）。本文件的夹具都是现场写的、断言的是本地行为，
+ * 所以环境必须由用例自己声明，不能跟着跑测试的机器走（否则同一份代码在开发机绿、在 CI 红）。
+ * 「CI 下关掉 mtime 判定」这条规则本身由 sync-docs-context-drift.test.ts 负责验证。
+ */
+const SAVED_CI = process.env.CI;
+
 let io: CapturingIO;
 beforeEach(() => {
   io = captureIO();
+  delete process.env.CI;
+});
+
+afterEach(() => {
+  if (SAVED_CI === undefined) delete process.env.CI;
+  else process.env.CI = SAVED_CI;
 });
 
 describe('sync-docs --agents', () => {
-  const tempDir = path.join(process.cwd(), 'temp-test-sync-docs-agents');
+  let tempDir: string;
 
   beforeAll(() => {
-    fs.mkdirSync(tempDir, { recursive: true });
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'temp-test-sync-docs-agents-'));
   });
 
   afterAll(() => {
@@ -489,11 +504,11 @@ describe('sync-docs --agents', () => {
     expect(parsed.resolution.some((r: { action: string }) => r.action === 'update-context-md')).toBe(true);
     expect(parsed.agentsMd).toEqual({ file: 'AGENTS.md', exists: false, stale: true });
 
-    // 人读模式：输出过时提示
+    // 人读模式：mtime 差异只给提示（harness#142 降级），判失败的是缺失
     io = captureIO();
     const humanResult = await syncDocs({ projectPath: testDir, agents: true, check: true }, io);
     expect(humanResult).toEqual({ kind: 'fail', reason: expect.stringContaining('文档不是最新') });
-    expect(io.outText()).toContain('可能过时');
+    expect(io.outText()).toContain('源码比文档新');
     expect(io.outText()).toContain('缺少 CONTEXT.md');
 
     fs.rmSync(testDir, { recursive: true, force: true });

package/src/cli/commands/__tests__/sync-docs-context-drift.test.ts

@@ -0,0 +1,232 @@
+/**
+ * sync-docs 的 CONTEXT.md 内容漂移判定接线测试（harness#142）
+ *
+ * 钉四件事：
+ * 1. 内容漂移（幽灵 / barrel 未登记）在 `--check` 下判 fail，reason 点名文件与符号；
+ * 2. mtime 漂移降级为本地提示——不再影响退出码，且 CI 环境下连提示都抑制；
+ * 3. `--json` 有 contentDrift 结构（供 LLM/CI 消费）；
+ * 4. 写入模式不改写 CONTEXT.md（散文不可机械生成），退出码面不变。
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { captureIO, type CapturingIO, type CommandResult } from '../../command-contract';
+import { syncDocs } from '../sync-docs';
+
+jest.mock('chalk', () => ({
+  blue: jest.fn((s: string) => s),
+  yellow: jest.fn((s: string) => s),
+  green: jest.fn((s: string) => s),
+  gray: jest.fn((s: string) => s),
+  red: jest.fn((s: string) => s),
+  cyan: jest.fn((s: string) => s),
+  bold: jest.fn((s: string) => s),
+}));
+
+/** 取 fail 的 reason（判别联合窄化只在测试里做一次） */
+function failReason(result: CommandResult): string {
+  if (result.kind !== 'fail' && result.kind !== 'usage-error') {
+    throw new Error(`期望 fail，实得 ${result.kind}`);
+  }
+  return result.reason;
+}
+
+let tempDir: string;
+const CI = process.env.CI;
+
+let io: CapturingIO;
+
+/** 建一个「CAPABILITIES 已覆盖 src/」的最小项目，把漂移轴隔离到 CONTEXT.md */
+function makeProject(name: string, contextMd: string, indexTs: string): string {
+  const projectPath = path.join(tempDir, name);
+  const modDir = path.join(projectPath, 'src', 'mod');
+  fs.mkdirSync(modDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(projectPath, 'CAPABILITIES.md'),
+    '# Capabilities\n\n| 模块 | 文件 | 说明 |\n|------|------|------|\n| all | src/ | 全量记录 |\n'
+  );
+  fs.writeFileSync(path.join(modDir, 'CONTEXT.md'), contextMd);
+  fs.writeFileSync(path.join(modDir, 'index.ts'), indexTs);
+  fs.writeFileSync(
+    path.join(modDir, 'impl.ts'),
+    'export class Widget {}\nexport function createWidget() {}\nexport const WIDGET_KIND = "a";\n'
+  );
+  return projectPath;
+}
+
+const CLEAN_DOC = [
+  '# mod/',
+  '',
+  '## 核心导出',
+  '- `Widget` — 主体',
+  '- `createWidget` — 工厂',
+  '- `WIDGET_KIND` — 常量',
+  '',
+  '## 约定',
+  '- 无',
+  '',
+].join('\n');
+
+const BARREL = [
+  "export { Widget, createWidget, WIDGET_KIND } from './impl';",
+  "export type { WidgetConfig } from './impl';",
+].join('\n');
+
+beforeEach(() => {
+  io = captureIO();
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'temp-test-sync-docs-drift-'));
+  delete process.env.CI;
+});
+
+afterEach(() => {
+  fs.rmSync(tempDir, { recursive: true, force: true });
+  if (CI === undefined) delete process.env.CI;
+  else process.env.CI = CI;
+});
+
+describe('sync-docs — CONTEXT.md 内容漂移判 fail（--check）', () => {
+  it('文档与导出面一致 → ok（新闸不制造存量噪音）', async () => {
+    const projectPath = makeProject('clean', CLEAN_DOC, BARREL);
+    await expect(syncDocs({ projectPath, check: true }, io)).resolves.toEqual({ kind: 'ok' });
+  });
+
+  it('幽灵符号（代码改名不回灌文档）→ fail 并指名文件与符号', async () => {
+    const projectPath = makeProject(
+      'ghost',
+      CLEAN_DOC.replace('`Widget`', '`WidgetRenamed`'),
+      BARREL
+    );
+
+    const result = await syncDocs({ projectPath, check: true }, io);
+
+    expect(failReason(result)).toContain('src/mod/CONTEXT.md');
+    expect(failReason(result)).toContain('WidgetRenamed');
+    expect(io.outText()).toContain('WidgetRenamed');
+  });
+
+  it('barrel 未跟着改名的虚再导出不洗白幽灵（正本改名即撞）', async () => {
+    const projectPath = makeProject('ghost-barrel', CLEAN_DOC, BARREL);
+    // 只改声明侧（Widget → WidgetSink），index.ts 的再导出与文档都不动
+    fs.writeFileSync(
+      path.join(projectPath, 'src', 'mod', 'impl.ts'),
+      'export class WidgetSink {}\nexport function createWidget() {}\nexport const WIDGET_KIND = "a";\n'
+    );
+
+    const result = await syncDocs({ projectPath, check: true }, io);
+
+    expect(failReason(result)).toContain('src/mod/CONTEXT.md');
+    expect(failReason(result)).toContain('Widget');
+  });
+
+  it('barrel 新增值符号未登记 → fail 并指名该符号', async () => {
+    const projectPath = makeProject(
+      'unlisted',
+      CLEAN_DOC.replace('- `WIDGET_KIND` — 常量\n', ''),
+      BARREL
+    );
+
+    const result = await syncDocs({ projectPath, check: true }, io);
+
+    expect(failReason(result)).toContain('src/mod/CONTEXT.md');
+    expect(failReason(result)).toContain('WIDGET_KIND');
+  });
+
+  it('barrel 新增类型符号 → 不要求登记（类型面豁免）', async () => {
+    const projectPath = makeProject(
+      'type-only',
+      CLEAN_DOC,
+      [BARREL, "export { type ExtraShape } from './impl';"].join('\n')
+    );
+
+    await expect(syncDocs({ projectPath, check: true }, io)).resolves.toEqual({ kind: 'ok' });
+  });
+
+  it('无 index.ts 的目录跳过覆盖方向（内部导出不要求登记）', async () => {
+    const projectPath = makeProject('no-barrel', CLEAN_DOC, BARREL);
+    fs.rmSync(path.join(projectPath, 'src', 'mod', 'index.ts'));
+
+    await expect(syncDocs({ projectPath, check: true }, io)).resolves.toEqual({ kind: 'ok' });
+  });
+});
+
+describe('sync-docs — mtime 判定降级为提示', () => {
+  /** 只把源码时间戳推到 CONTEXT.md 之后，内容一字不改 */
+  function touchSourceLater(projectPath: string): void {
+    const contextPath = path.join(projectPath, 'src', 'mod', 'CONTEXT.md');
+    const contextMtime = new Date(Date.now() - 60_000);
+    fs.utimesSync(contextPath, contextMtime, contextMtime);
+    const impl = path.join(projectPath, 'src', 'mod', 'impl.ts');
+    const later = new Date();
+    fs.utimesSync(impl, later, later);
+  }
+
+  it('mtime 漂移不再判 fail，只在本地给提示', async () => {
+    const projectPath = makeProject('mtime', CLEAN_DOC, BARREL);
+    touchSourceLater(projectPath);
+
+    await expect(syncDocs({ projectPath, check: true }, io)).resolves.toEqual({ kind: 'ok' });
+    expect(io.outText()).toContain('源码比文档新');
+  });
+
+  it('CI 环境下 mtime 提示抑制（全新 checkout 的 mtime 无意义）', async () => {
+    const projectPath = makeProject('mtime-ci', CLEAN_DOC, BARREL);
+    touchSourceLater(projectPath);
+    process.env.CI = 'true';
+
+    await expect(syncDocs({ projectPath, check: true }, io)).resolves.toEqual({ kind: 'ok' });
+    expect(io.outText()).not.toContain('源码比文档新');
+  });
+
+  it('内容漂移在 CI 环境下照样 fail', async () => {
+    const projectPath = makeProject('content-ci', CLEAN_DOC.replace('`Widget`', '`Gone`'), BARREL);
+    process.env.CI = 'true';
+
+    const result = await syncDocs({ projectPath, check: true }, io);
+    expect(failReason(result)).toContain('Gone');
+  });
+});
+
+describe('sync-docs — --json 与写入模式', () => {
+  it('--json 输出 contentDrift（dir/file/ghosts/unlisted）', async () => {
+    const projectPath = makeProject(
+      'json',
+      CLEAN_DOC.replace('- `WIDGET_KIND` — 常量\n', '').replace('`Widget`', '`Ghost`'),
+      BARREL
+    );
+
+    await syncDocs({ projectPath, check: true, json: true }, io);
+
+    const payload = JSON.parse(io.outText());
+    expect(payload.stale).toBe(true);
+    expect(payload.summary.contextContentDrift).toBe(1);
+    expect(payload.contentDrift).toEqual([
+      {
+        dir: 'src/mod',
+        file: 'src/mod/CONTEXT.md',
+        ghosts: ['Ghost'],
+        unlisted: ['Widget', 'WIDGET_KIND'],
+      },
+    ]);
+  });
+
+  it('--json 干净时 contentDrift 为空数组', async () => {
+    const projectPath = makeProject('json-clean', CLEAN_DOC, BARREL);
+
+    await syncDocs({ projectPath, check: true, json: true }, io);
+
+    expect(JSON.parse(io.outText()).contentDrift).toEqual([]);
+  });
+
+  it('写入模式给提示但不改 CONTEXT.md、退出码面不变', async () => {
+    const projectPath = makeProject('write', CLEAN_DOC.replace('`Widget`', '`Ghost`'), BARREL);
+    const contextPath = path.join(projectPath, 'src', 'mod', 'CONTEXT.md');
+    const before = fs.readFileSync(contextPath, 'utf-8');
+
+    const result = await syncDocs({ projectPath }, io);
+
+    expect(result.kind).toBe('ok');
+    expect(io.outText()).toContain('Ghost');
+    expect(fs.readFileSync(contextPath, 'utf-8')).toBe(before);
+  });
+});

package/src/cli/commands/__tests__/sync-docs-module-order.test.ts

@@ -0,0 +1,111 @@
+/**
+ * sync-docs 生成的模块清单顺序冻结（#147 B 票）
+ *
+ * `sync-docs` 写出的 CAPABILITIES.md 模块表格行序 = 源码目录遍历序，这个顺序此前
+ * **无任何测试覆盖**，而它对外可见（`--check` 逐行比对、人工看 diff）。#147 把描述
+ * 提取从串行改并发，票面裁决「输出顺序逐字保持现状」，本文件就是那条裁决的闸。
+ *
+ * 不写死字面顺序：`readdir` 的返回顺序由文件系统决定（本仓 tmpfs 上是字典序、ext4 上
+ * 是哈希序），写死等于把断言建立在机器上。这里的口径是**目录遍历序**本身——用测试内
+ * 独立推导的遍历序（`readdirSync` + 同一份跳过口径）作对照，另加两次运行的自复现，
+ * 任何「按并发完成顺序 append」「改成字典序」「子目录结果挪到末尾」都会撞红。
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { syncDocs } from '../sync-docs';
+import { scanSourceModules } from '../sync-docs/project-reader';
+import { captureIO } from '../../command-contract';
+import { DEFAULT_SKIP_DIRS, isTsSourceFile } from '../../../utils/file-walk';
+
+let tempDir: string;
+const io = captureIO();
+
+function write(rel: string, content: string): void {
+  const target = path.join(tempDir, rel);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, content, 'utf-8');
+}
+
+/** 口径对照：目录遍历序 = readdir 序，子目录结果就地展开在父条目所在位置 */
+function traversalOrder(dir: string, root: string): string[] {
+  const out: string[] = [];
+  for (const entry of fs.readdirSync(dir)) {
+    if (DEFAULT_SKIP_DIRS.includes(entry)) continue;
+    const entryPath = path.join(dir, entry);
+    if (fs.statSync(entryPath).isDirectory()) {
+      out.push(...traversalOrder(entryPath, root));
+    } else if (isTsSourceFile(entry, { skipIndex: true, includeTsx: true })) {
+      out.push(path.relative(root, entryPath));
+    }
+  }
+  return out;
+}
+
+/** 生成后的 CAPABILITIES.md 表格行序（文件列） */
+function tableRows(capabilitiesPath: string): string[] {
+  return fs
+    .readFileSync(capabilitiesPath, 'utf-8')
+    .split('\n')
+    .filter((line) => /^\|[^|]+\|[^|]+\.tsx?\s*\|[^|]+\|\s*$/.test(line))
+    .map((line) => line.split('|')[2].trim());
+}
+
+beforeAll(() => {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'sd147-module-order-'));
+  // 一个子目录恰好排在两份顶层文件之间（顺序若被重排，这里最容易露馅）
+  write('src/alpha.ts', '// 描述-甲\nexport const a = 1;\n');
+  write('src/mid/beta.ts', '/**\n * 描述-乙\n */\nexport const b = 1;\n');
+  write('src/mid/gamma.ts', '// 描述-丙\nexport const c = 1;\n');
+  write('src/zeta.ts', '// 描述-丁\nexport const d = 1;\n');
+  // 同一条规则下的旁支：barrel 与 .d.ts 不进清单
+  write('src/index.ts', 'export * from "./alpha";\n');
+  write('src/ambient.d.ts', 'export const t = 1;\n');
+});
+
+afterAll(() => {
+  fs.rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe('sync-docs 模块清单顺序冻结（#147）', () => {
+  it('扫描产出的清单顺序 = 目录遍历序，且描述与文件配对不串位', async () => {
+    const modules = await scanSourceModules(path.join(tempDir, 'src'), tempDir);
+    const expected = traversalOrder(path.join(tempDir, 'src'), tempDir);
+
+    expect(modules.map((m) => m.file)).toEqual(expected);
+    // 并发取数后每条描述仍是自己那份文件的（回填按原索引，不按完成先后）
+    expect(modules.map((m) => `${m.file}=${m.description}`).sort()).toEqual(
+      [
+        'src/alpha.ts=描述-甲',
+        'src/mid/beta.ts=描述-乙',
+        'src/mid/gamma.ts=描述-丙',
+        'src/zeta.ts=描述-丁',
+      ].sort()
+    );
+  });
+
+  it('写出的 CAPABILITIES.md 行序 = 同一次扫描的清单顺序（对外可见面被锁住）', async () => {
+    const capPath = path.join(tempDir, 'CAPABILITIES.md');
+    expect(fs.existsSync(capPath)).toBe(false);
+
+    await syncDocs({ projectPath: tempDir }, io);
+
+    expect(tableRows(capPath)).toEqual(traversalOrder(path.join(tempDir, 'src'), tempDir));
+  });
+
+  it('同一次生成的清单顺序两次运行逐字复现（并发不引入运行间抖动）', async () => {
+    const capPath = path.join(tempDir, 'CAPABILITIES.md');
+
+    fs.rmSync(capPath, { force: true });
+    await syncDocs({ projectPath: tempDir }, io);
+    const first = tableRows(capPath);
+    expect(first.length).toBe(4);
+
+    fs.rmSync(capPath, { force: true });
+    await syncDocs({ projectPath: tempDir }, io);
+
+    expect(tableRows(capPath)).toEqual(first);
+    fs.rmSync(capPath, { force: true });
+  });
+});