@dommaker/harness 1.3.0 → 1.4.0

package/src/knowledge/__tests__/flywheel-metrics.test.ts

@@ -0,0 +1,135 @@
+/**
+ * 知识飞轮指标纯判定测试（harness#81）
+ *
+ * interface 即测试面：喂 active 条目数组 + 可选消费事件数，断言 canonical 指标，零 fs。
+ * 口径正本 = genuine refs（过滤 synthetic 后）：此前 audit/stats/health 三处各自实现分子计算，
+ * stats/health 用原始 referencedBy.length 把自动化触碰算成消费，同一库报出两套飞轮健康度。
+ */
+
+import { describe, it, expect } from '@jest/globals';
+import { evaluateFlywheel, genuineRefs } from '../flywheel-metrics';
+import type { KnowledgeEntry } from '../types';
+
+function makeEntry(id: string, referencedBy: string[]): KnowledgeEntry {
+  return {
+    id,
+    type: 'guideline',
+    title: `entry ${id}`,
+    content: 'meaningful content long enough to survive every audit threshold',
+    maturity: 'verified',
+    layer: 'project',
+    created: '2026-09-01T00:00:00.000Z',
+    lastReferenced: '2026-09-01T00:00:00.000Z',
+    contributors: ['human'],
+    projects: ['harness'],
+    tags: [],
+    applicablePhases: [],
+    sourceReferences: [],
+    referencedBy,
+    executionResults: [],
+    consumptionMode: 'reference',
+    origin: 'agent',
+  };
+}
+
+// ── genuineRefs：synthetic 过滤口径 ─────────────────────
+
+describe('genuineRefs — synthetic 过滤口径', () => {
+  for (const prefix of [
+    'search', 'test-agent', 'prompt-inject', 'monitor',
+    'analyst', 'auditor', 'triage', 'executor', 'session', 'trend', 'incident',
+  ]) {
+    it(`过滤自动化写入方 ${prefix}:<date>`, () => {
+      expect(genuineRefs([`${prefix}:2026-09-01`])).toEqual([]);
+    });
+  }
+
+  it('保留人/决策类引用（含同前缀但非日期键的历史写法）', () => {
+    const refs = [
+      'agent-a:2026-09-01',
+      'decision-123',
+      'unknown:2026-09-01',
+      'search:not-a-date',
+      'xsearch:2026-09-01',
+    ];
+    expect(genuineRefs(refs)).toEqual([
+      'agent-a:2026-09-01',
+      'decision-123',
+      'unknown:2026-09-01',
+      'search:not-a-date',
+      'xsearch:2026-09-01',
+    ]);
+  });
+
+  it('无结束锚点：日期后带后缀的自动化键同样过滤', () => {
+    expect(genuineRefs(['search:2026-09-01:extra'])).toEqual([]);
+  });
+
+  it('不改动入参数组（纯函数，不过滤掉调用方数据）', () => {
+    const refs = ['agent-a:2026-09-01', 'search:2026-09-01'];
+    genuineRefs(refs);
+    expect(refs).toHaveLength(2);
+  });
+});
+
+// ── evaluateFlywheel：canonical 指标 ────────────────────
+
+describe('evaluateFlywheel — 引用侧指标', () => {
+  it('refCoverage / avgRefs 为未取整比例，分子只数 genuine refs', () => {
+    const metrics = evaluateFlywheel({
+      entries: [
+        makeEntry('K-001', ['agent-a:2026-09-01', 'search:2026-09-01']),
+        makeEntry('K-002', ['prompt-inject:2026-08-30', 'test-agent:2026-08-31']),
+        makeEntry('K-003', []),
+        makeEntry('K-004', ['decision-1:2026-07-01', 'studio-web:2026-07-02']),
+      ],
+    });
+
+    // 2/4 条目有真实引用；genuine refs 共 3 条 / 4 条目
+    expect(metrics.activeEntries).toBe(4);
+    expect(metrics.entriesWithRefs).toBe(2);
+    expect(metrics.refCoverage).toBe(0.5);
+    expect(metrics.avgRefs).toBe(0.75);
+  });
+
+  it('纯 synthetic 引用不给条目续命（覆盖与均值都归零）', () => {
+    const metrics = evaluateFlywheel({
+      entries: [makeEntry('K-001', ['search:2026-09-01', 'analyst:2026-09-01'])],
+    });
+    expect(metrics.entriesWithRefs).toBe(0);
+    expect(metrics.refCoverage).toBe(0);
+    expect(metrics.avgRefs).toBe(0);
+  });
+
+  it('空人口 → 全 0，不出 NaN / 不做除零', () => {
+    const metrics = evaluateFlywheel({ entries: [], dailyConsumptionEvents: 10 });
+    expect(metrics).toMatchObject({
+      activeEntries: 0,
+      entriesWithRefs: 0,
+      refCoverage: 0,
+      avgRefs: 0,
+      consumptionHitRate: 0,
+    });
+  });
+
+  it('不改动传入条目（人口筛选属调用方，本 module 零副作用）', () => {
+    const entries = [makeEntry('K-001', ['agent-a:2026-09-01', 'search:2026-09-01'])];
+    const before = JSON.stringify(entries);
+    evaluateFlywheel({ entries });
+    expect(JSON.stringify(entries)).toBe(before);
+  });
+});
+
+describe('evaluateFlywheel — 消费命中率', () => {
+  it('未传消费事件 → 0，输入值原样透传便于报告层复用', () => {
+    const metrics = evaluateFlywheel({ entries: [makeEntry('K-001', ['agent-a:2026-09-01'])] });
+    expect(metrics.dailyConsumptionEvents).toBe(0);
+    expect(metrics.consumptionHitRate).toBe(0);
+  });
+
+  it('dailyEvents / activeEntries，capped at 1', () => {
+    const entries = [makeEntry('K-001', []), makeEntry('K-002', [])];
+    expect(evaluateFlywheel({ entries, dailyConsumptionEvents: 1 }).consumptionHitRate).toBe(0.5);
+    expect(evaluateFlywheel({ entries, dailyConsumptionEvents: 99 }).consumptionHitRate).toBe(1);
+  });
+});

package/src/knowledge/__tests__/import.test.ts

@@ -308,6 +308,23 @@ describe('ColdStartImporter', () => {
       // 非 git 目录应该有错误但不崩溃
       expect(results.length).toBe(1);
     });
+
+    it('不应执行结果被丢弃的大型重构扫描命令（harness#111 死代码）', async () => {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const execSpy = jest.spyOn(require('child_process'), 'execSync').mockReturnValue('');
+      try {
+        const importer = new ColdStartImporter({
+          projectRoot: tmpDir,
+          store,
+          sources: ['git'],
+        });
+        await importer.importAll();
+        const commands = execSpy.mock.calls.map(call => String(call[0]));
+        expect(commands.some(cmd => cmd.includes('diff-filter=M'))).toBe(false);
+      } finally {
+        execSpy.mockRestore();
+      }
+    });
   });
 
   describe('importFromDocs - 目录', () => {
@@ -373,4 +390,31 @@ describe('ColdStartImporter', () => {
       expect(importer.getState().totalImported).toBe(0);
     });
   });
+
+  describe('批量写入收口（harness#107）', () => {
+    it('多条目导入经 saveAll 一次落索引，不再逐条 save', async () => {
+      const importer = new ColdStartImporter({
+        projectRoot: tmpDir,
+        store,
+        sources: ['manual'],
+        manualEntries: [
+          { title: 'Entry A', content: 'Content A', type: 'guideline' },
+          { title: 'Entry B', content: 'Content B', type: 'guideline' },
+        ],
+      });
+
+      const saveAllSpy = jest.spyOn(store, 'saveAll');
+      const saveSpy = jest.spyOn(store, 'save');
+      try {
+        const results = await importer.importAll();
+        expect(results[0].entries).toHaveLength(2);
+        expect(saveAllSpy).toHaveBeenCalledTimes(1);
+        expect(saveSpy).not.toHaveBeenCalled();
+      } finally {
+        saveAllSpy.mockRestore();
+        saveSpy.mockRestore();
+      }
+      expect(store.list()).toHaveLength(2);
+    });
+  });
 });

package/src/knowledge/__tests__/index-generator.test.ts

@@ -332,4 +332,57 @@ Extra text
       expect(lines[0]).toContain('real.md');
     });
   });
+
+  describe('frontmatter 收口（harness#89）', () => {
+    let errorSpy: jest.SpyInstance;
+
+    beforeEach(() => {
+      errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+      errorSpy.mockRestore();
+    });
+
+    it('正文里的 --- 分隔线不误吞：headings 取自闭合之后的正文', () => {
+      fs.writeFileSync(
+        path.join(tmpDir, 'decision-SEP-001.md'),
+        '---\nid: SEP-001\ntype: decision\ntitle: "Sep"\nmaturity: verified\ntags: []\n---\n\n## 前段\n\n---\n\n## 附录\n',
+      );
+
+      const fields = new KnowledgeIndexGenerator(tmpDir).generateIndexLines()[0].split('|');
+      expect(fields).toHaveLength(7);
+      expect(fields[6]).toBe('前段;附录');
+      expect(errorSpy).not.toHaveBeenCalled();
+    });
+
+    it('未闭合：按无 frontmatter best-effort 索引，并显式上报一行（不再静默）', () => {
+      fs.writeFileSync(path.join(tmpDir, 'decision-OPEN-001.md'), '---\nid: OPEN-001\n# 断掉的头\n\n## 附录\n');
+
+      const fields = new KnowledgeIndexGenerator(tmpDir).generateIndexLines()[0].split('|');
+      expect(fields[1]).toBe('decision-OPEN-001');
+      expect(fields[4]).toBe('unknown');
+      expect(errorSpy).toHaveBeenCalledTimes(1);
+      expect(errorSpy.mock.calls[0][0]).toMatch(/\[harness\].*unterminated.*decision-OPEN-001\.md/);
+    });
+
+    it('YAML 非法：best-effort 索引 + 显式上报 invalid-yaml', () => {
+      fs.writeFileSync(path.join(tmpDir, 'decision-BAD-001.md'), '---\nid: [1,\n---\n\n正文\n');
+
+      const fields = new KnowledgeIndexGenerator(tmpDir).generateIndexLines()[0].split('|');
+      expect(fields[1]).toBe('decision-BAD-001');
+      expect(errorSpy).toHaveBeenCalledTimes(1);
+      expect(errorSpy.mock.calls[0][0]).toMatch(/\[harness\].*invalid-yaml/);
+    });
+
+    it('空 meta：与缺 frontmatter 同走 absent——静默 best-effort，标题取 H1', () => {
+      fs.writeFileSync(path.join(tmpDir, 'decision-EMPTY-001.md'), '---\n\n---\n\n# 空头条目\n\n## 小节\n');
+
+      const fields = new KnowledgeIndexGenerator(tmpDir).generateIndexLines()[0].split('|');
+      expect(fields[1]).toBe('decision-EMPTY-001');
+      expect(fields[3]).toBe('空头条目');
+      expect(fields[6]).toBe('小节');
+      expect(errorSpy).not.toHaveBeenCalled();
+    });
+  });
 });

package/src/knowledge/__tests__/ingest.test.ts

@@ -127,6 +127,62 @@ describe('KnowledgeIngest', () => {
       expect(entries).toHaveLength(2);
       expect(store.list()).toHaveLength(2);
     });
+
+    it('同类型条目 id 序号批内递增（harness#107）', () => {
+      const entries = ingest.ingestBatch(
+        [
+          { title: 'First', type: 'decision' },
+          { title: 'Second', type: 'decision' },
+          { title: 'Third', type: 'decision' },
+        ],
+        { source: 'test', layer: 'project' },
+      );
+      expect(entries.map(e => e.id)).toEqual(['DEC-001', 'DEC-002', 'DEC-003']);
+    });
+  });
+
+  describe('generateId 走索引计数（harness#107）', () => {
+    it('不再经 store.list() 逐条读条目文件', () => {
+      const listSpy = jest.spyOn(store, 'list');
+      try {
+        ingest.ingestEntry(
+          { title: 'Test', content: 'Content', type: 'decision' },
+          { source: 'test', layer: 'project' },
+        );
+        expect(listSpy).not.toHaveBeenCalled();
+      } finally {
+        listSpy.mockRestore();
+      }
+    });
+
+    it('archived/deprecated 条目不计入序号（与 list 默认过滤口径一致）', () => {
+      store.save({
+        id: 'DEC-001',
+        type: 'decision',
+        title: 'Archived One',
+        content: 'Original',
+        maturity: 'draft',
+        layer: 'project',
+        created: '2026-05-01T00:00:00.000Z',
+        lastReferenced: '',
+        contributors: [],
+        projects: [],
+        tags: [],
+        applicablePhases: [],
+        sourceReferences: [],
+        referencedBy: [],
+        executionResults: [],
+        consumptionMode: 'reference',
+        origin: 'agent',
+      });
+      store.update('DEC-001', { maturity: 'archived' });
+
+      const entry = ingest.ingestEntry(
+        { title: 'Fresh', content: 'Content', type: 'decision' },
+        { source: 'test', layer: 'project' },
+      );
+      expect(entry.id).toBe('DEC-001');
+    });
   });
 
   describe('findDuplicate reads from disk (A1)', () => {
@@ -273,6 +329,35 @@ describe('KnowledgeIngest', () => {
       expect(store.list({ types: ['pitfall'] })).toHaveLength(2);
     });
 
+    it('正文首行以 --- 开头但不是 frontmatter 时不误吞分隔线（harness#89 回归）', () => {
+      // 两条正文首行是 `--- 说明…`（不是整行 ---，故 absent），中间各有一条 --- 分隔线。
+      // 收口前的手写 strip 把正文里那条 --- 当成闭合，吞掉前面的说明行，
+      // 于是两条的 dedup 前缀都变成同一段尾巴 → 误判重复。
+      const tail = '端口 3001 与 13101 不一致导致 session:archive 事件无法送达，责任归属是启动配置未校验端口。';
+      store.save({
+        id: 'PIT-091', type: 'pitfall', title: '甲乙丙丁子网掩码配置漂移一',
+        content: `--- 说明：这一段以三个连字符开头，但它不是 frontmatter\n\n---\n\n${tail}\n`,
+        maturity: 'draft', layer: 'system',
+        created: '2026-05-28T00:00:00.000Z', lastReferenced: '',
+        contributors: [], projects: [], tags: [], applicablePhases: [],
+        sourceReferences: [], referencedBy: [],
+        executionResults: [],
+        consumptionMode: 'reference',
+        origin: 'agent',
+      });
+
+      ingest.ingestEntry(
+        {
+          title: '戊己庚辛存储配额阈值设定二',
+          content: `--- 另一段同样以三个连字符开头的说明文字，形态与上面完全对称\n\n---\n\n${tail}\n`,
+          type: 'pitfall',
+        },
+        { source: 'test', layer: 'system' },
+      );
+
+      expect(store.list({ types: ['pitfall'] })).toHaveLength(2);
+    });
+
     it('should detect duplicate by title keyword overlap >= 60%', () => {
       store.save({
         id: 'PIT-030', type: 'pitfall', title: 'Prisma 连接超时导致 API 请求失败',

package/src/knowledge/__tests__/migration.test.ts

@@ -106,4 +106,51 @@ describe('migrateKnowledgeEntries', () => {
     expect(second.migrated).toBe(0);
     expect(second.skipped).toBe(1);
   });
+
+  describe('frontmatter 收口（harness#89）', () => {
+    it('缺 frontmatter：errors 记 no frontmatter（原文案不变），不算损坏', () => {
+      fs.writeFileSync(path.join(tempDir, 'PLAIN.md'), '# 只是普通 markdown\n\n正文\n', 'utf-8');
+
+      const result = migrateKnowledgeEntries(tempDir);
+      expect(result.errors).toEqual(['PLAIN.md: no frontmatter found']);
+      expect(result.migrated).toBe(0);
+    });
+
+    it('空 meta：与缺 frontmatter 同走一支（absent），不静默丢', () => {
+      fs.writeFileSync(path.join(tempDir, 'EMPTY-META.md'), '---\n\n---\n\nBody\n', 'utf-8');
+
+      const result = migrateKnowledgeEntries(tempDir);
+      expect(result.errors).toEqual(['EMPTY-META.md: no frontmatter found']);
+    });
+
+    it('未闭合：errors 显式记 unterminated（收口前是一条 YAML 内部报错）', () => {
+      fs.writeFileSync(path.join(tempDir, 'OPEN.md'), '---\nid: OPEN\ntype: decision\n', 'utf-8');
+
+      const result = migrateKnowledgeEntries(tempDir);
+      expect(result.errors).toHaveLength(1);
+      expect(result.errors[0]).toMatch(/^OPEN\.md: frontmatter unterminated \(.+\)$/);
+    });
+
+    it('YAML 非法：errors 显式记 invalid-yaml 并带上可定位 detail', () => {
+      fs.writeFileSync(path.join(tempDir, 'BAD.md'), '---\nid: [1,\n---\n\nBody\n', 'utf-8');
+
+      const result = migrateKnowledgeEntries(tempDir);
+      expect(result.errors).toHaveLength(1);
+      expect(result.errors[0]).toMatch(/^BAD\.md: frontmatter invalid-yaml \(.+\)$/);
+    });
+
+    it('写回走正本包裹格式：首尾分隔线与空行逐字一致，二次运行字节不变（无 diff 噪声）', () => {
+      writeEntry('DEC-005.md', { id: 'DEC-005', type: 'decision', title: 'T' });
+
+      expect(migrateKnowledgeEntries(tempDir).migrated).toBe(1);
+      const afterFirst = fs.readFileSync(path.join(tempDir, 'DEC-005.md'), 'utf-8');
+
+      expect(afterFirst.startsWith('---\nid: DEC-005\n')).toBe(true);
+      expect(afterFirst).toContain('---\n\nBody content');
+      expect(afterFirst).toMatch(/^---\n[\s\S]*\n---\n\n/);
+
+      expect(migrateKnowledgeEntries(tempDir).migrated).toBe(0);
+      expect(fs.readFileSync(path.join(tempDir, 'DEC-005.md'), 'utf-8')).toBe(afterFirst);
+    });
+  });
 });

package/src/knowledge/__tests__/reference-tracker.test.ts

@@ -125,6 +125,22 @@ describe('ReferenceTracker', () => {
       expect(tracker.getReferencesForEntry('any')).toEqual([]);
     });
 
+    it('单行损坏只丢该行，合法记录保留（harness#82：原「坏一行丢全部」改 skip）', () => {
+      const filePath = path.join(tempDir, 'references.jsonl');
+      fs.writeFileSync(
+        filePath,
+        [
+          JSON.stringify({ decisionId: 'decision-1', entryIds: ['entry-1'], timestamp: '2026-09-03' }),
+          'NOT VALID JSON',
+          JSON.stringify({ decisionId: 'decision-2', entryIds: ['entry-2'], timestamp: '2026-09-03' }),
+        ].join('\n') + '\n',
+        'utf-8'
+      );
+      expect(tracker.getReferencesForEntry('entry-1')).toEqual(['decision-1']);
+      expect(tracker.getReferencesForEntry('entry-2')).toEqual(['decision-2']);
+      expect(tracker.getReferencesForDecision('decision-2')).toEqual(['entry-2']);
+    });
+
     it('should return empty when file does not exist', () => {
       expect(tracker.getReferencesForDecision('any')).toEqual([]);
     });

package/src/knowledge/__tests__/store.test.ts

@@ -455,4 +455,198 @@ describe('KnowledgeStore', () => {
       expect(result!.total).toBe(2);
     });
   });
+
+  describe('readIndex memoize（harness#106）', () => {
+    // fs.readFileSync 不可 spy（Node 21+ 不可 redefine）；list/readIndex 路径上
+    // JSON.parse 仅用于解析 index.json，用其调用次数度量 index 重读次数
+    it('list() 单次调用内 index.json 只解析一次（消除 N+1 重读）', () => {
+      store.save(makeEntry({ id: 'DEC-001' }));
+      store.save(makeEntry({ id: 'DEC-002', title: 'Second' }));
+
+      const parseSpy = jest.spyOn(JSON, 'parse');
+      try {
+        store.list();
+        expect(parseSpy).toHaveBeenCalledTimes(1);
+      } finally {
+        parseSpy.mockRestore();
+      }
+    });
+
+    it('readIndex() 重复调用命中缓存，不重复解析', () => {
+      store.save(makeEntry({ id: 'DEC-001' }));
+
+      const parseSpy = jest.spyOn(JSON, 'parse');
+      try {
+        store.readIndex();
+        store.readIndex();
+        expect(parseSpy).toHaveBeenCalledTimes(1);
+      } finally {
+        parseSpy.mockRestore();
+      }
+    });
+
+    it('index.json 变更后缓存自动失效（mtime+size 指纹）', () => {
+      store.save(makeEntry({ id: 'DEC-001' }));
+      const first = store.readIndex();
+      expect(first).toHaveLength(1);
+
+      // 模拟外部进程直接改写 index.json
+      const indexPath = path.join(tempDir, 'index.json');
+      const external = [...first, { ...first[0], id: 'DEC-EXT' }];
+      fs.writeFileSync(indexPath, JSON.stringify(external, null, 2), 'utf-8');
+
+      const second = store.readIndex();
+      expect(second.map(e => e.id)).toContain('DEC-EXT');
+    });
+
+    it('index.json 被删除后缓存失效，readIndex 返回空', () => {
+      store.save(makeEntry({ id: 'DEC-001' }));
+      expect(store.readIndex()).toHaveLength(1);
+
+      fs.unlinkSync(path.join(tempDir, 'index.json'));
+      expect(store.readIndex()).toHaveLength(0);
+    });
+  });
+
+  describe('saveAll 批量写入（harness#107）', () => {
+    // writeIndex 是 store 内 JSON.stringify 的唯一调用方，用其调用次数度量 index.json 重写次数
+    it('K 条批量保存只重写一次 index.json', () => {
+      const stringifySpy = jest.spyOn(JSON, 'stringify');
+      try {
+        store.saveAll([
+          makeEntry({ id: 'DEC-001' }),
+          makeEntry({ id: 'DEC-002', title: 'Second' }),
+          makeEntry({ id: 'DEC-003', title: 'Third' }),
+        ]);
+        expect(stringifySpy).toHaveBeenCalledTimes(1);
+      } finally {
+        stringifySpy.mockRestore();
+      }
+      expect(store.readIndex()).toHaveLength(3);
+      expect(store.get('DEC-002')!.title).toBe('Second');
+    });
+
+    it('批量保存只读一次 index.json', () => {
+      store.save(makeEntry({ id: 'DEC-001' }));
+
+      const parseSpy = jest.spyOn(JSON, 'parse');
+      try {
+        store.saveAll([
+          makeEntry({ id: 'DEC-002', title: 'Second' }),
+          makeEntry({ id: 'DEC-003', title: 'Third' }),
+        ]);
+        expect(parseSpy).toHaveBeenCalledTimes(1);
+      } finally {
+        parseSpy.mockRestore();
+      }
+      expect(store.readIndex()).toHaveLength(3);
+    });
+
+    it('覆盖已存在同 id 条目，索引不产生重复', () => {
+      store.save(makeEntry({ id: 'DEC-001', title: 'Old' }));
+
+      store.saveAll([
+        makeEntry({ id: 'DEC-001', title: 'New' }),
+        makeEntry({ id: 'DEC-002' }),
+      ]);
+
+      expect(store.readIndex()).toHaveLength(2);
+      expect(store.get('DEC-001')!.title).toBe('New');
+    });
+
+    it('批内同 id 后者覆盖前者', () => {
+      store.saveAll([
+        makeEntry({ id: 'DEC-001', title: 'First' }),
+        makeEntry({ id: 'DEC-001', title: 'Last' }),
+      ]);
+
+      expect(store.readIndex()).toHaveLength(1);
+      expect(store.get('DEC-001')!.title).toBe('Last');
+    });
+
+    it('空批零读写，不创建 index.json', () => {
+      const stringifySpy = jest.spyOn(JSON, 'stringify');
+      try {
+        store.saveAll([]);
+        expect(stringifySpy).not.toHaveBeenCalled();
+      } finally {
+        stringifySpy.mockRestore();
+      }
+      expect(fs.existsSync(path.join(tempDir, 'index.json'))).toBe(false);
+    });
+
+    it('saveAll 后 list() 立即可见（缓存指纹失效）', () => {
+      store.save(makeEntry({ id: 'DEC-001' }));
+      expect(store.list()).toHaveLength(1); // 预热缓存
+
+      store.saveAll([makeEntry({ id: 'DEC-002' }), makeEntry({ id: 'DEC-003' })]);
+
+      expect(store.list().map(e => e.id)).toEqual(['DEC-001', 'DEC-002', 'DEC-003']);
+    });
+  });
+
+  describe('frontmatter 收口（harness#89）', () => {
+    const entryPath = (id: string): string => path.join(tempDir, `decision-${id}.md`);
+    let errorSpy: jest.SpyInstance;
+
+    beforeEach(() => {
+      errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+      errorSpy.mockRestore();
+    });
+
+    it('load→save 往返字节稳定：已落盘条目不产生无意义 diff', () => {
+      store.save(makeEntry({ id: 'FM-001' }));
+      const before = fs.readFileSync(entryPath('FM-001'), 'utf-8');
+
+      const loaded = store.get('FM-001')!;
+      store.save(loaded);
+
+      expect(fs.readFileSync(entryPath('FM-001'), 'utf-8')).toBe(before);
+    });
+
+    it('正文含 --- 分隔线的条目往返字节稳定，正文完整保留', () => {
+      const body = '第一段\n\n---\n\n## 附录\n末行\n';
+      store.save(makeEntry({ id: 'FM-002', content: body }));
+      const before = fs.readFileSync(entryPath('FM-002'), 'utf-8');
+
+      const loaded = store.get('FM-002')!;
+      expect(loaded.content).toBe(body);
+      store.save(loaded);
+
+      expect(fs.readFileSync(entryPath('FM-002'), 'utf-8')).toBe(before);
+    });
+
+    it('未闭合 frontmatter：跳过条目并显式上报（不再静默丢，口径与 migration 同派）', () => {
+      fs.writeFileSync(entryPath('FM-003'), '---\nid: FM-003\ntype: decision\n', 'utf-8');
+
+      expect(store.get('FM-003')).toBeUndefined();
+      expect(errorSpy).toHaveBeenCalledTimes(1);
+      expect(errorSpy.mock.calls[0][0]).toMatch(/\[harness\].*unterminated/);
+    });
+
+    it('YAML 非法 frontmatter：跳过条目并显式上报', () => {
+      fs.writeFileSync(entryPath('FM-004'), '---\nid: [1,\n---\n\nBody\n', 'utf-8');
+
+      expect(store.get('FM-004')).toBeUndefined();
+      expect(errorSpy).toHaveBeenCalledTimes(1);
+      expect(errorSpy.mock.calls[0][0]).toMatch(/\[harness\].*invalid-yaml/);
+    });
+
+    it('空 meta：按无 frontmatter 处理（absent）——跳过且不上报', () => {
+      fs.writeFileSync(entryPath('FM-005'), '---\n\n---\n\nBody\n', 'utf-8');
+
+      expect(store.get('FM-005')).toBeUndefined();
+      expect(errorSpy).not.toHaveBeenCalled();
+    });
+
+    it('缺 frontmatter：合法的非条目文件——跳过且不上报', () => {
+      fs.writeFileSync(entryPath('FM-006'), '# 只是普通 markdown\n\n正文\n', 'utf-8');
+
+      expect(store.get('FM-006')).toBeUndefined();
+      expect(errorSpy).not.toHaveBeenCalled();
+    });
+  });
 });