@geraldmaron/construct 1.0.6 → 1.0.8

package/lib/intake/postgres-queue.mjs

@@ -15,6 +15,7 @@
  */
 
 import path from 'node:path';
+import { shouldQuarantine } from './quarantine.mjs';
 
 function slugify(value) {
   return String(value || 'untitled')
@@ -69,21 +70,62 @@ export class PostgresIntakeQueue {
     const id = `${ts}-${slug}`;
     const triage = entry.triage || {};
 
+    // Quarantine routing: low-confidence packets land in status='quarantined'
+    // instead of 'pending' so worker claim() never picks them up. Human
+    // reroute via rerouteQuarantined() promotes to 'pending'.
+    const quarantineDecision = shouldQuarantine(triage);
+    const status = quarantineDecision.quarantine ? 'quarantined' : 'pending';
+    const augmentedEntry = quarantineDecision.quarantine
+      ? { ...entry, quarantineReason: quarantineDecision.reason }
+      : entry;
+
     await this.sql`
       INSERT INTO construct_intake_items (
         id, project, tenant_id, status,
         intake_type, rd_stage, primary_owner, recommended_action,
         risk, requires_approval, confidence, payload
       ) VALUES (
-        ${id}, ${this.project}, ${this.tenantId}, 'pending',
+        ${id}, ${this.project}, ${this.tenantId}, ${status},
         ${triage.intakeType || null}, ${triage.rdStage || null},
         ${triage.primaryOwner || null}, ${triage.recommendedAction || null},
         ${triage.risk || null}, ${triage.requiresApproval || false},
         ${typeof triage.confidence === 'number' ? triage.confidence : null},
-        ${this.sql.json(entry)}
+        ${this.sql.json(augmentedEntry)}
       )
     `;
-    return { id };
+    return { id, route: quarantineDecision.quarantine ? 'quarantine' : 'pending', reason: quarantineDecision.reason };
+  }
+
+  async listQuarantine({ limit = 100 } = {}) {
+    const rows = await this.sql`
+      SELECT * FROM construct_intake_items
+      WHERE project = ${this.project}
+        AND (${this.tenantId}::text IS NULL OR tenant_id IS NOT DISTINCT FROM ${this.tenantId})
+        AND status = 'quarantined'
+      ORDER BY created_at ASC
+      LIMIT ${limit}
+    `;
+    return rows.map(rowToEntry);
+  }
+
+  async rerouteQuarantined(id, newType, { reroutedBy = 'unknown', reason = '' } = {}) {
+    const result = await this.sql`
+      UPDATE construct_intake_items
+      SET status = 'pending',
+          intake_type = ${newType},
+          payload = jsonb_set(
+            jsonb_set(payload, '{triage,originalIntakeType}', to_jsonb(intake_type::text)),
+            '{triage,intakeType}', to_jsonb(${newType}::text)
+          ),
+          updated_at = now(),
+          notes = ${`rerouted by ${reroutedBy}${reason ? `: ${reason}` : ''}`}
+      WHERE id = ${id}
+        AND project = ${this.project}
+        AND status = 'quarantined'
+      RETURNING id
+    `;
+    if (result.count === 0) throw new Error(`rerouteQuarantined: no quarantined entry ${id}`);
+    return { id, route: 'pending' };
   }
 
   async listPending({ limit = 100 } = {}) {

package/lib/intake/prepare.mjs

@@ -77,19 +77,21 @@ export async function prepareIntakeForIngestedFile({
     extractedText: extracted,
     related,
     profile: activeProfile?.id,
-    cwd: rootDir,
   });
 
   // Detect customer mentions and update profiles
   const customerMentions = detectCustomerMentions(extracted.slice(0, 2000));
   const customers = customerMentions.map((c) => c.customerId);
 
+  const droppedInfo = ingestedFile.droppedInfo ?? [];
+
   const entry = {
     intake: {
       sourcePath: ingestedFile.sourcePath,
       outputPath: ingestedFile.outputPath,
       characters: ingestedFile.characters,
       knowledgeSubdir: ingestedFile.knowledgeSubdir,
+      extractor: droppedInfo.length > 0 ? { droppedInfo } : undefined,
     },
     triage,
     suggestion: lane ? { lane, source: 'docs-routing.suggestDocsLaneForFile' } : null,

package/lib/intake/quarantine.mjs

@@ -0,0 +1,205 @@
+/**
+ * lib/intake/quarantine.mjs — low-confidence intake quarantine + learned-fixture loop.
+ *
+ * When the classifier is uncertain (low confidence or close margin between
+ * top-2 candidates), the packet should not auto-route to pending where a
+ * downstream specialist might act on a confident-looking-but-wrong label.
+ * Instead it lands in `.cx/intake/quarantine/` and waits for human review
+ * via `construct intake quarantine show <id>` + `construct intake reroute`.
+ *
+ * The reroute path writes a fixture into tests/fixtures/intake/learned/
+ * keyed by content hash. CI loads these fixtures alongside the golden
+ * corpus and asserts the classifier handles them correctly. The override
+ * thus becomes durable — the same wrong call cannot happen twice without
+ * also failing CI.
+ *
+ * Determinism contract preserved: the daemon never reads the learned
+ * fixtures at runtime; only tests do. Classification stays a pure function
+ * of (sourcePath, extractedText, related, profile).
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+
+const QUEUE_SUBDIR = '.cx/intake';
+
+// Quarantine thresholds. A packet with a winning candidate still lands in
+// quarantine when either bar fails. Conservative defaults: 0.60 confidence
+// and 0.20 margin cover the demonstrated failure cases without flooding
+// quarantine for borderline-but-defensible classifications.
+export const QUARANTINE_CONFIDENCE_THRESHOLD = 0.60;
+export const QUARANTINE_MARGIN_THRESHOLD = 0.20;
+
+export function quarantineDir(rootDir) {
+  return path.join(rootDir, QUEUE_SUBDIR, 'quarantine');
+}
+
+/**
+ * Decide whether a triage result should be routed to quarantine.
+ * Returns { quarantine: boolean, reason?: string }.
+ */
+export function shouldQuarantine(triage) {
+  if (!triage || triage.intakeType === 'unknown') {
+    return { quarantine: false }; // unknown is its own bucket; not quarantine
+  }
+  const confidence = typeof triage.confidence === 'number' ? triage.confidence : 1;
+  if (confidence < QUARANTINE_CONFIDENCE_THRESHOLD) {
+    return { quarantine: true, reason: `confidence ${confidence.toFixed(2)} < ${QUARANTINE_CONFIDENCE_THRESHOLD}` };
+  }
+  if (Array.isArray(triage.candidates) && triage.candidates.length >= 2) {
+    const margin = triage.candidates[0].score - triage.candidates[1].score;
+    if (margin < QUARANTINE_MARGIN_THRESHOLD) {
+      return { quarantine: true, reason: `margin ${margin.toFixed(2)} < ${QUARANTINE_MARGIN_THRESHOLD}` };
+    }
+  }
+  return { quarantine: false };
+}
+
+/**
+ * Hash content for fixture deduplication. Uses the same input the classifier
+ * sees so two packets with identical signal produce one fixture.
+ */
+export function fixtureHash(sourcePath, extractedText) {
+  const h = createHash('sha256');
+  h.update(String(sourcePath || ''));
+  h.update('\n--\n');
+  h.update(String(extractedText || '').slice(0, 8000));
+  return h.digest('hex').slice(0, 16);
+}
+
+/**
+ * Write a learned-fixture file recording the human-chosen classification.
+ * Called by `construct intake reroute`. Idempotent — overwrites with the
+ * latest reroute decision (the most recent human call is authoritative).
+ *
+ * @param {string} rootDir - repo root where tests/fixtures/intake/learned lives
+ * @param {object} packet - the quarantined packet being rerouted
+ * @param {string} expectedType - intakeType the human picked
+ * @returns {{ filePath: string, hash: string }}
+ */
+export function writeLearnedFixture(rootDir, packet, expectedType) {
+  const sourcePath = packet?.intake?.sourcePath || packet?.sourcePath || '';
+  const text = packet?.excerpt || '';
+  const hash = fixtureHash(sourcePath, text);
+  const dir = path.join(rootDir, 'tests', 'fixtures', 'intake', 'learned');
+  mkdirSync(dir, { recursive: true });
+  const filePath = path.join(dir, `${hash}.json`);
+  const fixture = {
+    content_hash: `sha256:${hash}`,
+    source_path: sourcePath,
+    text_snippet: text.slice(0, 500),
+    expected: { intakeType: expectedType },
+    origin: 'user-reroute',
+    created_at: new Date().toISOString(),
+    packet_id: packet?.id || null,
+  };
+  writeFileSync(filePath, JSON.stringify(fixture, null, 2) + '\n', 'utf8');
+  return { filePath, hash };
+}
+
+/**
+ * List all learned fixtures (for the calibration test). Returns an array
+ * of { content_hash, source_path, text_snippet, expected, ... } objects.
+ */
+export function loadLearnedFixtures(rootDir) {
+  const dir = path.join(rootDir, 'tests', 'fixtures', 'intake', 'learned');
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((name) => name.endsWith('.json'))
+    .map((name) => {
+      try { return JSON.parse(readFileSync(path.join(dir, name), 'utf8')); }
+      catch { return null; }
+    })
+    .filter(Boolean);
+}
+
+/**
+ * Write a quarantined packet to disk. Mirrors the structure of pending/
+ * packets so `intake show` / `intake reroute` can read either location.
+ */
+export function writeQuarantinePacket(rootDir, packet, quarantineReason) {
+  const dir = quarantineDir(rootDir);
+  mkdirSync(dir, { recursive: true });
+  const id = packet.id;
+  if (!id) throw new Error('writeQuarantinePacket: packet.id required');
+  const filePath = path.join(dir, `${id}.json`);
+  const payload = {
+    ...packet,
+    status: 'quarantined',
+    quarantinedAt: new Date().toISOString(),
+    quarantineReason: quarantineReason || null,
+  };
+  writeFileSync(filePath, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+  return { id, filePath };
+}
+
+/**
+ * List packets currently in quarantine. Same shape as listPending.
+ */
+export function listQuarantine(rootDir) {
+  const dir = quarantineDir(rootDir);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((name) => name.endsWith('.json'))
+    .map((name) => {
+      const filePath = path.join(dir, name);
+      try {
+        const data = JSON.parse(readFileSync(filePath, 'utf8'));
+        return { ...data, filePath };
+      } catch { return null; }
+    })
+    .filter(Boolean)
+    .sort((a, b) => (a.quarantinedAt || '').localeCompare(b.quarantinedAt || ''));
+}
+
+/**
+ * Read a single quarantined packet by id. Returns null if not found.
+ */
+export function readQuarantine(rootDir, id) {
+  const filePath = path.join(quarantineDir(rootDir), `${id}.json`);
+  if (!existsSync(filePath)) return null;
+  try {
+    const data = JSON.parse(readFileSync(filePath, 'utf8'));
+    return { ...data, filePath };
+  } catch { return null; }
+}
+
+/**
+ * Move a quarantined packet to pending after a human reroute. Updates the
+ * triage.intakeType + records the reroute history. Writes the learned
+ * fixture as a side effect.
+ *
+ * Returns { id, filePath, fixturePath, fixtureHash } on success.
+ */
+export function rerouteQuarantined(rootDir, id, newType, { reroutedBy = 'unknown', reason = '' } = {}) {
+  const packet = readQuarantine(rootDir, id);
+  if (!packet) throw new Error(`reroute: no quarantined packet ${id}`);
+
+  // Write learned fixture BEFORE moving — fixture creation must succeed for
+  // the reroute to commit. If fixture write fails, the packet stays put so
+  // the human can retry.
+  const { filePath: fixturePath, hash } = writeLearnedFixture(rootDir, packet, newType);
+
+  const updated = {
+    ...packet,
+    status: 'pending',
+    triage: {
+      ...(packet.triage || {}),
+      intakeType: newType,
+      originalIntakeType: packet.triage?.intakeType,
+      reroutedAt: new Date().toISOString(),
+      reroutedBy,
+      rerouteReason: reason || null,
+      rerouteFixtureHash: hash,
+    },
+  };
+  delete updated.quarantinedAt;
+  delete updated.quarantineReason;
+
+  const pendingPath = path.join(rootDir, QUEUE_SUBDIR, 'pending', `${id}.json`);
+  mkdirSync(path.dirname(pendingPath), { recursive: true });
+  writeFileSync(pendingPath, JSON.stringify(updated, null, 2) + '\n', 'utf8');
+  rmSync(packet.filePath);
+  return { id, filePath: pendingPath, fixturePath, fixtureHash: hash };
+}

package/lib/intake/session-prelude.mjs

@@ -13,6 +13,7 @@
 import { createIntakeQueue } from './queue.mjs';
 import { formatTriageLine } from './classify.mjs';
 import { isBrokered } from '../mcp/broker.mjs';
+import { getRebrand } from '../profiles/rebrand.mjs';
 
 export function buildIntakePrelude({ cwd, env = process.env } = {}) {
   if (!cwd) return '';
@@ -20,11 +21,16 @@ export function buildIntakePrelude({ cwd, env = process.env } = {}) {
     const queue = createIntakeQueue(cwd, env);
     const pending = queue.listPending();
     if (!pending.length) return '';
+    const { intakeQueueLabel, signalNoun } = getRebrand(cwd);
     const recent = pending.slice(-3).map((p) => {
       const src = p.intake?.sourcePath || p.id;
       return `- ${formatTriageLine(src, p.triage)}`;
     });
-    return `\n## Pending R&D intake (${pending.length})\n${recent.join('\n')}\nEach packet at \`.cx/intake/pending/<id>.json\` carries the new signal, a triage block (intakeType, rdStage, primaryOwner, recommendedChain, recommendedAction, risk), related existing docs, and an excerpt. Process via the recommended chain, then close via \`construct intake done <id>\`.\n`;
+    // Strip a trailing " queue" / " intake" so the heading reads
+    // "## Pending R&D intake (N)" rather than the redundant
+    // "## Pending R&D intake queue queue (N)".
+    const heading = intakeQueueLabel.replace(/\s+queue$/i, '');
+    return `\n## Pending ${heading} (${pending.length})\n${recent.join('\n')}\nEach packet at \`.cx/intake/pending/<id>.json\` carries the new ${signalNoun}, a triage block (intakeType, rdStage, primaryOwner, recommendedChain, recommendedAction, risk), related existing docs, and an excerpt. Process via the recommended chain, then close via \`construct intake done <id>\`.\n`;
   } catch {
     return '';
   }

package/lib/intake/traceability.mjs

@@ -0,0 +1,90 @@
+/**
+ * lib/intake/traceability.mjs — stamps intake provenance into artifact frontmatter.
+ *
+ * Backs `construct intake done <id> --output=<path>`: reads the intake packet,
+ * extracts (id, confidence, rationale), and writes them into the artifact's
+ * YAML frontmatter. Refuses to overwrite a different intake_id (an artifact
+ * can be linked to exactly one intake source). Idempotent on re-stamping.
+ *
+ * Read by docs:verify checkIntakeTraceability to surface artifacts in
+ * intake-fed locations that lack a reference.
+ *
+ * Field schema (in artifact YAML frontmatter):
+ *   intake_id: construct-xxx
+ *   intake_confidence: 0.7
+ *   intake_rationale: "Matched 3 keywords: dashboard, latency, p95"
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
+
+export function parseArtifactFrontmatter(content) {
+  const m = content.match(FRONTMATTER_RE);
+  if (!m) return { frontmatter: {}, body: content, hasBlock: false };
+  const out = {};
+  for (const line of m[1].split('\n')) {
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    const rawValue = line.slice(idx + 1).trim();
+    if (!key) continue;
+    const unquoted = rawValue.replace(/^["']|["']$/g, '');
+    if (/^-?\d+(\.\d+)?$/.test(unquoted)) out[key] = Number(unquoted);
+    else out[key] = unquoted;
+  }
+  return { frontmatter: out, body: content.slice(m[0].length), hasBlock: true };
+}
+
+function serializeFrontmatter(fm) {
+  const lines = ['---'];
+  for (const [k, v] of Object.entries(fm)) {
+    if (v === null || v === undefined) continue;
+    if (typeof v === 'number' || typeof v === 'boolean') {
+      lines.push(`${k}: ${v}`);
+    } else {
+      const s = String(v);
+      const needsQuoting = /[:#"'\n]|^\s|\s$/.test(s);
+      lines.push(`${k}: ${needsQuoting ? JSON.stringify(s) : s}`);
+    }
+  }
+  lines.push('---');
+  return lines.join('\n');
+}
+
+export function stampIntakeProvenance(artifactPath, { intakeId, confidence, rationale }) {
+  if (!existsSync(artifactPath)) {
+    throw new Error(`Output artifact not found: ${artifactPath}`);
+  }
+  if (!intakeId) throw new Error('intakeId required for stamping');
+  const content = readFileSync(artifactPath, 'utf8');
+  const { frontmatter, body, hasBlock } = parseArtifactFrontmatter(content);
+
+  const existing = frontmatter.intake_id;
+  if (existing && existing !== intakeId) {
+    throw new Error(
+      `Refusing to overwrite intake_id: artifact already references ${existing}, not ${intakeId}. Resolve manually or supersede.`,
+    );
+  }
+
+  const next = {
+    ...frontmatter,
+    intake_id: intakeId,
+    ...(confidence !== undefined && confidence !== null ? { intake_confidence: confidence } : {}),
+    ...(rationale ? { intake_rationale: rationale } : {}),
+  };
+
+  const fmText = serializeFrontmatter(next);
+  const out = hasBlock ? `${fmText}\n${body}` : `${fmText}\n\n${content}`;
+  writeFileSync(artifactPath, out, 'utf8');
+  return { intake_id: intakeId, intake_confidence: next.intake_confidence, intake_rationale: next.intake_rationale };
+}
+
+export function hasIntakeReference(artifactPath) {
+  if (!existsSync(artifactPath)) return false;
+  const { frontmatter } = parseArtifactFrontmatter(readFileSync(artifactPath, 'utf8'));
+  if (frontmatter.intake_id) return true;
+  if (frontmatter.intake === 'none') return true;
+  return false;
+}

package/lib/knowledge/postgres-search.mjs

@@ -0,0 +1,132 @@
+/**
+ * lib/knowledge/postgres-search.mjs — Tag-aware vector search via pgvector + GIN.
+ *
+ * Runs when DATABASE_URL is configured. Chooses between two execution paths
+ * based on tag selectivity:
+ *
+ * - High selectivity (tag matches <5% of corpus): GIN prefilter first, then
+ *   HNSW ANN on the filtered set.
+ * - Low selectivity (tag matches ≥5% of corpus): HNSW ANN first with
+ *   hnsw.iterative_scan=relaxed_order, postfilter by tag.
+ *
+ * Falls back gracefully when DATABASE_URL is absent or the pgvector extension
+ * is not installed; callers should use knowledgeSearch() from search.mjs in
+ * that case.
+ */
+
+// Selectivity threshold: if the tagged fraction exceeds this, use postfilter.
+const HIGH_SELECTIVITY_THRESHOLD = 0.05;
+
+/**
+ * Execute a tag-filtered vector search against Postgres + pgvector.
+ *
+ * @param {object} opts
+ * @param {Float32Array|number[]} opts.queryEmbedding   — query vector
+ * @param {string}   opts.project       — project id (construct_documents.project)
+ * @param {string[]} [opts.tags]        — tag filter
+ * @param {'any'|'all'} [opts.tagMatch] — 'any' (default) or 'all'
+ * @param {number}   [opts.topK]        — result limit (default 20)
+ * @param {object}   opts.db            — postgres client (from lib/db.mjs or postgres pkg)
+ * @returns {Promise<Array<{id, title, score}>>}
+ */
+export async function postgresTagSearch({ queryEmbedding, project, tags = [], tagMatch = 'any', topK = 20, db }) {
+  if (!db) throw new Error('postgres-search: db client required');
+  if (!queryEmbedding?.length) throw new Error('postgres-search: queryEmbedding required');
+
+  const vecLiteral = `[${Array.from(queryEmbedding).join(',')}]`;
+
+  if (!tags.length) {
+    // No tag filter — plain ANN.
+    const rows = await db`
+      select d.id, d.title, e.embedding <=> ${vecLiteral}::vector as distance
+      from construct_embeddings e
+      join construct_documents d on d.id = e.document_id
+      where d.project = ${project}
+      order by e.embedding <=> ${vecLiteral}::vector
+      limit ${topK}
+    `;
+    return rows.map((r) => ({ id: r.id, title: r.title, score: 1 - parseFloat(r.distance) }));
+  }
+
+  // Estimate selectivity for this tag set.
+  const tagJsonb = JSON.stringify(tags);
+  const [{ total }] = await db`select count(*) as total from construct_documents where project = ${project}`;
+  const totalCount = parseInt(total, 10) || 1;
+
+  let taggedCount;
+  if (tagMatch === 'all') {
+    const [{ cnt }] = await db`
+      select count(*) as cnt from construct_documents
+      where project = ${project} and tags @> ${tagJsonb}::jsonb
+    `;
+    taggedCount = parseInt(cnt, 10);
+  } else {
+    // 'any' — count docs with at least one matching tag.
+    const [{ cnt }] = await db`
+      select count(*) as cnt from construct_documents
+      where project = ${project}
+        and (${db.unsafe(tags.map((_, i) => `tags ? $${i + 2}`).join(' or '))})
+    `;
+    taggedCount = parseInt(cnt, 10);
+  }
+
+  const selectivity = taggedCount / totalCount;
+
+  if (selectivity < HIGH_SELECTIVITY_THRESHOLD) {
+    // High selectivity: GIN prefilter → ANN on filtered set.
+    if (tagMatch === 'all') {
+      const rows = await db`
+        with filtered as (
+          select id from construct_documents
+          where project = ${project} and tags @> ${tagJsonb}::jsonb
+        )
+        select d.id, d.title, e.embedding <=> ${vecLiteral}::vector as distance
+        from construct_embeddings e
+        join filtered f on f.id = e.document_id
+        join construct_documents d on d.id = e.document_id
+        order by e.embedding <=> ${vecLiteral}::vector
+        limit ${topK}
+      `;
+      return rows.map((r) => ({ id: r.id, title: r.title, score: 1 - parseFloat(r.distance) }));
+    }
+    // 'any' — OR-expand tag list.
+    const tagConditions = tags.map((t) => `tags ? '${t.replace(/'/g, "''")}'`).join(' or ');
+    const rows = await db.unsafe(`
+      with filtered as (
+        select id from construct_documents
+        where project = $1 and (${tagConditions})
+      )
+      select d.id, d.title, e.embedding <=> $2::vector as distance
+      from construct_embeddings e
+      join filtered f on f.id = e.document_id
+      join construct_documents d on d.id = e.document_id
+      order by e.embedding <=> $2::vector
+      limit $3
+    `, [project, vecLiteral, topK]);
+    return rows.map((r) => ({ id: r.id, title: r.title, score: 1 - parseFloat(r.distance) }));
+  }
+
+  // Low selectivity: HNSW iterative scan → postfilter.
+  await db`set hnsw.iterative_scan = relaxed_order`;
+  if (tagMatch === 'all') {
+    const rows = await db`
+      select d.id, d.title, e.embedding <=> ${vecLiteral}::vector as distance
+      from construct_embeddings e
+      join construct_documents d on d.id = e.document_id
+      where d.project = ${project} and d.tags @> ${tagJsonb}::jsonb
+      order by e.embedding <=> ${vecLiteral}::vector
+      limit ${topK}
+    `;
+    return rows.map((r) => ({ id: r.id, title: r.title, score: 1 - parseFloat(r.distance) }));
+  }
+  const tagConditions = tags.map((t) => `d.tags ? '${t.replace(/'/g, "''")}'`).join(' or ');
+  const rows = await db.unsafe(`
+    select d.id, d.title, e.embedding <=> $1::vector as distance
+    from construct_embeddings e
+    join construct_documents d on d.id = e.document_id
+    where d.project = $2 and (${tagConditions})
+    order by e.embedding <=> $1::vector
+    limit $3
+  `, [vecLiteral, project, topK]);
+  return rows.map((r) => ({ id: r.id, title: r.title, score: 1 - parseFloat(r.distance) }));
+}

package/lib/knowledge/research-store.mjs

@@ -19,6 +19,7 @@ import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { syncFileStateToSql } from '../storage/sync.mjs';
 import { resolveActiveProfile } from '../profiles/loader.mjs';
+import { ensureCxDir } from '../project-init-shared.mjs';
 
 const ROOT = '.cx/knowledge/external/research';
 const MAX_BYTES = 50 * 1024;
@@ -68,6 +69,7 @@ export async function addResearchFinding({
   const expiresAt = new Date(now.getTime() + ttlDays * 24 * 60 * 60 * 1000).toISOString();
 
   const outDir = join(cwd, ROOT);
+  ensureCxDir(cwd);
   mkdirSync(outDir, { recursive: true });
   const outPath = join(outDir, `${slug}.md`);
 

package/lib/knowledge/search.mjs

@@ -253,7 +253,7 @@ function buildObservationChunks(rootDir) {
  * @param {string} [opts.rootDir]      — data dir where .cx/observations/ lives (default: homedir())
  * @returns {KnowledgeSearchResult}
  */
-export function knowledgeSearch({ query, topK = 5, minScore = 0.1, repoRoot, rootDir } = {}) {
+export function knowledgeSearch({ query, topK = 5, minScore = 0.1, repoRoot, rootDir, tags, tagMatch = 'any' } = {}) {
   if (!query || typeof query !== 'string') {
     return { ok: false, query: query ?? '', totalChunks: 0, hits: [], sources: [], message: 'query is required' };
   }
@@ -279,14 +279,24 @@ export function knowledgeSearch({ query, topK = 5, minScore = 0.1, repoRoot, roo
     return { ok: false, query, totalChunks: 0, hits: [], sources: [], message: 'No documentation or observation sources found' };
   }
 
+  // Tag filter (optional): applied before scoring to restrict the candidate set.
+  const filteredChunks = tags?.length
+    ? allChunks.filter((c) => {
+        const chunkTags = new Set(Array.isArray(c.tags) ? c.tags : []);
+        const required = tags;
+        if (tagMatch === 'all') return required.every((t) => chunkTags.has(t));
+        return required.some((t) => chunkTags.has(t));
+      })
+    : allChunks;
+
   const queryTokens = tokenise(query);
   if (!queryTokens.length) {
-    return { ok: false, query, totalChunks: allChunks.length, hits: [], sources: [], message: 'Query contains no searchable terms after stop-word removal' };
+    return { ok: false, query, totalChunks: filteredChunks.length, hits: [], sources: [], message: 'Query contains no searchable terms after stop-word removal' };
   }
 
-  const idf = buildIdf(queryTokens, allChunks);
+  const idf = buildIdf(queryTokens, filteredChunks);
 
-  const scored = allChunks
+  const scored = filteredChunks
     .map(chunk => ({ chunk, score: scoreChunk(chunk, queryTokens, idf) }))
     .filter(({ score }) => score >= minScore)
     .sort((a, b) => b.score - a.score)