@assistkick/create 1.0.0

package/templates/product-system/tests/qa_issue_sheet.test.ts

@@ -0,0 +1,464 @@
+/**
+ * Tests for QA Issue Reporting Side Sheet (feat_039).
+ * Uses node:test built-in runner.
+ * Tests the sheet logic: open/close, note rendering, CRUD callbacks,
+ * read-only mode outside QA column, and outside-click behavior.
+ */
+import { describe, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+class QaIssueSheet {
+  sheetEl: any;
+  apiClient: any;
+  document: any;
+  onNotesChanged: any;
+  isOpen = false;
+  featureId: string | null = null;
+  featureName: string | null = null;
+  column: string | null = null;
+  notes: any[] = [];
+  reviews: any[] = [];
+  titleEl: any = null;
+  bodyEl: any = null;
+
+  constructor(sheetEl: any, apiClient: any, document: any, onNotesChanged: any) {
+    this.sheetEl = sheetEl;
+    this.apiClient = apiClient;
+    this.document = document;
+    this.onNotesChanged = onNotesChanged;
+  }
+
+  init() {
+    this.titleEl = this.sheetEl.querySelector('.qa-sheet-title');
+    this.bodyEl = this.sheetEl.querySelector('.qa-sheet-body');
+    this.bindClose();
+    this.bindDocumentClick();
+  }
+
+  bindClose() {
+    const btn = this.sheetEl.querySelector('.qa-sheet-close');
+    if (btn) btn.addEventListener('click', () => this.close());
+  }
+
+  _handleDocumentClick: any = null;
+
+  bindDocumentClick() {
+    this._handleDocumentClick = (e: any) => this.handleDocumentClick(e);
+    this.document.addEventListener('click', this._handleDocumentClick);
+  }
+
+  handleDocumentClick(e: any) {
+    if (!this.isOpen) return;
+    if (this.sheetEl.contains(e.target)) return;
+    if (e.target.closest?.('.kanban-issues-btn')) return;
+    this.close();
+  }
+
+  open(featureId: string, featureName: string, column: string, notes: any[], reviews?: any[]) {
+    this.featureId = featureId;
+    this.featureName = featureName;
+    this.column = column;
+    this.notes = notes || [];
+    this.reviews = reviews || [];
+    this.isOpen = true;
+    this.render();
+    this.sheetEl.classList.add('open');
+  }
+
+  close() {
+    this.isOpen = false;
+    this.featureId = null;
+    this.sheetEl.classList.remove('open');
+  }
+
+  isEditable() { return this.column === 'qa'; }
+
+  render() {
+    if (this.titleEl) this.titleEl.textContent = `${this.featureId} — ${this.featureName}`;
+  }
+
+  formatDate(isoString: string | null | undefined): string {
+    if (!isoString) return '';
+    try {
+      const d = new Date(isoString);
+      return d.toLocaleDateString('en-US', { month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit' });
+    } catch { return ''; }
+  }
+
+  async refreshNotes() {
+    if (!this.featureId) return;
+    try {
+      const kanbanData = await this.apiClient.fetchKanban();
+      const entry = kanbanData[this.featureId];
+      if (entry) {
+        this.notes = entry.notes || [];
+        this.reviews = entry.reviews || [];
+      }
+      this.render();
+      if (this.onNotesChanged) this.onNotesChanged();
+    } catch {}
+  }
+
+  async deleteNote(note: any) {
+    try {
+      await this.apiClient.deleteNote(this.featureId, note.id);
+      await this.refreshNotes();
+    } catch {}
+  }
+
+  destroy() {
+    this.document.removeEventListener('click', this._handleDocumentClick);
+  }
+}
+
+// Minimal DOM element mock
+const createMockElement = (attrs: Record<string, any> = {}) => {
+  const listeners = {};
+  const classList = new Set();
+  const children: any[] = [];
+
+  const el: Record<string, any> = {
+    dataset: attrs.dataset || {},
+    innerHTML: '',
+    textContent: '',
+    style: {},
+    listeners,
+    classList: {
+      add: (c: string) => classList.add(c),
+      remove: (c: string) => classList.delete(c),
+      contains: (c: string) => classList.has(c),
+    },
+    _classList: classList,
+    addEventListener: (event: string, handler: any) => {
+      listeners[event] = listeners[event] || [];
+      listeners[event].push(handler);
+    },
+    removeEventListener: (event: string, handler: any) => {
+      if (listeners[event]) {
+        listeners[event] = listeners[event].filter((h: any) => h !== handler);
+      }
+    },
+    querySelector: (selector: string) => {
+      return children.find((c: any) => c._role === selector) || null;
+    },
+    querySelectorAll: () => [] as any[],
+    appendChild: (child: any) => { children.push(child); },
+    _addChild: (child: any) => { child._role = child._role || null; children.push(child); },
+    contains: (target: any) => target === el || children.includes(target),
+    closest: () => null,
+  };
+
+  return el;
+};
+
+// Mock document
+const createMockDocument = () => {
+  const listeners: Record<string, any[]> = {};
+  return {
+    createElement: (tag: string) => {
+      const el = createMockElement();
+      el._tag = tag;
+      el.appendChild = (child: any) => {};
+      el.focus = () => {};
+      return el;
+    },
+    addEventListener: (event: string, handler: any) => {
+      listeners[event] = listeners[event] || [];
+      listeners[event].push(handler);
+    },
+    removeEventListener: (event: string, handler: any) => {
+      if (listeners[event]) {
+        listeners[event] = listeners[event].filter((h: any) => h !== handler);
+      }
+    },
+    _listeners: listeners,
+  };
+};
+
+// Mock API client
+const createMockApiClient = (kanbanData = {}) => ({
+  createNote: mock.fn(async () => ({ id: 'n1', text: 'new note', created_at: new Date().toISOString() })),
+  updateNote: mock.fn(async () => ({ id: 'n1', text: 'updated', updated_at: new Date().toISOString() })),
+  deleteNote: mock.fn(async () => ({ ok: true })),
+  fetchKanban: mock.fn(async () => kanbanData),
+});
+
+describe('QaIssueSheet', () => {
+
+  describe('open/close', () => {
+    it('starts closed', () => {
+      const sheetEl = createMockElement();
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-title' }));
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-body' }));
+      const doc = createMockDocument();
+      const api = createMockApiClient();
+
+      const sheet = new QaIssueSheet(sheetEl, api, doc, null);
+      assert.equal(sheet.isOpen, false);
+    });
+
+    it('opens when open() is called', () => {
+      const sheetEl = createMockElement();
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-title' }));
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-body' }));
+      const doc = createMockDocument();
+      const api = createMockApiClient();
+
+      const sheet = new QaIssueSheet(sheetEl, api, doc, null);
+      sheet.init();
+      sheet.open('feat_001', 'Test Feature', 'qa', []);
+
+      assert.equal(sheet.isOpen, true);
+      assert.equal(sheet.featureId, 'feat_001');
+      assert.ok(sheetEl._classList.has('open'));
+    });
+
+    it('closes when close() is called', () => {
+      const sheetEl = createMockElement();
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-title' }));
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-body' }));
+      const doc = createMockDocument();
+      const api = createMockApiClient();
+
+      const sheet = new QaIssueSheet(sheetEl, api, doc, null);
+      sheet.init();
+      sheet.open('feat_001', 'Test Feature', 'qa', []);
+      sheet.close();
+
+      assert.equal(sheet.isOpen, false);
+      assert.equal(sheet.featureId, null);
+      assert.ok(!sheetEl._classList.has('open'));
+    });
+  });
+
+  describe('isEditable', () => {
+    it('returns true when column is qa', () => {
+      const sheetEl = createMockElement();
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-title' }));
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-body' }));
+      const doc = createMockDocument();
+      const api = createMockApiClient();
+
+      const sheet = new QaIssueSheet(sheetEl, api, doc, null);
+      sheet.init();
+      sheet.open('feat_001', 'Test Feature', 'qa', []);
+
+      assert.equal(sheet.isEditable(), true);
+    });
+
+    it('returns false when column is todo', () => {
+      const sheetEl = createMockElement();
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-title' }));
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-body' }));
+      const doc = createMockDocument();
+      const api = createMockApiClient();
+
+      const sheet = new QaIssueSheet(sheetEl, api, doc, null);
+      sheet.init();
+      sheet.open('feat_001', 'Test Feature', 'todo', []);
+
+      assert.equal(sheet.isEditable(), false);
+    });
+
+    it('returns false when column is done', () => {
+      const sheetEl = createMockElement();
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-title' }));
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-body' }));
+      const doc = createMockDocument();
+      const api = createMockApiClient();
+
+      const sheet = new QaIssueSheet(sheetEl, api, doc, null);
+      sheet.init();
+      sheet.open('feat_001', 'Test Feature', 'done', [{ id: 'n1', text: 'issue', created_at: '2026-01-01T00:00:00Z' }]);
+
+      assert.equal(sheet.isEditable(), false);
+    });
+  });
+
+  describe('document click (outside click to close)', () => {
+    it('closes sheet when clicking outside', () => {
+      const sheetEl = createMockElement();
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-title' }));
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-body' }));
+      const doc = createMockDocument();
+      const api = createMockApiClient();
+
+      const sheet = new QaIssueSheet(sheetEl, api, doc, null);
+      sheet.init();
+      sheet.open('feat_001', 'Test Feature', 'qa', []);
+
+      const outsideTarget = createMockElement();
+      sheet.handleDocumentClick({ target: outsideTarget });
+
+      assert.equal(sheet.isOpen, false);
+    });
+
+    it('does not close when clicking inside the sheet', () => {
+      const sheetEl = createMockElement();
+      const titleEl = Object.assign(createMockElement(), { _role: '.qa-sheet-title' });
+      sheetEl._addChild(titleEl);
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-body' }));
+      const doc = createMockDocument();
+      const api = createMockApiClient();
+
+      const sheet = new QaIssueSheet(sheetEl, api, doc, null);
+      sheet.init();
+      sheet.open('feat_001', 'Test Feature', 'qa', []);
+
+      sheet.handleDocumentClick({ target: titleEl });
+
+      assert.equal(sheet.isOpen, true);
+    });
+
+    it('does not close when sheet is already closed', () => {
+      const sheetEl = createMockElement();
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-title' }));
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-body' }));
+      const doc = createMockDocument();
+      const api = createMockApiClient();
+
+      const sheet = new QaIssueSheet(sheetEl, api, doc, null);
+      sheet.init();
+
+      const outsideTarget = createMockElement();
+      sheet.handleDocumentClick({ target: outsideTarget });
+
+      assert.equal(sheet.isOpen, false);
+    });
+  });
+
+  describe('formatDate', () => {
+    it('formats ISO string to readable date', () => {
+      const sheetEl = createMockElement();
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-title' }));
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-body' }));
+      const doc = createMockDocument();
+      const api = createMockApiClient();
+
+      const sheet = new QaIssueSheet(sheetEl, api, doc, null);
+      const result = sheet.formatDate('2026-02-27T10:30:00Z');
+
+      assert.ok(result.length > 0);
+      assert.ok(result.includes('Feb') || result.includes('27'));
+    });
+
+    it('returns empty string for null/undefined', () => {
+      const sheetEl = createMockElement();
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-title' }));
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-body' }));
+      const doc = createMockDocument();
+      const api = createMockApiClient();
+
+      const sheet = new QaIssueSheet(sheetEl, api, doc, null);
+      assert.equal(sheet.formatDate(null), '');
+      assert.equal(sheet.formatDate(undefined), '');
+    });
+  });
+
+  describe('notes data management', () => {
+    it('stores notes passed to open()', () => {
+      const sheetEl = createMockElement();
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-title' }));
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-body' }));
+      const doc = createMockDocument();
+      const api = createMockApiClient();
+
+      const notes = [
+        { id: 'n1', text: 'Bug in validation', created_at: '2026-02-27T10:00:00Z' },
+        { id: 'n2', text: 'Missing error handling', created_at: '2026-02-27T11:00:00Z' },
+      ];
+
+      const sheet = new QaIssueSheet(sheetEl, api, doc, null);
+      sheet.init();
+      sheet.open('feat_001', 'Test Feature', 'qa', notes);
+
+      assert.equal(sheet.notes.length, 2);
+      assert.equal(sheet.notes[0].text, 'Bug in validation');
+    });
+
+    it('defaults to empty notes when null is passed', () => {
+      const sheetEl = createMockElement();
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-title' }));
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-body' }));
+      const doc = createMockDocument();
+      const api = createMockApiClient();
+
+      const sheet = new QaIssueSheet(sheetEl, api, doc, null);
+      sheet.init();
+      sheet.open('feat_001', 'Test Feature', 'qa', null);
+
+      assert.deepEqual(sheet.notes, []);
+    });
+  });
+
+  describe('refreshNotes', () => {
+    it('fetches fresh kanban data and updates notes', async () => {
+      const sheetEl = createMockElement();
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-title' }));
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-body' }));
+      const doc = createMockDocument();
+      const kanbanData = {
+        feat_001: {
+          column: 'qa',
+          notes: [
+            { id: 'n1', text: 'Refreshed note', created_at: '2026-02-27T12:00:00Z' },
+          ],
+        },
+      };
+      const api = createMockApiClient(kanbanData);
+
+      const onNotesChanged = mock.fn();
+      const sheet = new QaIssueSheet(sheetEl, api, doc, onNotesChanged);
+      sheet.init();
+      sheet.open('feat_001', 'Test Feature', 'qa', []);
+
+      await sheet.refreshNotes();
+
+      assert.equal(sheet.notes.length, 1);
+      assert.equal(sheet.notes[0].text, 'Refreshed note');
+      assert.equal(api.fetchKanban.mock.calls.length, 1);
+      assert.equal(onNotesChanged.mock.calls.length, 1);
+    });
+  });
+
+  describe('deleteNote', () => {
+    it('calls apiClient.deleteNote and refreshes', async () => {
+      const sheetEl = createMockElement();
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-title' }));
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-body' }));
+      const doc = createMockDocument();
+      const kanbanData = {
+        feat_001: { column: 'qa', notes: [] },
+      };
+      const api = createMockApiClient(kanbanData);
+
+      const sheet = new QaIssueSheet(sheetEl, api, doc, null);
+      sheet.init();
+      sheet.open('feat_001', 'Test Feature', 'qa', [{ id: 'n1', text: 'To delete' }]);
+
+      await sheet.deleteNote({ id: 'n1', text: 'To delete' });
+
+      assert.equal(api.deleteNote.mock.calls.length, 1);
+      assert.equal((api.deleteNote.mock.calls as any[])[0].arguments[0], 'feat_001');
+      assert.equal((api.deleteNote.mock.calls as any[])[0].arguments[1], 'n1');
+    });
+  });
+
+  describe('destroy', () => {
+    it('removes document click listener', () => {
+      const sheetEl = createMockElement();
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-title' }));
+      sheetEl._addChild(Object.assign(createMockElement(), { _role: '.qa-sheet-body' }));
+      const doc = createMockDocument();
+      const api = createMockApiClient();
+
+      const sheet = new QaIssueSheet(sheetEl, api, doc, null);
+      sheet.init();
+
+      assert.ok(doc._listeners['click'] && doc._listeners['click'].length > 0);
+
+      sheet.destroy();
+
+      assert.equal(doc._listeners['click'].length, 0);
+    });
+  });
+});

package/templates/product-system/tests/relevance_search.test.ts

@@ -0,0 +1,186 @@
+/**
+ * Tests for Smart Search with Relevance Ranking (feat_051).
+ * Uses node:test built-in runner.
+ * Tests the relevance search algorithm: direct matches, graph expansion,
+ * edge type weighting, deduplication, and cold start fallback.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { relevanceSearch, coldStartFallback } from '../packages/shared/lib/relevance_search.js';
+
+// --- Test fixtures ---
+
+const makeNode = (id, type, name, status = 'defined') => ({
+  id, type, name, status, completeness: 1.0, open_questions_count: 0,
+});
+
+const makeEdge = (from, relation, to) => ({ from, relation, to });
+
+const NODES = [
+  makeNode('feat_001', 'feature', 'Node CRUD Operations'),
+  makeNode('feat_002', 'feature', 'Edge Management'),
+  makeNode('feat_003', 'feature', 'Search and Discovery'),
+  makeNode('comp_001', 'component', 'Graph Engine'),
+  makeNode('dec_001', 'decision', 'Force-Directed Layout'),
+  makeNode('tech_001', 'tech_choice', 'D3.js Force Graph'),
+  makeNode('nfr_001', 'non_functional_requirement', 'Performance Guidelines'),
+];
+
+const EDGES = [
+  makeEdge('feat_001', 'implemented_with', 'comp_001'),
+  makeEdge('feat_002', 'implemented_with', 'comp_001'),
+  makeEdge('feat_003', 'depends_on', 'feat_001'),
+  makeEdge('feat_003', 'depends_on', 'feat_002'),
+  makeEdge('comp_001', 'governed_by', 'dec_001'),
+  makeEdge('dec_001', 'relates_to', 'tech_001'),
+  makeEdge('feat_001', 'constrained_by', 'nfr_001'),
+];
+
+// Simple body lookup — only comp_001 has body containing "atomic writes"
+const BODIES = {
+  comp_001: 'Core data layer managing the graph. Uses atomic writes for safety.',
+};
+
+const getBody = async (id) => BODIES[id] ?? null;
+
+// --- Tests ---
+
+describe('relevanceSearch', () => {
+
+  describe('direct matches', () => {
+    it('returns direct match by name with relevance "direct"', async () => {
+      const results = await relevanceSearch('CRUD', NODES, EDGES, getBody);
+      const direct = results.filter(r => r.relevance === 'direct');
+      assert.equal(direct.length, 1);
+      assert.equal(direct[0].id, 'feat_001');
+    });
+
+    it('matches body content as direct match', async () => {
+      const results = await relevanceSearch('atomic', NODES, EDGES, getBody);
+      const direct = results.filter(r => r.relevance === 'direct');
+      assert.equal(direct.length, 1);
+      assert.equal(direct[0].id, 'comp_001');
+    });
+
+    it('is case-insensitive', async () => {
+      const lower = await relevanceSearch('crud', NODES, EDGES, getBody);
+      const upper = await relevanceSearch('CRUD', NODES, EDGES, getBody);
+      assert.equal(lower.length, upper.length);
+      assert.equal(lower[0].id, upper[0].id);
+    });
+  });
+
+  describe('graph expansion', () => {
+    it('includes 1-hop neighbors of direct matches', async () => {
+      const results = await relevanceSearch('CRUD', NODES, EDGES, getBody);
+      const ids = results.map(r => r.id);
+      // feat_001 direct → comp_001 (implemented_with), feat_003 (depends_on), nfr_001 (constrained_by)
+      assert.ok(ids.includes('comp_001'), 'should include comp_001 via implemented_with');
+      assert.ok(ids.includes('feat_003'), 'should include feat_003 via depends_on');
+      assert.ok(ids.includes('nfr_001'), 'should include nfr_001 via constrained_by');
+    });
+
+    it('neighbor relevance shows connection path', async () => {
+      const results = await relevanceSearch('CRUD', NODES, EDGES, getBody);
+      const comp = results.find(r => r.id === 'comp_001');
+      assert.ok(comp.relevance.includes('via feat_001'), 'should show source node');
+      assert.ok(comp.relevance.includes('implemented_with'), 'should show edge type');
+    });
+  });
+
+  describe('edge type weighting', () => {
+    it('strong-edge neighbors rank above weak-edge neighbors', async () => {
+      // Search for "Force-Directed" → direct match dec_001
+      // dec_001's neighbors: comp_001 (governed_by - strong, inbound), tech_001 (relates_to - weak)
+      const results = await relevanceSearch('Force-Directed', NODES, EDGES, getBody);
+
+      const comp = results.find(r => r.id === 'comp_001');
+      const tech = results.find(r => r.id === 'tech_001');
+      assert.ok(comp, 'comp_001 should be in results (1-hop via governed_by)');
+      assert.ok(tech, 'tech_001 should be in results (1-hop via relates_to)');
+      assert.ok(comp._score > tech._score,
+        `comp_001 (strong edge, score=${comp._score}) should rank above tech_001 (weak edge, score=${tech._score})`);
+    });
+
+    it('depends_on, implemented_with, governed_by, contains are strong edges', async () => {
+      const results = await relevanceSearch('CRUD', NODES, EDGES, getBody);
+      // comp_001 is via implemented_with (strong)
+      const comp = results.find(r => r.id === 'comp_001');
+      assert.equal(comp._score, 50, 'implemented_with should give score 50');
+    });
+
+    it('relates_to is a weak edge', async () => {
+      const results = await relevanceSearch('Force-Directed', NODES, EDGES, getBody);
+      const tech = results.find(r => r.id === 'tech_001');
+      assert.equal(tech._score, 20, 'relates_to should give score 20');
+    });
+  });
+
+  describe('sorting', () => {
+    it('direct matches come first in results', async () => {
+      const results = await relevanceSearch('CRUD', NODES, EDGES, getBody);
+      assert.equal(results[0].relevance, 'direct');
+      assert.equal(results[0].id, 'feat_001');
+    });
+
+    it('results are sorted by score descending', async () => {
+      const results = await relevanceSearch('CRUD', NODES, EDGES, getBody);
+      for (let i = 1; i < results.length; i++) {
+        assert.ok(results[i - 1]._score >= results[i]._score,
+          `result[${i - 1}] score ${results[i - 1]._score} should be >= result[${i}] score ${results[i]._score}`);
+      }
+    });
+  });
+
+  describe('deduplication', () => {
+    it('keeps highest score when node appears as both direct and neighbor', async () => {
+      // Search "Search" — matches feat_003 "Search and Discovery" directly
+      // feat_003 depends_on feat_001 and feat_002, which are neighbors
+      // If we also search for something that makes feat_003 a neighbor of another direct match,
+      // the direct score (100) should win over neighbor score
+
+      // Create a scenario: feat_003 is both a direct match and a neighbor of feat_001
+      const results = await relevanceSearch('Search', NODES, EDGES, getBody);
+      const feat003 = results.find(r => r.id === 'feat_003');
+      assert.ok(feat003, 'feat_003 should be in results');
+      assert.equal(feat003._score, 100, 'direct match should keep score 100');
+      assert.equal(feat003.relevance, 'direct');
+    });
+  });
+
+  describe('cold start fallback', () => {
+    it('returns results when keyword matches nothing', async () => {
+      const results = await relevanceSearch('xyznonexistent', NODES, EDGES, getBody);
+      assert.ok(results.length > 0, 'cold start should return structural overview');
+    });
+
+    it('cold start results have structural overview relevance', async () => {
+      const results = await relevanceSearch('xyznonexistent', NODES, EDGES, getBody);
+      for (const r of results) {
+        assert.ok(r.relevance.includes('structural overview'),
+          `result ${r.id} should have structural overview relevance, got: ${r.relevance}`);
+      }
+    });
+
+    it('cold start returns at most 5 per type', async () => {
+      // Create many nodes of one type
+      const manyFeatures = Array.from({ length: 10 }, (_, i) =>
+        makeNode(`feat_${String(i + 100).padStart(3, '0')}`, 'feature', `Feature ${i + 100}`)
+      );
+      const manyEdges = manyFeatures.map(n => makeEdge(n.id, 'relates_to', 'comp_001'));
+
+      const results = await relevanceSearch('xyznonexistent', manyFeatures, manyEdges, getBody);
+      const featureResults = results.filter(r => r.type === 'feature');
+      assert.ok(featureResults.length <= 5, `should return at most 5 per type, got ${featureResults.length}`);
+    });
+
+    it('cold start ranks by total edge count', async () => {
+      const results = coldStartFallback(NODES, EDGES);
+      // comp_001 has 4 edges (feat_001 impl, feat_002 impl, dec_001 gov_by)
+      // Should be among the top results
+      const comp = results.find(r => r.id === 'comp_001');
+      assert.ok(comp, 'comp_001 should be in cold start results');
+      assert.ok(comp._score > 0, 'should have positive score from edge count');
+    });
+  });
+});