@geraldmaron/construct 1.0.7 → 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

@@ -83,12 +83,15 @@ export async function prepareIntakeForIngestedFile({
   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/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/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)

package/lib/mcp/server.mjs

@@ -14,6 +14,7 @@ import { fileURLToPath } from 'node:url';
 import { realpathSync } from 'node:fs';
 import { loadToolkitEnv } from '../toolkit-env.mjs';
 import { loadConstructEnv } from '../env-config.mjs';
+import { withGenAiSpan, GenAiAttrs, extractTraceContext, injectTraceContext } from '../telemetry/otel-tracer.mjs';
 
 // Apply config.env values to process.env, letting config.env win over shell env
 // so telemetry/OpenRouter credentials are always correct regardless of host env.
@@ -415,11 +416,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'broker_check',
-      description: 'Queries the MCP broker policy gate for a pending action without executing it. Agents call this BEFORE attempting a high-risk action so the response (allowed / approvalRequired / reason / source) can be surfaced to the user in the agent\'s voice rather than triggering a denial after the fact. In solo mode the broker is off by default — returns `brokerActive: false` with `allowed: true` so the call is cheap and agents don\'t waste tokens on an inactive gate. Always emits a `tool.called` trace event for audit-trail parity. Reads agents/role-manifests.json fence rules in team / enterprise mode.',
+      description: 'Queries the MCP broker policy gate for a pending action without executing it. Agents call this BEFORE attempting a high-risk action so the response (allowed / approvalRequired / reason / source) can be surfaced to the user in the agent\'s voice rather than triggering a denial after the fact. In solo mode the broker is off by default — returns `brokerActive: false` with `allowed: true` so the call is cheap and agents don\'t waste tokens on an inactive gate. Always emits a `tool.called` trace event for audit-trail parity. Reads specialists/role-manifests.json fence rules in team / enterprise mode.',
       inputSchema: {
         type: 'object',
         properties: {
-          role: { type: 'string', description: 'Persona name (e.g. `engineer`, `security`). Must match a key in agents/role-manifests.json for team / enterprise mode.' },
+          role: { type: 'string', description: 'Persona name (e.g. `engineer`, `security`). Must match a key in specialists/role-manifests.json for team / enterprise mode.' },
           project: { type: 'string', description: 'Optional project scope for the decision.' },
           tool: { type: 'string', description: 'The tool the agent wants to invoke (e.g. `github`, `fs`).' },
           action: { type: 'string', description: 'The action on that tool (e.g. `create_pr`, `edit:lib/foo.mjs`).' },
@@ -431,7 +432,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'agent_contract',
-      description: 'Looks up explicit agent-to-agent service contracts (from agents/contracts.json). Specialists should call this at the start of a handoff to see the expected input shape, preconditions, and what postconditions they must satisfy. Use without args to get all contracts; pass producer/consumer to narrow; pass id for a specific contract.',
+      description: 'Looks up explicit agent-to-agent service contracts (from specialists/contracts.json). Specialists should call this at the start of a handoff to see the expected input shape, preconditions, and what postconditions they must satisfy. Use without args to get all contracts; pass producer/consumer to narrow; pass id for a specific contract.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -875,6 +876,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           cwd: { type: 'string', description: 'Project root (default: server cwd).' },
           top_k: { type: 'number', description: 'Max communities to return (default 5).' },
           min_size: { type: 'number', description: 'Skip communities smaller than this (default 2).' },
+          tags: { type: 'array', items: { type: 'string' }, description: 'Restrict entity extraction to observations carrying these tags.' },
+          tag_match: { type: 'string', enum: ['any', 'all'], description: 'Tag match mode: any (default) or all.' },
         },
       },
     },
@@ -906,6 +909,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args = {} } = request.params;
 
+  // Extract W3C traceparent from params._meta (SEP-414 propagation).
+  const parentCtx = await extractTraceContext(request.params?._meta || {});
+
   let result;
   try {
     if (name === 'agent_health') result = agentHealth(args);

package/lib/mcp/tools/skills.mjs

@@ -21,8 +21,14 @@ export function listSkills({ ROOT_DIR }) {
     const entries = readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
       if (entry.isDirectory()) {
-        results = results.concat(listDirRecursive(join(dir, entry.name), `${prefix}${entry.name}/`));
-      } else if (entry.name.endsWith('.md') && entry.name !== 'SKILL.md') {
+        // Directory form: <name>/SKILL.md — emit the directory name as the skill id.
+        const skillMd = join(dir, entry.name, 'SKILL.md');
+        if (existsSync(skillMd)) {
+          results.push(`${prefix}${entry.name}`);
+        } else {
+          results = results.concat(listDirRecursive(join(dir, entry.name), `${prefix}${entry.name}/`));
+        }
+      } else if (entry.name.endsWith('.md') && entry.name !== 'SKILL.md' && entry.name !== 'routing.md') {
         results.push(`${prefix}${entry.name.replace('.md', '')}`);
       }
     }
@@ -37,13 +43,28 @@ export function getSkill(args, { ROOT_DIR }) {
   const { path: skillPath } = args;
   if (!skillPath) return { error: 'Missing path argument' };
 
-  const fullPath = join(ROOT_DIR, 'skills', `${skillPath}.md`);
+  // Primary: flat file form skills/<path>.md
+  // Fallback: directory form skills/<path>/SKILL.md (one minor-release grace period)
+  const candidates = [
+    join(ROOT_DIR, 'skills', `${skillPath}.md`),
+    join(ROOT_DIR, 'skills', skillPath, 'SKILL.md'),
+  ];
 
-  if (!existsSync(fullPath)) {
+  const fullPath = candidates.find(existsSync);
+  if (!fullPath) {
     return { error: `Skill not found: ${skillPath}` };
   }
+  const t0 = Date.now();
   const content = readFileSync(fullPath, 'utf8');
-  logSkillCall({ skillId: skillPath, source: 'mcp' });
+  logSkillCall({
+    skillId: skillPath,
+    source: 'mcp',
+    latencyMs: Date.now() - t0,
+    callerContext: args.callerContext,
+    agentId: args.agentId,
+    sessionId: args.sessionId,
+    tokensReturned: Math.ceil(content.length / 4),
+  });
   return { content };
 }
 
@@ -114,8 +135,8 @@ export async function agentContract(args = {}) {
     getOutgoingContracts,
     getIncomingContracts,
     summarize,
-  } = await import('../../agent-contracts.mjs');
-  const { describePostconditions } = await import('../../agents/postconditions.mjs');
+  } = await import('../../specialist-contracts.mjs');
+  const { describePostconditions } = await import('../../specialists/postconditions.mjs');
   const { id, producer, consumer } = args;
   // Attach binary postconditions to every returned contract so a specialist
   // calling this tool at handoff time sees the hard checks their output
@@ -382,8 +403,8 @@ export async function workerRun(args = {}) {
 }
 
 export function listTeams({ ROOT_DIR }) {
-  const teamsPath = join(ROOT_DIR, 'agents', 'teams.json');
-  if (!existsSync(teamsPath)) return { error: 'agents/teams.json not found' };
+  const teamsPath = join(ROOT_DIR, 'specialists', 'teams.json');
+  if (!existsSync(teamsPath)) return { error: 'specialists/teams.json not found' };
   const { templates } = JSON.parse(readFileSync(teamsPath, 'utf8'));
   return {
     teams: Object.entries(templates).map(([name, t]) => ({
@@ -400,8 +421,8 @@ export function listTeams({ ROOT_DIR }) {
 export function getTeam(args, { ROOT_DIR }) {
   const { name } = args;
   if (!name) return { error: 'Missing name argument' };
-  const teamsPath = join(ROOT_DIR, 'agents', 'teams.json');
-  if (!existsSync(teamsPath)) return { error: 'agents/teams.json not found' };
+  const teamsPath = join(ROOT_DIR, 'specialists', 'teams.json');
+  if (!existsSync(teamsPath)) return { error: 'specialists/teams.json not found' };
   const { templates } = JSON.parse(readFileSync(teamsPath, 'utf8'));
   const team = templates[name];
   if (!team) return { error: `Team not found: ${name}`, available: Object.keys(templates) };

package/lib/mcp/tools/workflow.mjs

@@ -97,7 +97,7 @@ export function workflowValidate(args) {
 }
 
 /**
- * Validate a producer→consumer handoff against agents/contracts.json.
+ * Validate a producer→consumer handoff against specialists/contracts.json.
  *
  * Args:
  *   producer    — agent or persona name producing the artifact

package/lib/migrations/index.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/migrations/index.mjs — Schema migration registry and runner.
  *
- * Construct's machine-readable artifacts (agents/registry.json, contracts.json,
+ * Construct's machine-readable artifacts (specialists/registry.json, contracts.json,
  * role-manifests.json, .cx/config.json, profile JSON) carry an integer
  * `version` field. When the installed binary's expected schema version is
  * higher than the on-disk version, migrations apply in order. When the on-disk

package/lib/model-registry.mjs

@@ -19,7 +19,7 @@ import path from 'node:path';
  * RESOLUTION ORDER (highest to lowest):
  * 1. Environment variables (CX_MODEL_*): Emergency overrides
  * 2. User config (~/.construct/config.env): Personal defaults
- * 3. Registry (agents/registry.json): Project recommendations
+ * 3. Registry (specialists/registry.json): Project recommendations
  * 4. Built-in defaults: Last resort fallbacks
  * 
  * Primary resolution path. All code must use this function.

package/lib/opencode-runtime-plugin.mjs

@@ -415,7 +415,7 @@ function buildHostConstraints() {
 
 function readRegistryModels(rootDir) {
   try {
-    const registryPath = join(rootDir, "agents", "registry.json");
+    const registryPath = join(rootDir, "specialists", "registry.json");
     if (!existsSync(registryPath)) return {};
     const registry = JSON.parse(readFileSync(registryPath, "utf8"));
     return registry?.models ?? {};

package/lib/orchestration-policy.mjs

@@ -6,14 +6,14 @@
  *   2. framing/research/doc-ownership gates  (what must be true before work starts)
  *   3. contract chain (resolveContractChain)  (what the typed handoffs are)
  *
- * Agent-to-agent contracts are defined in agents/contracts.json and loaded via
- * lib/agent-contracts.mjs. That file is the single source of truth for
+ * Agent-to-agent contracts are defined in specialists/contracts.json and loaded via
+ * lib/specialist-contracts.mjs. That file is the single source of truth for
  * producer→consumer expectations, replacing the scattered DOC_OWNERSHIP map,
  * SPECIALIST_MAP, and informal "collaborators" lists for anything contract-
  * shaped. The older maps remain for quick lookups but defer to contracts.json
  * for authoritative semantics.
  */
-import { resolveContractChain } from './agent-contracts.mjs';
+import { resolveContractChain } from './specialist-contracts.mjs';
 import { verifyRoute } from './intent-classifier.mjs';
 
 export const EXECUTION_TRACKS = {
@@ -80,7 +80,7 @@ export const DOC_OWNERSHIP = {
 // Event ownership for the role framework (lib/roles/**). When a hook emits
 // an event of one of these types, the gateway routes the invocation to the
 // listed persona. Empty owners mean the event is recorded but no persona
-// fires until onboarded. Keep in sync with agents/role-manifests.json.
+// fires until onboarded. Keep in sync with specialists/role-manifests.json.
 
 export const EVENT_OWNERSHIP = {
   'push_gate.fail': 'cx-sre',