@geraldmaron/construct 1.0.3 → 1.0.5

package/lib/orchestration-policy.mjs

@@ -324,6 +324,14 @@ export function classifyDataEngineerFlavor(request = '') {
   return null;
 }
 
+export function classifyEngineerFlavor(request = '') {
+  const text = String(request).toLowerCase();
+  if (containsAny(text, ['llm', 'agent', 'prompt', 'eval', 'hallucination', 'rag', 'model behavior', 'model routing'])) return 'ai';
+  if (containsAny(text, ['vector', 'embedding', 'retrieval', 'warehouse', 'etl', 'elt', 'pipeline', 'streaming', 'data contract'])) return 'data';
+  if (containsAny(text, ['ci', 'build', 'deploy', 'docker', 'kubernetes', 'terraform', 'helm', 'release pipeline', 'platform tooling', 'developer experience'])) return 'platform';
+  return null;
+}
+
 export function isDataAnalysisRequest(request = '') {
   return Boolean(classifyDataAnalystFlavor(request));
 }
@@ -406,6 +414,7 @@ export function isVisualDeliverableRequest(request = '') {
 
 export function classifyRoleFlavors(request = '') {
   return {
+    engineer: classifyEngineerFlavor(request),
     architect: classifyArchitectFlavor(request),
     productManager: isProductIntelligenceRequest(request) ? classifyProductManagerFlavor(request) : null,
     qa: classifyQaFlavor(request),

package/lib/outcomes/aggregate.mjs

@@ -0,0 +1,104 @@
+/**
+ * lib/outcomes/aggregate.mjs — Per-role rolling success-rate summary.
+ *
+ * Reads `.cx/outcomes/<role>.jsonl` files and produces `_summary.json`:
+ *
+ *   { generatedAt, roles: { <role>: { count, success, successRate,
+ *                                     p50DurationMs, last30: { count, successRate } } } }
+ *
+ * The classifier reads `successRate` to apply a tie-breaker soft re-rank
+ * (capped at ±0.05 in lib/intake/classify.mjs so it cannot invert the
+ * primary keyword signal).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { listOutcomes } from './record.mjs';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const LAST_WINDOW_DAYS = 30;
+
+function median(nums) {
+  if (nums.length === 0) return null;
+  const sorted = [...nums].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0 ? Math.round((sorted[mid - 1] + sorted[mid]) / 2) : sorted[mid];
+}
+
+function rollupRole(outcomes) {
+  const total = outcomes.length;
+  if (total === 0) return null;
+  const success = outcomes.filter((o) => o.success === true).length;
+  const durations = outcomes
+    .map((o) => o.durationMs)
+    .filter((d) => Number.isFinite(d) && d > 0);
+
+  const cutoff = Date.now() - LAST_WINDOW_DAYS * DAY_MS;
+  const recent = outcomes.filter((o) => Date.parse(o.ts) >= cutoff);
+  const recentSuccess = recent.filter((o) => o.success === true).length;
+
+  return {
+    count: total,
+    success,
+    successRate: total > 0 ? Number((success / total).toFixed(3)) : 0,
+    p50DurationMs: median(durations),
+    last30: {
+      count: recent.length,
+      successRate: recent.length > 0 ? Number((recentSuccess / recent.length).toFixed(3)) : 0,
+    },
+  };
+}
+
+/**
+ * List every role with outcome data in this project. Returns role ids.
+ */
+export function listRolesWithOutcomes(cwd) {
+  const dir = path.join(cwd, '.cx', 'outcomes');
+  if (!fs.existsSync(dir)) return [];
+  const seen = new Set();
+  for (const f of fs.readdirSync(dir)) {
+    const m = /^([a-z0-9-]+)(\.\d+)?\.jsonl$/.exec(f);
+    if (m) seen.add(m[1]);
+  }
+  return Array.from(seen).sort();
+}
+
+/**
+ * Rebuild the summary from all per-role JSONL files. Idempotent.
+ */
+export function aggregateOutcomes(cwd) {
+  const roles = listRolesWithOutcomes(cwd);
+  const out = { generatedAt: new Date().toISOString(), roles: {} };
+  for (const role of roles) {
+    const rollup = rollupRole(listOutcomes(cwd, role));
+    if (rollup) out.roles[role] = rollup;
+  }
+  const dir = path.join(cwd, '.cx', 'outcomes');
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, '_summary.json'), JSON.stringify(out, null, 2) + '\n');
+  return out;
+}
+
+/**
+ * Read the cached summary without recomputing. Keeps the classifier
+ * tiebreaker on an O(1) hot path.
+ */
+export function readSummary(cwd) {
+  const p = path.join(cwd, '.cx', 'outcomes', '_summary.json');
+  if (!fs.existsSync(p)) return null;
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; }
+}
+
+/**
+ * Tiebreaker score for the classifier. Returns a number in [-0.05, 0.05]
+ * derived from the role's recent success rate. Default behavior on missing
+ * data is 0 (no influence).
+ */
+export function outcomeBoost(cwd, role, { cap = 0.05 } = {}) {
+  const summary = readSummary(cwd);
+  const stats = summary?.roles?.[role];
+  if (!stats || !stats.last30 || stats.last30.count < 3) return 0;
+  // Map [0.5, 1.0] success → [0, cap]; [0, 0.5] → [-cap, 0]. Linear, capped.
+  const rate = stats.last30.successRate;
+  const centered = (rate - 0.5) * 2; // [-1, 1]
+  return Math.max(-cap, Math.min(cap, centered * cap));
+}

package/lib/outcomes/record.mjs

@@ -0,0 +1,115 @@
+/**
+ * lib/outcomes/record.mjs — Specialist outcome recorder.
+ *
+ * Records the result of every dispatched specialist into
+ * `.cx/outcomes/<role>.jsonl`. The aggregator (lib/outcomes/aggregate.mjs)
+ * reads these files to produce per-role rolling success rates, which the
+ * classifier consumes as a soft tiebreaker.
+ *
+ * Schema (one JSONL line per outcome):
+ *   { ts, role, intakeId, profile, success, escalated, durationMs, notes,
+ *     source: 'agent-tracker' | 'feedback' | 'manual' }
+ *
+ * Files rotate at 10k lines per role to keep disk bounded. The rotated file
+ * is named `<role>.<yyyymm>.jsonl`. Current is always `<role>.jsonl`.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { withFileLockSync } from '../storage/file-lock.mjs';
+
+const ROTATE_AT = 10_000;
+const MAX_NOTES = 500;
+
+function safeRole(role) {
+  return String(role || 'unknown').replace(/[^a-z0-9-]/gi, '-').toLowerCase().slice(0, 60) || 'unknown';
+}
+
+function outcomesDir(cwd) {
+  return path.join(cwd, '.cx', 'outcomes');
+}
+
+function activeFile(cwd, role) {
+  return path.join(outcomesDir(cwd), `${safeRole(role)}.jsonl`);
+}
+
+function rotatedFile(cwd, role) {
+  const stamp = new Date().toISOString().slice(0, 7).replace('-', ''); // yyyymm
+  return path.join(outcomesDir(cwd), `${safeRole(role)}.${stamp}.jsonl`);
+}
+
+function countLines(file) {
+  try {
+    const buf = fs.readFileSync(file);
+    let n = 0;
+    for (let i = 0; i < buf.length; i++) if (buf[i] === 0x0a) n++;
+    return n;
+  } catch { return 0; }
+}
+
+/**
+ * Record a specialist outcome. Best-effort: any IO failure is swallowed and
+ * the caller proceeds. Outcomes are telemetry, never on the critical path.
+ *
+ * @param {string} cwd - project root
+ * @param {object} payload
+ * @param {string} payload.role - specialist id (cx-engineer → 'engineer')
+ * @param {string} [payload.intakeId]
+ * @param {string} [payload.profile] - active profile id
+ * @param {boolean} payload.success
+ * @param {boolean} [payload.escalated]
+ * @param {number} [payload.durationMs]
+ * @param {string} [payload.notes]
+ * @param {string} [payload.source='manual']
+ * @returns {string|null} path to the file written, or null on failure
+ */
+export function recordOutcome(cwd, payload) {
+  if (!cwd || !payload || typeof payload.success !== 'boolean') return null;
+  try {
+    fs.mkdirSync(outcomesDir(cwd), { recursive: true });
+    const file = activeFile(cwd, payload.role);
+
+    if (countLines(file) >= ROTATE_AT) {
+      try { fs.renameSync(file, rotatedFile(cwd, payload.role)); } catch { /* race */ }
+    }
+
+    const entry = {
+      ts: new Date().toISOString(),
+      role: safeRole(payload.role),
+      intakeId: payload.intakeId || null,
+      profile: payload.profile || null,
+      success: !!payload.success,
+      escalated: !!payload.escalated,
+      durationMs: Number.isFinite(payload.durationMs) ? payload.durationMs : null,
+      notes: payload.notes ? String(payload.notes).slice(0, MAX_NOTES) : null,
+      source: payload.source || 'manual',
+    };
+
+    withFileLockSync(file, () => {
+      fs.appendFileSync(file, JSON.stringify(entry) + '\n');
+    });
+    return file;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read every outcome line for a role across active + rotated files.
+ * Returns oldest-first.
+ */
+export function listOutcomes(cwd, role) {
+  const dir = outcomesDir(cwd);
+  if (!fs.existsSync(dir)) return [];
+  const safe = safeRole(role);
+  const files = fs.readdirSync(dir).filter((f) => f.startsWith(`${safe}.`) && f.endsWith('.jsonl'));
+  const out = [];
+  for (const f of files.sort()) {
+    let raw = '';
+    try { raw = fs.readFileSync(path.join(dir, f), 'utf8'); } catch { continue; }
+    for (const line of raw.split('\n')) {
+      if (!line.trim()) continue;
+      try { out.push(JSON.parse(line)); } catch { /* skip malformed */ }
+    }
+  }
+  return out;
+}

package/lib/parity.mjs

@@ -2,7 +2,7 @@
  * lib/parity.mjs — Cross-surface parity verifier.
  *
  * After `construct sync` writes adapters to multiple surfaces (Claude Code,
- * OpenCode, Codex), the module diffs each surface's actual state against the
+ * OpenCode, Codex, Copilot, VS Code, Cursor), the module diffs each surface's actual state against the
  * canonical `agents/registry.json`. Backs `construct doctor` for surfacing
  * silent divergence — for instance, an agent added to the registry that
  * never made it to OpenCode because of a sync regression.
@@ -14,9 +14,12 @@
  * the field are mirrored everywhere.
  *
  * Surfaces checked:
- *   claude   ~/.claude/agents/*.md
- *   opencode ~/.config/opencode/opencode.json (agent table)
- *   codex    ~/.codex/agents/*.toml
+ *   claude    ~/.claude/agents/*.md
+ *   opencode  ~/.config/opencode/opencode.json (agent table)
+ *   codex     ~/.codex/agents/*.toml
+ *   copilot   ~/.github/prompts/*.prompt.md
+ *   vscode    VS Code user settings (github.copilot.mcpServers)
+ *   cursor    ~/.cursor/mcp.json
  */
 
 import fs from 'node:fs';
@@ -59,16 +62,15 @@ function diffSets(expected, actual) {
   return { missing, extra };
 }
 
-function checkClaude(registry, { homeDir = os.homedir() } = {}) {
-  const dir = path.join(homeDir, '.claude', 'agents');
-  if (!fs.existsSync(dir)) return { surface: 'claude', status: 'absent', dir };
-  const expected = entriesForSurface(registry, 'claude');
+function checkFileSurface({ surface, kind, dir, extension, expected }) {
+  if (!fs.existsSync(dir)) return { surface, kind, status: 'absent', dir };
   const actual = fs.readdirSync(dir)
-    .filter((name) => name.endsWith('.md'))
-    .map((name) => name.replace(/\.md$/, ''));
+    .filter((name) => name.endsWith(extension))
+    .map((name) => name.slice(0, -extension.length));
   const { missing, extra } = diffSets(expected, actual);
   return {
-    surface: 'claude',
+    surface,
+    kind,
     status: missing.length === 0 && extra.length === 0 ? 'ok' : 'drift',
     dir,
     expectedCount: expected.length,
@@ -78,20 +80,56 @@ function checkClaude(registry, { homeDir = os.homedir() } = {}) {
   };
 }
 
+function getVSCodeSettingsPaths(homeDir) {
+  const platform = os.platform();
+  if (platform === 'darwin') {
+    return [
+      path.join(homeDir, 'Library', 'Application Support', 'Code', 'User', 'settings.json'),
+      path.join(homeDir, 'Library', 'Application Support', 'Code - Insiders', 'User', 'settings.json'),
+    ];
+  }
+  if (platform === 'linux') {
+    return [
+      path.join(homeDir, '.config', 'Code', 'User', 'settings.json'),
+      path.join(homeDir, '.config', 'Code - Insiders', 'User', 'settings.json'),
+    ];
+  }
+  if (platform === 'win32') {
+    const appData = process.env.APPDATA ?? path.join(homeDir, 'AppData', 'Roaming');
+    return [
+      path.join(appData, 'Code', 'User', 'settings.json'),
+      path.join(appData, 'Code - Insiders', 'User', 'settings.json'),
+    ];
+  }
+  return [];
+}
+
+function checkClaude(registry, { homeDir = os.homedir() } = {}) {
+  const expected = entriesForSurface(registry, 'claude');
+  return checkFileSurface({
+    surface: 'claude',
+    kind: 'agents',
+    dir: path.join(homeDir, '.claude', 'agents'),
+    extension: '.md',
+    expected,
+  });
+}
+
 function checkOpenCode(registry, { homeDir = os.homedir() } = {}) {
   const file = path.join(homeDir, '.config', 'opencode', 'opencode.json');
-  if (!fs.existsSync(file)) return { surface: 'opencode', status: 'absent', file };
+  if (!fs.existsSync(file)) return { surface: 'opencode', kind: 'agents', status: 'absent', file };
   let config;
   try {
     config = JSON.parse(fs.readFileSync(file, 'utf8'));
   } catch (err) {
-    return { surface: 'opencode', status: 'unreadable', file, error: err.message };
+    return { surface: 'opencode', kind: 'agents', status: 'unreadable', file, error: err.message };
   }
   const expected = entriesForSurface(registry, 'opencode');
   const actual = Object.keys(config.agent || config.agents || {});
   const { missing, extra } = diffSets(expected, actual);
   return {
     surface: 'opencode',
+    kind: 'agents',
     status: missing.length === 0 && extra.length === 0 ? 'ok' : 'drift',
     file,
     expectedCount: expected.length,
@@ -102,17 +140,76 @@ function checkOpenCode(registry, { homeDir = os.homedir() } = {}) {
 }
 
 function checkCodex(registry, { homeDir = os.homedir() } = {}) {
-  const dir = path.join(homeDir, '.codex', 'agents');
-  if (!fs.existsSync(dir)) return { surface: 'codex', status: 'absent', dir };
   const expected = entriesForSurface(registry, 'codex');
-  const actual = fs.readdirSync(dir)
-    .filter((name) => name.endsWith('.toml'))
-    .map((name) => name.replace(/\.toml$/, ''));
+  return checkFileSurface({
+    surface: 'codex',
+    kind: 'agents',
+    dir: path.join(homeDir, '.codex', 'agents'),
+    extension: '.toml',
+    expected,
+  });
+}
+
+function checkCopilot(registry, { homeDir = os.homedir() } = {}) {
+  // Use the same helper as Claude/OpenCode/Codex so all surfaces apply the
+  // platform-filter rules identically. The previous implementation dropped
+  // entries with internal:true, which produced false drift because the sync
+  // script writes every specialist to ~/.github/prompts regardless of the
+  // internal flag.
+  const expected = entriesForSurface(registry, 'copilot');
+  return checkFileSurface({
+    surface: 'copilot',
+    kind: 'prompts',
+    dir: path.join(homeDir, '.github', 'prompts'),
+    extension: '.prompt.md',
+    expected,
+  });
+}
+
+function checkVSCode(registry, { homeDir = os.homedir() } = {}) {
+  const paths = getVSCodeSettingsPaths(homeDir).filter((settingsPath) => fs.existsSync(settingsPath));
+  if (paths.length === 0) return { surface: 'vscode', kind: 'mcps', status: 'absent', paths };
+  const expected = Object.keys(registry.mcpServers ?? {}).filter((id) => id !== 'memory');
+  const actualSet = new Set();
+  for (const settingsPath of paths) {
+    try {
+      const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+      for (const id of Object.keys(settings['github.copilot.mcpServers'] ?? {})) actualSet.add(id);
+    } catch (err) {
+      return { surface: 'vscode', kind: 'mcps', status: 'unreadable', file: settingsPath, error: err.message };
+    }
+  }
+  const actual = [...actualSet].sort();
   const { missing, extra } = diffSets(expected, actual);
   return {
-    surface: 'codex',
+    surface: 'vscode',
+    kind: 'mcps',
     status: missing.length === 0 && extra.length === 0 ? 'ok' : 'drift',
-    dir,
+    paths,
+    expectedCount: expected.length,
+    actualCount: actual.length,
+    missing,
+    extra,
+  };
+}
+
+function checkCursor(registry, { homeDir = os.homedir() } = {}) {
+  const file = path.join(homeDir, '.cursor', 'mcp.json');
+  if (!fs.existsSync(file)) return { surface: 'cursor', kind: 'mcps', status: 'absent', file };
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    return { surface: 'cursor', kind: 'mcps', status: 'unreadable', file, error: err.message };
+  }
+  const expected = Object.keys(registry.mcpServers ?? {}).filter((id) => id !== 'memory');
+  const actual = Object.keys(config.mcpServers ?? {});
+  const { missing, extra } = diffSets(expected, actual);
+  return {
+    surface: 'cursor',
+    kind: 'mcps',
+    status: missing.length === 0 && extra.length === 0 ? 'ok' : 'drift',
+    file,
     expectedCount: expected.length,
     actualCount: actual.length,
     missing,
@@ -130,13 +227,16 @@ export function checkParity({ rootDir = ROOT_DIR, homeDir = os.homedir() } = {})
     checkClaude(registry, { homeDir }),
     checkOpenCode(registry, { homeDir }),
     checkCodex(registry, { homeDir }),
+    checkCopilot(registry, { homeDir }),
+    checkVSCode(registry, { homeDir }),
+    checkCursor(registry, { homeDir }),
   ];
 
   const ok = surfaces.every((s) => s.status === 'ok' || s.status === 'absent');
   const summary = surfaces.map((s) => {
     if (s.status === 'absent') return `${s.surface}: not installed`;
     if (s.status === 'unreadable') return `${s.surface}: unreadable (${s.error})`;
-    if (s.status === 'ok') return `${s.surface}: ok (${s.actualCount}/${s.expectedCount})`;
+    if (s.status === 'ok') return `${s.surface}: ok (${s.actualCount}/${s.expectedCount} ${s.kind})`;
     const parts = [];
     if (s.missing.length) parts.push(`missing: ${s.missing.join(', ')}`);
     if (s.extra.length) parts.push(`extra: ${s.extra.join(', ')}`);