@geraldmaron/construct 1.0.14 → 1.0.15

package/lib/document-ingest.mjs

@@ -7,7 +7,7 @@
  */
 import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, extname, isAbsolute, join, parse, relative, resolve } from 'node:path';
-import { extractDocumentText, extractDocumentMetadata, isExtractableDocumentPath } from './document-extract.mjs';
+import { extractDocumentText, extractDocumentTextAsync, extractDocumentMetadata, isExtractableDocumentPath } from './document-extract.mjs';
 import { syncFileStateToSql } from './storage/sync.mjs';
 import { stampFrontmatter } from './doc-stamp.mjs';
 import { KNOWLEDGE_ROOT, KNOWLEDGE_SUBDIRS } from './knowledge/layout.mjs';
@@ -127,6 +127,8 @@ export async function ingestDocuments(inputPaths, {
   outputDir = null,
   target = 'knowledge/internal',
   sync = false,
+  strict = false,
+  highFidelity = true,
   env = process.env,
 } = {}) {
   if (!Array.isArray(inputPaths) || inputPaths.length === 0) {
@@ -142,8 +144,12 @@ export async function ingestDocuments(inputPaths, {
   }
 
   const results = [];
+  let totalDrops = 0;
   for (const sourcePath of files) {
-    const extracted = extractDocumentText(sourcePath, { maxChars: 200_000 });
+    const extracted = highFidelity
+      ? await extractDocumentTextAsync(sourcePath, { maxChars: 200_000 })
+      : extractDocumentText(sourcePath, { maxChars: 200_000 });
+    totalDrops += (extracted.droppedInfo ?? []).reduce((a, d) => a + (Number(d.count) || 1), 0);
     const metadata = extractDocumentMetadata(sourcePath);
     const targetPath = resolveOutputPath(sourcePath, { cwd, outputPath, outputDir, target });
     ensureDir(dirname(targetPath));
@@ -184,6 +190,13 @@ export async function ingestDocuments(inputPaths, {
     });
   }
 
+  if (strict && totalDrops > 0) {
+    const err = new Error(`--strict: ${totalDrops} dropped items across ${results.filter(r => r.droppedInfo.length).length} files`);
+    err.code = 'INGEST_DROPS';
+    err.droppedInfo = results.flatMap((r) => r.droppedInfo.map((d) => ({ ...d, sourcePath: r.sourcePath })));
+    throw err;
+  }
+
   return {
     status: 'ok',
     target: outputPath ? 'custom' : target,
@@ -197,6 +210,9 @@ export async function ingestDocuments(inputPaths, {
     indexedLocally: true,
     storageSync: syncResult,
     files: results,
+    droppedInfo: results.flatMap((r) => r.droppedInfo.map((d) => ({ ...d, sourcePath: r.sourcePath }))),
+    droppedCount: totalDrops,
+    highFidelity,
   };
 }
 
@@ -206,19 +222,25 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
   let outputDir = null;
   let target = 'knowledge/internal';
   let sync = false;
+  let strict = false;
+  let highFidelity = true;
 
   for (const arg of argv) {
     if (arg.startsWith('--out=')) outputPath = arg.split('=').slice(1).join('=');
     else if (arg.startsWith('--out-dir=')) outputDir = arg.split('=').slice(1).join('=');
     else if (arg.startsWith('--target=')) target = arg.split('=').slice(1).join('=');
     else if (arg === '--sync') sync = true;
+    else if (arg === '--strict') strict = true;
+    else if (arg === '--legacy-extractor') highFidelity = false;
     else inputs.push(arg);
   }
 
   if (inputs.length === 0) {
     throw new Error(
       `Usage: construct ingest <file-or-dir> [more paths] [--out=FILE] [--out-dir=DIR] ` +
-      `[--target=sibling|knowledge/<subdir>] [--sync]\n` +
+      `[--target=sibling|knowledge/<subdir>] [--sync] [--strict] [--legacy-extractor]\n` +
+      `  --strict: exit non-zero if any extraction drops occur\n` +
+      `  --legacy-extractor: use the pre-docling regex extractor (lower fidelity)\n` +
       `  knowledge subdirs: ${KNOWLEDGE_SUBDIRS.join(', ')}`,
     );
   }
@@ -229,5 +251,5 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
     );
   }
 
-  return ingestDocuments(inputs, { cwd, outputPath, outputDir, target, sync, env });
+  return ingestDocuments(inputs, { cwd, outputPath, outputDir, target, sync, strict, highFidelity, env });
 }

package/lib/embed/daemon.mjs

@@ -1095,7 +1095,12 @@ this.#scheduler.register(
                 outputTokens = data.usage?.completion_tokens || 0;
               }
             }
-          } catch { /* probe call failed — still record timing */ }
+          } catch (probeErr) {
+            // Probe call failed; record the timing entry but surface the
+            // failure to the daemon log so operators can distinguish a 0ms
+            // success from a hard error. Don't crash the daemon.
+            process.stderr.write(`[embed] Probe call failed: ${probeErr.message}\n`);
+          }
 
           const endTime = Date.now();
 

package/lib/flavors/loader.mjs

@@ -6,7 +6,7 @@
  *   - validateFlavor(path) — frontmatter conformance check against the schema
  *   - perRoleFlavorCount(profile) — flavor counts per role for cap enforcement
  *
- * The cap is enforced at sync time and in lint-prose's sibling lint-flavors.
+ * The cap is enforced at sync time and in lint-profiles.
  * Six flavors per role per profile is the current ceiling; bumping requires
  * an ADR. Existing roles like qa already have 6, so the cap is set tight.
  */

package/lib/handoffs/contract.mjs

@@ -38,7 +38,7 @@
  *
  * `parseHandoff` is intentionally permissive — pre-contract handoffs with
  * no frontmatter still parse with status='legacy' so they aren't lost.
- * `validateHandoff` is the strict version, used when writing.
+ * `validateHandoffFile` is the strict version, used when writing.
  */
 
 import { readFileSync } from 'node:fs';
@@ -109,7 +109,7 @@ export function parseHandoffFile(filePath) {
   return parseHandoff(text);
 }
 
-export function validateHandoff(parsed) {
+export function validateHandoffFile(parsed) {
   const errors = [];
   const fm = parsed?.frontmatter || {};
   if (fm.schema !== HANDOFF_SCHEMA_VERSION) errors.push(`schema must be '${HANDOFF_SCHEMA_VERSION}'`);

package/lib/hooks/session-start.mjs

@@ -271,7 +271,7 @@ try {
   if (hasSources) {
     const parts = [];
     if (repos.length > 0) parts.push(`GitHub repos: ${repos.join(', ')}`);
-    if (jiraConfigured) parts.push(`Jira: ${process.env.JIRA_BASE_URL}`);
+    if (jiraConfigured) parts.push('Jira: configured');
     if (linearConfigured) parts.push('Linear: configured');
     // Surface which sources are wired so `provider_fetch` is the obvious
     // tool for questions about them. The "fetch first, don't answer from

package/lib/ingest/chunker.mjs

@@ -0,0 +1,94 @@
+/**
+ * lib/ingest/chunker.mjs — paragraph-boundary chunker with sentence overlap.
+ *
+ * 2026-06 best practice notes:
+ *   - Recursive/sentence chunking remains the high-recall default (~85-90%
+ *     on 2026 RAG benchmarks). Semantic chunking gains only ~2-3% recall at
+ *     ~14× the embedding cost and only matters above ~5k token docs.
+ *   - Parent-document retrieval is the meaningful 2026 upgrade beyond
+ *     paragraph chunking — track separately if recall plateaus.
+ *
+ * Strategy:
+ *   1. Split markdown by blank-line paragraph boundaries.
+ *   2. Pack paragraphs into chunks under maxChars (default 1500 ≈ 375 tokens).
+ *   3. Add 1-2 sentence overlap between consecutive chunks to preserve
+ *      cross-chunk anchors.
+ *   4. Preserve markdown structure: never split inside a fenced code block.
+ */
+
+const DEFAULT_MAX_CHARS = 1500;
+const DEFAULT_OVERLAP_SENTENCES = 2;
+const SENTENCE_RE = /[^.!?]+[.!?]+["')\]]*\s*/g;
+
+export function splitSentences(text) {
+  const matches = text.match(SENTENCE_RE);
+  if (matches && matches.length) return matches.map((s) => s.trim()).filter(Boolean);
+  return text.split('\n').map((s) => s.trim()).filter(Boolean);
+}
+
+function tailSentences(text, count) {
+  const sentences = splitSentences(text);
+  return sentences.slice(-count).join(' ');
+}
+
+function splitParagraphs(markdown) {
+  const blocks = [];
+  let buffer = '';
+  let inFence = false;
+  for (const line of markdown.split('\n')) {
+    if (/^```/.test(line.trim())) inFence = !inFence;
+    if (!inFence && line.trim() === '' && buffer.trim()) {
+      blocks.push(buffer.trim());
+      buffer = '';
+      continue;
+    }
+    buffer += line + '\n';
+  }
+  if (buffer.trim()) blocks.push(buffer.trim());
+  return blocks;
+}
+
+export function chunkMarkdown(markdown, { maxChars = DEFAULT_MAX_CHARS, overlapSentences = DEFAULT_OVERLAP_SENTENCES } = {}) {
+  const paragraphs = splitParagraphs(markdown || '');
+  if (paragraphs.length === 0) return [];
+
+  const chunks = [];
+  let current = '';
+  let chunkIndex = 0;
+  const flushChunk = () => {
+    if (!current.trim()) return;
+    const text = current.trim();
+    chunks.push({
+      index: chunkIndex++,
+      text,
+      chars: text.length,
+    });
+    const overlap = overlapSentences > 0 ? tailSentences(text, overlapSentences) : '';
+    current = overlap ? overlap + '\n\n' : '';
+  };
+
+  for (const para of paragraphs) {
+    if (current.length + para.length + 2 > maxChars && current.trim()) {
+      flushChunk();
+    }
+    if (para.length > maxChars) {
+      flushChunk();
+      const sentences = splitSentences(para);
+      let buf = '';
+      for (const s of sentences) {
+        if (buf.length + s.length + 1 > maxChars && buf.trim()) {
+          chunks.push({ index: chunkIndex++, text: buf.trim(), chars: buf.trim().length });
+          buf = (overlapSentences > 0 ? tailSentences(buf, overlapSentences) : '') + (overlapSentences > 0 ? ' ' : '');
+        }
+        buf += s + ' ';
+      }
+      if (buf.trim()) {
+        current = buf.trim() + '\n\n';
+      }
+      continue;
+    }
+    current += (current ? '\n\n' : '') + para;
+  }
+  flushChunk();
+  return chunks;
+}

package/lib/ingest/pipeline.mjs

@@ -0,0 +1,53 @@
+/**
+ * lib/ingest/pipeline.mjs — orchestrate the content-hashed ingest pipeline.
+ *
+ * Flow: hash → de-dup → extract via docling/whisper → chunk → write to
+ * .cx/ingest/<sha>/. Returns a record describing what was stored along
+ * with any droppedInfo surfaced by the extractor.
+ *
+ * Idempotent: re-ingesting the same content (by sha256) returns the
+ * existing record without re-extracting.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { extractDocumentTextAsync } from '../document-extract.mjs';
+import { hashFile, defaultIngestRoot, readRecord, writeRecord } from './store.mjs';
+import { chunkMarkdown } from './chunker.mjs';
+
+export async function ingestFile(filePath, { cwd = process.cwd(), force = false } = {}) {
+  const absPath = path.resolve(filePath);
+  const stat = await fs.stat(absPath);
+  if (!stat.isFile()) throw new Error(`not a regular file: ${absPath}`);
+
+  const root = defaultIngestRoot(cwd);
+  const sha256 = await hashFile(absPath);
+
+  if (!force) {
+    const existing = await readRecord(root, sha256);
+    if (existing) return { ...existing, status: 'cached' };
+  }
+
+  const extracted = await extractDocumentTextAsync(absPath);
+  const markdown = extracted.markdown ?? extracted.text ?? '';
+  const chunks = chunkMarkdown(markdown);
+
+  const source = {
+    sourcePath: absPath,
+    fileName: path.basename(absPath),
+    extension: extracted.extension,
+    bytes: stat.size,
+    sha256,
+    ingestedAt: new Date().toISOString(),
+  };
+
+  const meta = {
+    extractionMethod: extracted.extractionMethod,
+    extractorMetadata: extracted.metadata ?? null,
+    droppedInfo: extracted.droppedInfo ?? [],
+    chunkCount: chunks.length,
+    chunkChars: chunks.reduce((a, c) => a + c.chars, 0),
+  };
+
+  const record = await writeRecord(root, { sha256, source, meta, markdown });
+  return { ...record, status: 'ingested', droppedInfo: meta.droppedInfo, chunks };
+}

package/lib/ingest/store.mjs

@@ -0,0 +1,82 @@
+/**
+ * lib/ingest/store.mjs — content-addressed ingest store at .cx/ingest/<hash>/.
+ *
+ * Each ingested document is stored under its SHA-256 content hash:
+ *   .cx/ingest/<sha256>/source.json   — original path, size, sha256, ingestedAt
+ *   .cx/ingest/<sha256>/markdown.md   — extracted markdown body
+ *   .cx/ingest/<sha256>/meta.json     — extractor metadata, droppedInfo, chunks
+ *
+ * Idempotent: re-ingesting a file with the same content is a no-op (returns
+ * the existing record). Re-running ingestion is the safe default.
+ *
+ * 2026-06 best practice notes:
+ *   - SHA-256 is still the universal content-addressing primitive. BLAKE3 is
+ *     ~2.3× faster on M-series and worth considering at multi-GB scale,
+ *     but is not the industry default and adds an unfamiliar dependency.
+ *     Revisit if ingest throughput becomes a measured bottleneck.
+ *   - Storing markdown body separately from metadata keeps the embedding
+ *     and search paths simple: they only read markdown.md and look up
+ *     provenance from meta.json on demand.
+ */
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export function defaultIngestRoot(cwd = process.cwd()) {
+  return path.join(cwd, '.cx', 'ingest');
+}
+
+export async function hashFile(filePath) {
+  return new Promise((resolveHash, reject) => {
+    const hash = createHash('sha256');
+    const stream = createReadStream(filePath);
+    stream.on('data', (chunk) => hash.update(chunk));
+    stream.on('error', reject);
+    stream.on('end', () => resolveHash(hash.digest('hex')));
+  });
+}
+
+function recordDirFor(root, sha256) {
+  return path.join(root, sha256);
+}
+
+export async function readRecord(root, sha256) {
+  const dir = recordDirFor(root, sha256);
+  try {
+    const [source, meta, markdown] = await Promise.all([
+      fs.readFile(path.join(dir, 'source.json'), 'utf8').then(JSON.parse),
+      fs.readFile(path.join(dir, 'meta.json'), 'utf8').then(JSON.parse),
+      fs.readFile(path.join(dir, 'markdown.md'), 'utf8'),
+    ]);
+    return { sha256, source, meta, markdown, dir };
+  } catch {
+    return null;
+  }
+}
+
+export async function writeRecord(root, { sha256, source, meta, markdown }) {
+  const dir = recordDirFor(root, sha256);
+  await fs.mkdir(dir, { recursive: true });
+  await Promise.all([
+    fs.writeFile(path.join(dir, 'source.json'), JSON.stringify(source, null, 2) + '\n', 'utf8'),
+    fs.writeFile(path.join(dir, 'meta.json'), JSON.stringify(meta, null, 2) + '\n', 'utf8'),
+    fs.writeFile(path.join(dir, 'markdown.md'), markdown, 'utf8'),
+  ]);
+  return { sha256, dir, source, meta, markdown };
+}
+
+export async function listRecords(root) {
+  let entries;
+  try { entries = await fs.readdir(root, { withFileTypes: true }); }
+  catch { return []; }
+  const records = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const sha = entry.name;
+    if (!/^[a-f0-9]{64}$/.test(sha)) continue;
+    const record = await readRecord(root, sha);
+    if (record) records.push(record);
+  }
+  return records;
+}

package/lib/knowledge/search.mjs

@@ -80,6 +80,18 @@ function buildSourceList(repoRoot = REPO_ROOT) {
     }
   }
 
+  // User-ingested documents (PDF/Office/audio routed through docling + whisper)
+  const ingestRoot = join(repoRoot, '.cx', 'ingest');
+  if (existsSync(ingestRoot)) {
+    for (const entry of readdirSync(ingestRoot)) {
+      const dir = join(ingestRoot, entry);
+      const markdown = join(dir, 'markdown.md');
+      if (!/^[a-f0-9]{64}$/.test(entry)) continue;
+      if (!existsSync(markdown)) continue;
+      sources.push({ path: markdown, rel: relative(repoRoot, markdown), priority: 4, source: 'ingest' });
+    }
+  }
+
   return sources;
 }
 

package/lib/mcp/server.mjs

@@ -116,7 +116,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'extract_document_text',
-      description: 'Extracts readable text from a local document path. Supports PDF on macOS plus common text and office document formats.',
+      description: 'Extracts readable text from a local document path. High-fidelity backend (docling Python sidecar via uv, whisper.cpp for audio/video) is wired into `construct ingest`; this MCP path returns the legacy regex extraction for backwards compatibility. Supports PDF, DOCX, XLSX, PPTX, HTML, plain text, email, and transcripts.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -903,6 +903,147 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
       },
     },
+    {
+      name: 'workflow_init',
+      description: 'Initialize a new workflow for the current project. Creates plan.md state if not already present and returns the initial workflow envelope.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          cwd: { type: 'string', description: 'Project root (default: server cwd).' },
+          title: { type: 'string', description: 'Workflow title shown in the plan header (default: "Untitled workflow").' },
+          spec_ref: { type: 'string', description: 'Optional reference to a spec/PRD/ADR id this workflow implements.' },
+        },
+      },
+    },
+    {
+      name: 'workflow_add_task',
+      description: 'Add a task to the current workflow. Pass `request` for intent-based routing (the classifier picks track + specialist) or pass explicit task fields (`key`, `title`, etc.) for manual entry.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          cwd: { type: 'string', description: 'Project root (default: server cwd).' },
+          request: { type: 'string', description: 'Natural-language task request; when present, intent-based routing is used and the explicit fields below act as overrides.' },
+          key: { type: 'string', description: 'Stable task key (e.g. T-001). Generated when omitted.' },
+          title: { type: 'string', description: 'Short task title.' },
+          phase: { type: 'string', description: 'Phase bucket (plan, build, validate, ship, etc.).' },
+          owner: { type: 'string', description: 'Specialist or persona that owns the task.' },
+          files: { type: 'array', items: { type: 'string' }, description: 'File paths this task touches.' },
+          readFirst: { type: 'array', items: { type: 'string' }, description: 'Files the owner should read before editing.' },
+          doNotChange: { type: 'array', items: { type: 'string' }, description: 'Files/regions the owner must not modify.' },
+          acceptanceCriteria: { type: 'array', items: { type: 'string' }, description: 'Acceptance criteria as a checklist.' },
+          verification: { type: 'string', description: 'Command(s) or description of how to verify the task is done.' },
+          dependsOn: { type: 'array', items: { type: 'string' }, description: 'Task keys this task depends on.' },
+          overlays: { type: 'array', items: { type: 'string' }, description: 'Role flavors that augment the owner persona for this task.' },
+          challengeRequired: { type: 'boolean', description: 'Force a cx-devil-advocate challenge before the task can complete.' },
+          challengeStatus: { type: 'string', description: 'Initial challenge status when seeded.' },
+          tokenBudget: { type: 'number', description: 'Per-task token budget for cost tracking.' },
+          status: { type: 'string', description: 'Initial status override.' },
+        },
+      },
+    },
+    {
+      name: 'workflow_update_task',
+      description: 'Update fields on an existing workflow task. Requires the task `key`. Only fields supplied are changed.',
+      inputSchema: {
+        type: 'object',
+        required: ['key'],
+        properties: {
+          cwd: { type: 'string', description: 'Project root (default: server cwd).' },
+          key: { type: 'string', description: 'Task key to update.' },
+          status: { type: 'string', description: 'New status (pending, in_progress, blocked_needs_user, blocked_by_dep, done, etc.).' },
+          owner: { type: 'string', description: 'New owner persona.' },
+          phase: { type: 'string', description: 'New phase bucket.' },
+          note: { type: 'string', description: 'Append-only progress note.' },
+          verification: { type: 'string', description: 'Updated verification description.' },
+          overlays: { type: 'array', items: { type: 'string' }, description: 'Replace the overlay list.' },
+          challengeRequired: { type: 'boolean', description: 'Toggle whether a challenge is required.' },
+          challengeStatus: { type: 'string', description: 'Update the challenge status (proposed, accepted, refused, etc.).' },
+        },
+      },
+    },
+    {
+      name: 'workflow_needs_main_input',
+      description: 'Mark a workflow task as blocked pending user input. Sets status to blocked_needs_user and writes a packet describing the blocker for the orchestrator to surface.',
+      inputSchema: {
+        type: 'object',
+        required: ['taskKey', 'blocker', 'question'],
+        properties: {
+          cwd: { type: 'string', description: 'Project root (default: server cwd).' },
+          taskKey: { type: 'string', description: 'Task key to mark blocked.' },
+          worker: { type: 'string', description: 'Specialist that needs input (default: current owner).' },
+          blocker: { type: 'string', description: 'One-line description of what is blocking progress.' },
+          question: { type: 'string', description: 'The specific question to put to the user.' },
+        },
+      },
+    },
+    {
+      name: 'workflow_validate',
+      description: 'Validate the current workflow state against the schema and run consistency checks (no orphan tasks, no circular dependencies, every owner resolves to a known persona).',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          cwd: { type: 'string', description: 'Project root (default: server cwd).' },
+        },
+      },
+    },
+    {
+      name: 'workflow_status',
+      description: 'Return the full workflow snapshot for the current project: tasks, summary, alignment health, and the public-health surface used by the dashboard.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          cwd: { type: 'string', description: 'Project root (default: server cwd).' },
+        },
+      },
+    },
+    {
+      name: 'workflow_contract_validate',
+      description: 'Validate a producer→consumer handoff against specialists/contracts.json. Required when a specialist hands off to another role: enforces input.mustContain, output schema, disk-artifact postconditions, and binary postconditions per producer (rubber-stamp prevention, post-hoc threat-model prevention, etc.). Self-enforcing: a producer with binary rules MUST pass `packet`, or the call itself is a contract violation.',
+      inputSchema: {
+        type: 'object',
+        required: ['producer', 'consumer'],
+        properties: {
+          producer: { type: 'string', description: 'Producer agent or persona name (e.g. cx-reviewer, cx-security).' },
+          consumer: { type: 'string', description: 'Consumer agent or persona name receiving the handoff.' },
+          id: { type: 'string', description: 'Optional contract id; overrides producer/consumer lookup.' },
+          artifact: { type: 'object', description: 'The handoff payload to validate against the contract schema and disk-artifact postconditions.' },
+          packet: { type: 'object', description: 'The producer\'s in-memory output packet. REQUIRED when the producer has binary postconditions; omitting it is itself a contract violation.' },
+          enforcement: { type: 'string', enum: ['block', 'warn'], description: 'Enforcement mode (default: block). Use warn only when explicitly advisory.' },
+        },
+      },
+    },
+    {
+      name: 'workflow_import_plan',
+      description: 'Bulk-add tasks from a markdown plan to the current workflow. Parses headings and bullet structure to extract task titles, owners, and acceptance criteria.',
+      inputSchema: {
+        type: 'object',
+        required: ['markdown'],
+        properties: {
+          cwd: { type: 'string', description: 'Project root (default: server cwd).' },
+          markdown: { type: 'string', description: 'Plan markdown to parse.' },
+          phase: { type: 'string', description: 'Phase bucket applied to all imported tasks.' },
+          owner: { type: 'string', description: 'Default owner for tasks that do not specify one.' },
+          readFirst: { type: 'array', items: { type: 'string' }, description: 'Default readFirst files applied to all imported tasks.' },
+          doNotChange: { type: 'array', items: { type: 'string' }, description: 'Default doNotChange files applied to all imported tasks.' },
+          acceptanceCriteria: { type: 'array', items: { type: 'string' }, description: 'Default acceptance criteria applied to all imported tasks.' },
+          title: { type: 'string', description: 'Workflow title to set if the workflow is newly created.' },
+          spec_ref: { type: 'string', description: 'Spec reference to associate with the workflow.' },
+        },
+      },
+    },
+    {
+      name: 'cx_trace_telemetry',
+      description: 'Record a single CX telemetry trace for an agent invocation. Use to log start/end, model used, token cost, and outcome verdict for performance review.',
+      inputSchema: {
+        type: 'object',
+        required: ['agent', 'trace'],
+        properties: {
+          agent: { type: 'string', description: 'Agent or persona name being traced.' },
+          trace: { type: 'object', description: 'Trace record: start_ts, end_ts, model, tokens, verdict, notes, etc.' },
+          cwd: { type: 'string', description: 'Project root (default: server cwd).' },
+        },
+      },
+    },
   ],
 }));
 

package/lib/mcp/tools/skills.mjs

@@ -7,7 +7,7 @@
  */
 import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import { routeRequest, routeRequestVerified, requiresExecutiveApproval, TERMINAL_STATES } from '../../orchestration-policy.mjs';
 import { buildTaskPacketFromIntent } from '../../workflow-state.mjs';
 import { logSkillCall } from '../../telemetry/skill-calls.mjs';
@@ -73,12 +73,15 @@ export function searchSkills(args, { ROOT_DIR }) {
   if (!pattern) return { error: 'Missing pattern argument' };
   const skillsDir = join(ROOT_DIR, 'skills');
 
+  // argv-array form: pattern is a discrete argument, never interpreted by a
+  // shell. MCP tool inputs are model-controlled and must not reach a shell.
+
   try {
-    const output = execSync(`rg -i "${pattern.replace(/"/g, '\\"')}" "${skillsDir}"`, { encoding: 'utf8' });
+    const output = execFileSync('rg', ['-i', pattern, skillsDir], { encoding: 'utf8' });
     return { results: output.split('\n').filter(Boolean) };
   } catch {
     try {
-      const output = execSync(`grep -ri "${pattern.replace(/"/g, '\\"')}" "${skillsDir}"`, { encoding: 'utf8' });
+      const output = execFileSync('grep', ['-ri', pattern, skillsDir], { encoding: 'utf8' });
       return { results: output.split('\n').filter(Boolean) };
     } catch {
       return { results: [], note: 'No matches found or grep error' };

package/lib/mcp/tools/workflow.mjs

@@ -104,7 +104,10 @@ export function workflowValidate(args) {
  *   consumer    — agent or persona name receiving it
  *   id          — optional contract id (overrides producer/consumer lookup)
  *   artifact    — the handoff payload to validate
- *   enforcement — 'warn' (default) or 'block'; 'block' returns ok:false on
+ *   packet      — the producer's in-memory output packet. Required when the
+ *                 producer has binary postconditions; omitting it is itself
+ *                 a contract violation.
+ *   enforcement — 'block' (default) or 'warn'; 'block' returns ok:false on
  *                 violation so the workflow can refuse to advance
  *
  * Returns { ok, status?, errors?, warnings?, contract } where status is set
@@ -117,7 +120,8 @@ export async function workflowContractValidate(args) {
     consumer: args.consumer,
     id: args.id,
     artifact: args.artifact,
-    enforcement: args.enforcement || process.env.CONSTRUCT_CONTRACT_ENFORCEMENT || 'warn',
+    packet: args.packet,
+    enforcement: args.enforcement || 'block',
   });
 }
 

package/lib/observation-store.mjs

@@ -112,10 +112,12 @@ function logCapDrop(rootDir, kind, dropped, total) {
 function writeIndex(rootDir, entries) {
   ensureDir(obsDir(rootDir), rootDir);
   const trimmed = entries.slice(0, MAX_INDEX);
-  if (entries.length > MAX_INDEX) {
-    logCapDrop(rootDir, 'observation-index', entries.length - MAX_INDEX, entries.length);
+  const dropped = Math.max(0, entries.length - MAX_INDEX);
+  if (dropped > 0) {
+    logCapDrop(rootDir, 'observation-index', dropped, entries.length);
   }
   fs.writeFileSync(indexPath(rootDir), JSON.stringify(trimmed, null, 2) + '\n');
+  return { dropped };
 }
 
 function readVectors(rootDir) {
@@ -130,10 +132,12 @@ function readVectors(rootDir) {
 
 function writeVectors(rootDir, records) {
   ensureDir(obsDir(rootDir), rootDir);
-  if (records.length > MAX_INDEX) {
-    logCapDrop(rootDir, 'observation-vectors', records.length - MAX_INDEX, records.length);
+  const dropped = Math.max(0, records.length - MAX_INDEX);
+  if (dropped > 0) {
+    logCapDrop(rootDir, 'observation-vectors', dropped, records.length);
   }
   fs.writeFileSync(vectorsPath(rootDir), JSON.stringify(records, null, 2) + '\n');
+  return { dropped };
 }
 
 /**
@@ -188,6 +192,7 @@ export async function addObservation(rootDir, {
     JSON.stringify(record, null, 2) + '\n',
   );
 
+  let indexDropped = 0;
   withFileLockSync(indexPath(rootDir), () => {
     const index = readIndex(rootDir);
     index.unshift({
@@ -198,8 +203,12 @@ export async function addObservation(rootDir, {
       project: record.project,
       createdAt: now,
     });
-    writeIndex(rootDir, index);
+    indexDropped = writeIndex(rootDir, index).dropped;
   });
+  if (indexDropped > 0) {
+    record.capDropped = indexDropped;
+    process.stderr.write(`[observation-store] observation cap reached: ${indexDropped} oldest entries evicted (cap=${MAX_INDEX})\n`);
+  }
 
   // Try SQL storage with neural embeddings
   try {