@dommaker/harness 1.6.0 → 1.8.0

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

@@ -4,6 +4,7 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
+import * as os from 'os';
 import { FileKnowledgeStore as KnowledgeStore } from '../store';
 import { KnowledgeLinter } from '../lint';
 import { ReferenceTracker } from '../reference-tracker';
@@ -11,14 +12,14 @@ import { KnowledgeHealthScorer } from '../doctor';
 import type { KnowledgeEntry } from '../types';
 
 describe('KnowledgeHealthScorer', () => {
-  const tempDir = path.join(process.cwd(), 'temp-test-knowledge-doctor');
+  let tempDir: string;
   let store: KnowledgeStore;
   let tracker: ReferenceTracker;
   let linter: KnowledgeLinter;
   let scorer: KnowledgeHealthScorer;
 
   beforeAll(() => {
-    fs.mkdirSync(tempDir, { recursive: true });
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'temp-test-knowledge-doctor-'));
   });
 
   afterAll(() => {

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

@@ -7,14 +7,15 @@ import { FileKnowledgeStore as KnowledgeStore } from '../store';
 import { KnowledgeIngest } from '../ingest';
 import * as fs from 'fs';
 import * as path from 'path';
+import * as os from 'os';
 
 describe('KnowledgeIngest', () => {
-  const tempDir = path.join(process.cwd(), 'temp-test-ingest');
+  let tempDir: string;
   let store: KnowledgeStore;
   let ingest: KnowledgeIngest;
 
   beforeAll(() => {
-    fs.mkdirSync(tempDir, { recursive: true });
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'temp-test-ingest-'));
   });
 
   afterAll(() => {

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

@@ -8,9 +8,10 @@ import { KnowledgeLifecycle } from '../lifecycle';
 import type { KnowledgeEntry } from '../types';
 import * as fs from 'fs';
 import * as path from 'path';
+import * as os from 'os';
 
 describe('KnowledgeLifecycle', () => {
-  const tempDir = path.join(process.cwd(), 'temp-test-lifecycle');
+  let tempDir: string;
   let store: KnowledgeStore;
   let lifecycle: KnowledgeLifecycle;
 
@@ -36,7 +37,7 @@ describe('KnowledgeLifecycle', () => {
   });
 
   beforeAll(() => {
-    fs.mkdirSync(tempDir, { recursive: true });
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'temp-test-lifecycle-'));
   });
 
   afterAll(() => {
@@ -396,6 +397,27 @@ describe('KnowledgeLifecycle', () => {
       expect(changes[0].from).toBe('proven');
       expect(changes[0].to).toBe('verified');
     });
+
+    it('一次 cycle 的 K 条衰减只重写一次 index.json（harness#134 走 applyAll）', () => {
+      const oldDate = new Date();
+      oldDate.setMonth(oldDate.getMonth() - 4);
+      for (const id of ['DEC-001', 'DEC-002', 'DEC-003']) {
+        store.save(makeEntry({ id, maturity: 'draft', lastReferenced: oldDate.toISOString() }));
+      }
+
+      const stringifySpy = jest.spyOn(JSON, 'stringify');
+      try {
+        const changes = lifecycle.runDecayCycle();
+        // 正对照：3 条真衰减，否则「1 次重写」是空跑出来的
+        expect(changes.map(c => c.entryId)).toEqual(['DEC-001', 'DEC-002', 'DEC-003']);
+        expect(stringifySpy).toHaveBeenCalledTimes(1);
+      } finally {
+        stringifySpy.mockRestore();
+      }
+      for (const id of ['DEC-001', 'DEC-002', 'DEC-003']) {
+        expect(store.get(id)!.maturity).toBe('archived');
+      }
+    });
   });
 
   describe('tryPromote', () => {
@@ -732,6 +754,39 @@ describe('KnowledgeLifecycle', () => {
       expect(lifecycle.checkEntryDecay('RULE-001')).toBe('deprecated');
     });
 
+    it('边界钉：成功率恰 0.5（失败率恰 50%）即降级（harness#161 修边界差一）', () => {
+      store.save(makeEntry({
+        id: 'RULE-001',
+        consumptionMode: 'rule',
+        maturity: 'active',
+        content: 'API port must be 13101',
+        executionResults: [
+          { contributor: 'alice', success: true, timestamp: '2026-05-01T00:00:00.000Z' },
+          { contributor: 'bob', success: false, timestamp: '2026-05-02T00:00:00.000Z' },
+          { contributor: 'charlie', success: true, timestamp: '2026-05-03T00:00:00.000Z' },
+          { contributor: 'dave', success: false, timestamp: '2026-05-04T00:00:00.000Z' },
+        ],
+      }));
+      expect(lifecycle.checkEntryDecay('RULE-001')).toBe('deprecated');
+    });
+
+    it('成功率略高于 0.5（3 成 2 败）不降级', () => {
+      store.save(makeEntry({
+        id: 'RULE-001',
+        consumptionMode: 'rule',
+        maturity: 'active',
+        content: 'API port must be 13101',
+        executionResults: [
+          { contributor: 'alice', success: true, timestamp: '2026-05-01T00:00:00.000Z' },
+          { contributor: 'bob', success: true, timestamp: '2026-05-02T00:00:00.000Z' },
+          { contributor: 'charlie', success: true, timestamp: '2026-05-03T00:00:00.000Z' },
+          { contributor: 'dave', success: false, timestamp: '2026-05-04T00:00:00.000Z' },
+          { contributor: 'erin', success: false, timestamp: '2026-05-05T00:00:00.000Z' },
+        ],
+      }));
+      expect(lifecycle.checkEntryDecay('RULE-001')).toBeUndefined();
+    });
+
     it('should NOT decay active→deprecated when fail rate < 50%', () => {
       store.save(makeEntry({
         id: 'RULE-001',

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

@@ -6,12 +6,13 @@ import { describe, it, expect, beforeAll, afterAll, beforeEach } from '@jest/glo
 import { migrateKnowledgeEntries } from '../migration';
 import * as fs from 'fs';
 import * as path from 'path';
+import * as os from 'os';
 
 describe('migrateKnowledgeEntries', () => {
-  const tempDir = path.join(process.cwd(), 'temp-test-migration');
+  let tempDir: string;
 
   beforeAll(() => {
-    fs.mkdirSync(tempDir, { recursive: true });
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'temp-test-migration-'));
   });
 
   afterAll(() => {
@@ -107,20 +108,48 @@ describe('migrateKnowledgeEntries', () => {
     expect(second.skipped).toBe(1);
   });
 
+  describe('知识树生成物豁免（harness#134 walker 口径单点化）', () => {
+    it('_index.md 既不计入 total 也不计入 errors（修此前的假阳性）', () => {
+      // 真实组合：knowledge index 把生成物落在同一个 baseDir，无 frontmatter
+      fs.writeFileSync(
+        path.join(tempDir, '_index.md'),
+        '# Knowledge Base Index\n# Auto-generated\n\n# filename|id|type\n',
+        'utf-8'
+      );
+      writeEntry('DEC-010.md', {
+        id: 'DEC-010', type: 'decision', title: 'Test', maturity: 'draft',
+        layer: 'project', created: '2026-05-01', lastReferenced: '',
+        contributors: [], projects: [], tags: [], applicablePhases: [],
+        sourceReferences: [], referencedBy: [], executionResults: [],
+      });
+
+      const result = migrateKnowledgeEntries(tempDir);
+      expect(result.total).toBe(1);
+      expect(result.errors).toEqual([]);
+      expect(result.migrated).toBe(1);
+      // 生成物不被改写
+      expect(fs.readFileSync(path.join(tempDir, '_index.md'), 'utf-8'))
+        .toContain('# Auto-generated');
+    });
+  });
+
   describe('frontmatter 收口（harness#89）', () => {
-    it('缺 frontmatter：errors 记 no frontmatter（原文案不变），不算损坏', () => {
+    it('缺 frontmatter：absent 是合法输入——不进 errors，按非条目语义计入 skipped（harness#161 裁决，正本 #89 裁决 2）', () => {
       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.errors).toEqual([]);
       expect(result.migrated).toBe(0);
+      expect(result.skipped).toBe(1);
+      expect(result.total).toBe(1);
     });
 
-    it('空 meta：与缺 frontmatter 同走一支（absent），不静默丢', () => {
+    it('空 meta：与缺 frontmatter 同走一支（absent），不进 errors、计 skipped', () => {
       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']);
+      expect(result.errors).toEqual([]);
+      expect(result.skipped).toBe(1);
     });
 
     it('未闭合：errors 显式记 unterminated（收口前是一条 YAML 内部报错）', () => {

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

@@ -8,9 +8,10 @@ import { KnowledgeQuery } from '../query';
 import type { KnowledgeEntry, QueryBudget } from '../types';
 import * as fs from 'fs';
 import * as path from 'path';
+import * as os from 'os';
 
 describe('KnowledgeQuery', () => {
-  const tempDir = path.join(process.cwd(), 'temp-test-query');
+  let tempDir: string;
   let store: KnowledgeStore;
   let query: KnowledgeQuery;
 
@@ -36,7 +37,7 @@ describe('KnowledgeQuery', () => {
   });
 
   beforeAll(() => {
-    fs.mkdirSync(tempDir, { recursive: true });
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'temp-test-query-'));
   });
 
   afterAll(() => {

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

@@ -8,9 +8,10 @@ import { ReferenceTracker } from '../reference-tracker';
 import type { KnowledgeEntry } from '../types';
 import * as fs from 'fs';
 import * as path from 'path';
+import * as os from 'os';
 
 describe('ReferenceTracker', () => {
-  const tempDir = path.join(process.cwd(), 'temp-test-refs');
+  let tempDir: string;
   let store: KnowledgeStore;
   let tracker: ReferenceTracker;
 
@@ -36,7 +37,7 @@ describe('ReferenceTracker', () => {
   });
 
   beforeAll(() => {
-    fs.mkdirSync(tempDir, { recursive: true });
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'temp-test-refs-'));
   });
 
   afterAll(() => {
@@ -116,6 +117,26 @@ describe('ReferenceTracker', () => {
       expect(e1!.referencedBy).toContain('decision-2');
       expect(e2!.referencedBy).toEqual(['decision-2']);
     });
+
+    it('K 条 referencedBy 更新只重写一次 index.json（harness#134 走 applyAll）', () => {
+      for (const id of ['entry-1', 'entry-2', 'entry-3']) {
+        store.save(makeEntry({ id }));
+      }
+      tracker.record('decision-1', ['entry-1', 'entry-2', 'entry-3']);
+
+      const stringifySpy = jest.spyOn(JSON, 'stringify');
+      try {
+        tracker.updateReferencedBy();
+        expect(stringifySpy).toHaveBeenCalledTimes(1);
+      } finally {
+        stringifySpy.mockRestore();
+      }
+
+      // 正对照：3 条真写入，否则「1 次重写」是空跑出来的
+      for (const id of ['entry-1', 'entry-2', 'entry-3']) {
+        expect(store.get(id)!.referencedBy).toEqual(['decision-1']);
+      }
+    });
   });
 
   describe('edge cases', () => {

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

@@ -7,9 +7,10 @@ import { FileKnowledgeStore as KnowledgeStore } from '../store';
 import type { KnowledgeEntry } from '../types';
 import * as fs from 'fs';
 import * as path from 'path';
+import * as os from 'os';
 
 describe('KnowledgeStore', () => {
-  const tempDir = path.join(process.cwd(), 'temp-test-knowledge');
+  let tempDir: string;
   let store: KnowledgeStore;
 
   const makeEntry = (overrides?: Partial<KnowledgeEntry>): KnowledgeEntry => ({
@@ -34,7 +35,7 @@ describe('KnowledgeStore', () => {
   });
 
   beforeAll(() => {
-    fs.mkdirSync(tempDir, { recursive: true });
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'temp-test-knowledge-'));
   });
 
   afterAll(() => {
@@ -224,10 +225,11 @@ describe('KnowledgeStore', () => {
     });
 
     it('should create directory if it does not exist', () => {
-      const newDir = path.join(process.cwd(), 'temp-test-knowledge-nested', 'sub', 'deep');
+      const root = fs.mkdtempSync(path.join(os.tmpdir(), 'temp-test-knowledge-nested-'));
+      const newDir = path.join(root, 'sub', 'deep');
       new KnowledgeStore({ baseDir: newDir });
       expect(fs.existsSync(newDir)).toBe(true);
-      fs.rmSync(path.join(process.cwd(), 'temp-test-knowledge-nested'), { recursive: true, force: true });
+      fs.rmSync(root, { recursive: true, force: true });
     });
 
     it('should handle corrupt index.json gracefully', () => {
@@ -585,6 +587,149 @@ describe('KnowledgeStore', () => {
     });
   });
 
+  describe('applyAll 按 id 部分更新的批量出口（harness#134）', () => {
+    it('K 条部分更新只重写一次 index.json', () => {
+      store.saveAll([
+        makeEntry({ id: 'DEC-001' }),
+        makeEntry({ id: 'DEC-002', title: 'Second' }),
+        makeEntry({ id: 'DEC-003', title: 'Third' }),
+      ]);
+
+      const stringifySpy = jest.spyOn(JSON, 'stringify');
+      try {
+        store.applyAll([
+          { id: 'DEC-001', partial: { maturity: 'archived' } },
+          { id: 'DEC-002', partial: { maturity: 'draft' } },
+          { id: 'DEC-003', partial: { tags: ['low_quality'] } },
+        ]);
+        expect(stringifySpy).toHaveBeenCalledTimes(1);
+      } finally {
+        stringifySpy.mockRestore();
+      }
+    });
+
+    it('只改给到的字段，其余字段原样保留（与 update() 同语义）', () => {
+      store.save(makeEntry({ id: 'DEC-001', title: 'Keep Me', contributors: ['a'], tags: ['t1'] }));
+
+      store.applyAll([{ id: 'DEC-001', partial: { maturity: 'archived' } }]);
+
+      const after = store.get('DEC-001')!;
+      expect(after.maturity).toBe('archived');
+      expect(after.title).toBe('Keep Me');
+      expect(after.contributors).toEqual(['a']);
+      expect(after.tags).toEqual(['t1']);
+      expect(after.content).toBe('This is a test decision.');
+    });
+
+    it('id 不可被 partial 改写（与 update() 同语义）', () => {
+      store.save(makeEntry({ id: 'DEC-001' }));
+      store.applyAll([{ id: 'DEC-001', partial: { id: 'HACKED' as never } }]);
+
+      expect(store.get('DEC-001')!.id).toBe('DEC-001');
+      expect(store.get('HACKED')).toBeUndefined();
+      expect(store.readIndex().map(e => e.id)).toEqual(['DEC-001']);
+    });
+
+    it('未知 id 跳过：不写文件、索引不增项，其余条目照常落盘', () => {
+      store.save(makeEntry({ id: 'DEC-001' }));
+
+      store.applyAll([
+        { id: 'GHOST', partial: { maturity: 'archived' } },
+        { id: 'DEC-001', partial: { maturity: 'archived' } },
+      ]);
+
+      expect(fs.existsSync(path.join(tempDir, 'decision-GHOST.md'))).toBe(false);
+      expect(store.readIndex().map(e => e.id)).toEqual(['DEC-001']);
+      expect(store.get('DEC-001')!.maturity).toBe('archived');
+    });
+
+    it('批内同 id 多条：按顺序累积合并（后者不覆盖前者已改的字段）', () => {
+      store.save(makeEntry({ id: 'DEC-001', tags: ['t1'] }));
+
+      store.applyAll([
+        { id: 'DEC-001', partial: { maturity: 'archived' } },
+        { id: 'DEC-001', partial: { tags: ['t1', 'low_quality'] } },
+      ]);
+
+      const after = store.get('DEC-001')!;
+      expect(after.maturity).toBe('archived');
+      expect(after.tags).toEqual(['t1', 'low_quality']);
+      expect(store.readIndex()).toHaveLength(1);
+    });
+
+    it('空批零读写，不创建 index.json', () => {
+      const stringifySpy = jest.spyOn(JSON, 'stringify');
+      try {
+        store.applyAll([]);
+        expect(stringifySpy).not.toHaveBeenCalled();
+      } finally {
+        stringifySpy.mockRestore();
+      }
+      expect(fs.existsSync(path.join(tempDir, 'index.json'))).toBe(false);
+    });
+
+    it('applyAll 后 list() 立即可见（缓存指纹失效）', () => {
+      store.save(makeEntry({ id: 'DEC-001' }));
+      expect(store.list()).toHaveLength(1); // 预热缓存
+
+      store.applyAll([{ id: 'DEC-001', partial: { maturity: 'archived' } }]);
+
+      expect(store.list({ excludeArchived: false })[0].maturity).toBe('archived');
+    });
+
+    it('与逐条 update() 的落盘结果逐字节相同（只是少重写索引）', () => {
+      const updates = [
+        { id: 'DEC-001', partial: { maturity: 'archived' as const } },
+        { id: 'DEC-002', partial: { tags: ['x'] } },
+      ];
+      store.save(makeEntry({ id: 'DEC-001' }));
+      store.save(makeEntry({ id: 'DEC-002' }));
+      for (const u of updates) store.update(u.id, u.partial);
+      const perEntry = {
+        md1: fs.readFileSync(path.join(tempDir, 'decision-DEC-001.md'), 'utf-8'),
+        md2: fs.readFileSync(path.join(tempDir, 'decision-DEC-002.md'), 'utf-8'),
+        index: fs.readFileSync(path.join(tempDir, 'index.json'), 'utf-8'),
+      };
+
+      const fresh = new KnowledgeStore({ baseDir: tempDir });
+      fresh.save(makeEntry({ id: 'DEC-001' }));
+      fresh.save(makeEntry({ id: 'DEC-002' }));
+      fresh.applyAll(updates);
+      expect({
+        md1: fs.readFileSync(path.join(tempDir, 'decision-DEC-001.md'), 'utf-8'),
+        md2: fs.readFileSync(path.join(tempDir, 'decision-DEC-002.md'), 'utf-8'),
+        index: fs.readFileSync(path.join(tempDir, 'index.json'), 'utf-8'),
+      }).toEqual(perEntry);
+    });
+  });
+
+  describe('getConsumptionStats（harness#134：打分核心的 IO 归 store 供给）', () => {
+    const statsPath = (): string => path.join(tempDir, '.consumption-stats.json');
+
+    it('文件不存在 → undefined（未提供即无消费数据，不是 0 条记录）', () => {
+      expect(store.getConsumptionStats()).toBeUndefined();
+    });
+
+    it('读出 dailyEvents 供 D6 打分', () => {
+      fs.writeFileSync(
+        statsPath(),
+        JSON.stringify({ date: '2026-09-15', dailyEvents: 12, searchHits: 5 }),
+        'utf-8'
+      );
+      expect(store.getConsumptionStats()).toEqual({ dailyEvents: 12 });
+    });
+
+    it('坏 JSON → undefined，不抛（沿用直读侧 best-effort 语义）', () => {
+      fs.writeFileSync(statsPath(), 'NOT VALID JSON{{{', 'utf-8');
+      expect(store.getConsumptionStats()).toBeUndefined();
+    });
+
+    it('缺 dailyEvents 字段 → 0（有文件但无该计数）', () => {
+      fs.writeFileSync(statsPath(), JSON.stringify({ date: '2026-09-15' }), 'utf-8');
+      expect(store.getConsumptionStats()).toEqual({ dailyEvents: 0 });
+    });
+  });
+
   describe('frontmatter 收口（harness#89）', () => {
     const entryPath = (id: string): string => path.join(tempDir, `decision-${id}.md`);
     let errorSpy: jest.SpyInstance;

package/src/knowledge/__tests__/tree-walker.test.ts

@@ -0,0 +1,132 @@
+/**
+ * 知识树 walker 排除口径单点化（harness#134，架构评审候选 4）
+ *
+ * 判据不是「各文件有没有抄同一份常量」，而是**同一份知识树在四个入口下得到同一份条目人口**：
+ * store 顶层扫描、migration 顶层扫描、index-generator 递归扫描此前各有各的排除口径，
+ * 后果是 `harness knowledge index` 落在 baseDir 的 `_index.md`（生成物、无 frontmatter）
+ * 被 `harness knowledge migrate` 判成「no frontmatter found」计入 errors——同一份树，
+ * `store.list()` 报 1 条、`migrateKnowledgeEntries` 报 total 2 / errors 1。
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { isEntryFile, isInfraDir, INDEX_MD_FILE, SNAPSHOTS_DIR } from '../tree-walker';
+import { FileKnowledgeStore } from '../store';
+import { KnowledgeIndexGenerator } from '../index-generator';
+import { migrateKnowledgeEntries } from '../migration';
+import type { KnowledgeEntry } from '../types';
+
+function makeEntry(overrides: Partial<KnowledgeEntry> = {}): KnowledgeEntry {
+  return {
+    id: 'TREE-001',
+    type: 'guideline',
+    title: 'Tree Walker Entry',
+    content: '内容足够长以通过各口径的判定阈值要求'.repeat(3),
+    maturity: 'verified',
+    layer: 'project',
+    created: '2026-09-01T00:00:00.000Z',
+    lastReferenced: '2026-09-01T00:00:00.000Z',
+    contributors: ['a'],
+    projects: ['p'],
+    tags: [],
+    applicablePhases: [],
+    sourceReferences: [],
+    referencedBy: [],
+    executionResults: [],
+    consumptionMode: 'reference',
+    origin: 'agent',
+    ...overrides,
+  };
+}
+
+describe('tree-walker 谓词', () => {
+  it('条目文件判定：仅 .md 且非生成物', () => {
+    expect(isEntryFile('guideline-A.md')).toBe(true);
+    expect(isEntryFile(INDEX_MD_FILE)).toBe(false);
+    expect(isEntryFile('notes.txt')).toBe(false);
+    expect(isEntryFile('index.json')).toBe(false);
+  });
+
+  it('基建目录判定：归档/快照/resolution 都不是条目人口', () => {
+    for (const dir of ['.archive', 'archived', SNAPSHOTS_DIR, 'resolutions']) {
+      expect(isInfraDir(dir)).toBe(true);
+    }
+    expect(isInfraDir('skills')).toBe(false);
+    expect(isInfraDir('.harness')).toBe(false);
+  });
+});
+
+describe('四个 walker 的条目人口一致（同一份树）', () => {
+  let dir: string;
+
+  /**
+   * 平铺知识库：2 个真条目 + 全部基建产物（_index.md / .snapshots / .archive / resolutions）
+   * 只放平铺层，因为 store 与 migration 本就是顶层扫描器、index-generator 会下钻业务子目录——
+   * 本票统一的是**排除口径**，不是递归深度。
+   */
+  function buildTree(): void {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'tree-walker-'));
+    const store = new FileKnowledgeStore({ baseDir: dir });
+    store.save(makeEntry({ id: 'TREE-001' }));
+    store.save(makeEntry({ id: 'TREE-002', type: 'pitfall', title: 'Another Entry' }));
+
+    for (const sub of ['.snapshots', '.archive', 'resolutions']) {
+      fs.mkdirSync(path.join(dir, sub), { recursive: true });
+    }
+    fs.writeFileSync(
+      path.join(dir, '.snapshots', 'index-2026-08-01.json'),
+      JSON.stringify([{ id: 'TREE-001', type: 'guideline' }]),
+      'utf-8'
+    );
+    // 基建目录里的 .md 带着合法 frontmatter：口径若漏了排除，它们会冒充条目
+    const fakeEntry = (id: string): string =>
+      `---\nid: ${id}\ntype: pitfall\ntitle: Ghost ${id}\nmaturity: verified\nlayer: project\n` +
+      `created: 2026-08-01T00:00:00.000Z\nlastReferenced: ''\ncontributors: []\nprojects: []\n` +
+      `tags: []\napplicablePhases: []\nsourceReferences: []\nreferencedBy: []\nexecutionResults: []\n` +
+      `consumptionMode: reference\norigin: agent\n---\n\nGhost body\n`;
+    fs.writeFileSync(path.join(dir, '.archive', 'ghost.md'), fakeEntry('GHOST-ARCHIVE'), 'utf-8');
+    fs.writeFileSync(path.join(dir, 'resolutions', 'ghost.md'), fakeEntry('GHOST-RESOLUTION'), 'utf-8');
+
+    // 生成物落回同一目录：knowledge index 的真实产物形状
+    new KnowledgeIndexGenerator(dir).regenerate();
+  }
+
+  beforeEach(buildTree);
+  afterEach(() => fs.rmSync(dir, { recursive: true, force: true }));
+
+  it('store 顶层扫描：_index.md 与快照目录不冒充条目', () => {
+    const store = new FileKnowledgeStore({ baseDir: dir });
+    expect(store.list({ excludeArchived: false }).map(e => e.id).sort()).toEqual(['TREE-001', 'TREE-002']);
+    expect(store.readEntriesFromDisk().map(e => e.id).sort()).toEqual(['TREE-001', 'TREE-002']);
+    store.rebuildIndex();
+    expect(store.readIndex().map(e => e.id).sort()).toEqual(['TREE-001', 'TREE-002']);
+  });
+
+  it('migration：生成物既不计入 total 也不计入 errors（修假阳性）', () => {
+    const result = migrateKnowledgeEntries(dir);
+    expect(result.total).toBe(2);
+    expect(result.errors).toEqual([]);
+  });
+
+  it('index-generator：基建目录与 _index.md 一律不出现在索引行里', () => {
+    const lines = new KnowledgeIndexGenerator(dir).generateIndexLines();
+    const files = lines.map(l => l.split('|')[0]);
+    expect(files.sort()).toEqual(['guideline-TREE-001.md', 'pitfall-TREE-002.md']);
+  });
+
+  it('三处对撞：条目集合逐 id 相同（口径漂移即红）', () => {
+    const store = new FileKnowledgeStore({ baseDir: dir });
+    const fromStore = store.list({ excludeArchived: false }).map(e => e.id).sort();
+    const fromDisk = store.readEntriesFromDisk().map(e => e.id).sort();
+    const fromIndex = new KnowledgeIndexGenerator(dir)
+      .generateIndexLines()
+      .map(l => l.split('|')[1])
+      .sort();
+    expect({ fromStore, fromDisk, fromIndex }).toEqual({
+      fromStore: ['TREE-001', 'TREE-002'],
+      fromDisk: ['TREE-001', 'TREE-002'],
+      fromIndex: ['TREE-001', 'TREE-002'],
+    });
+  });
+});