@geraldmaron/construct 1.0.4 → 1.0.6

package/lib/mcp/server.mjs

@@ -3,7 +3,7 @@
  * lib/mcp/server.mjs — Construct MCP server: tool registry and request dispatcher.
  *
  * Thin dispatcher only — all tool implementations live in lib/mcp/tools/*.mjs.
- * Registers 40 tools across 7 modules: project, document, storage, skills, workflow, telemetry, memory.
+ * Registers 52 tools across 8 modules: project, document, storage, skills, workflow, telemetry, memory, profile.
  * Consumed by Claude Code, OpenCode, and any MCP-compatible host.
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
@@ -48,6 +48,12 @@ import {
   memorySearch, memoryAddObservations, memoryCreateEntities, memoryRecent,
   sessionList, sessionLoad, sessionSearch, sessionSave, rovoSearch,
 } from './tools/memory.mjs';
+import {
+  profileShow, profileList, profileDrafts, profileHealthTool,
+  outcomesSummary, outcomesRecord, knowledgeAdd,
+  profileCreate, profileArchive, sandboxList, learningStatus,
+  knowledgeGraphAsk,
+} from './tools/profile.mjs';
 
 const DEFAULT_ROOT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 const ROOT_DIR = resolve(process.env.CX_TOOLKIT_DIR || DEFAULT_ROOT_DIR);
@@ -711,6 +717,174 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
       },
     },
+    {
+      name: 'profile_show',
+      description: 'Return the active Construct org profile (id, displayName, roles, departments, intake taxonomy, doc templates). Use when a specialist needs to know which role set, classification taxonomy, or doc templates apply before drafting work.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          cwd: { type: 'string', description: 'Project root (default: server cwd).' },
+          id: { type: 'string', description: 'Force a specific profile id instead of resolving from config.' },
+        },
+      },
+    },
+    {
+      name: 'profile_list',
+      description: 'List the curated org profile catalog (rnd, operations, creative, research) with role/department counts. Use to discover which profiles are available before suggesting `construct profile set`.',
+      inputSchema: { type: 'object', properties: {} },
+    },
+    {
+      name: 'profile_drafts',
+      description: 'List in-progress draft profiles under `.cx/profiles/draft-*` and any user-defined custom profile at `.cx/profile.json`. Use to see what profile work is pending before scaffolding another draft.',
+      inputSchema: {
+        type: 'object',
+        properties: { cwd: { type: 'string', description: 'Project root (default: server cwd).' } },
+      },
+    },
+    {
+      name: 'profile_health',
+      description: 'Per-profile health rollup over a window: observation count, per-role outcome runs and success rates. Use to check whether a profile is producing data before recommending changes or archive.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          cwd: { type: 'string', description: 'Project root (default: server cwd).' },
+          id: { type: 'string', description: 'Profile id (default: active profile).' },
+          window_days: { type: 'number', description: 'Window in days (default 30).' },
+        },
+      },
+    },
+    {
+      name: 'outcomes_summary',
+      description: 'Read `.cx/outcomes/_summary.json` (per-role success rate, 30-day trend). Pass `aggregate=true` to rebuild the summary from JSONL outcome files first. Use to ground tiebreakers and improvement suggestions in real specialist performance.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          cwd: { type: 'string', description: 'Project root (default: server cwd).' },
+          aggregate: { type: 'boolean', description: 'Rebuild `_summary.json` before reading (default false).' },
+        },
+      },
+    },
+    {
+      name: 'outcomes_record',
+      description: 'Append a specialist outcome line to `.cx/outcomes/<role>.jsonl` (writes durable state — requires `confirm=true`). Use when a specialist wants to self-report success/failure outside the automatic agent-tracker path.',
+      inputSchema: {
+        type: 'object',
+        required: ['confirm', 'role', 'success'],
+        properties: {
+          confirm: { type: 'boolean', description: 'Must be true.' },
+          cwd: { type: 'string' },
+          role: { type: 'string', description: 'Specialist id (e.g. cx-engineer, product-manager).' },
+          success: { type: 'boolean' },
+          intake_id: { type: 'string' },
+          profile: { type: 'string', description: 'Override active profile id stamp.' },
+          escalated: { type: 'boolean' },
+          duration_ms: { type: 'number' },
+          notes: { type: 'string', description: 'Trimmed to 500 chars.' },
+          source: { type: 'string', description: 'Origin tag (default: "mcp").' },
+        },
+      },
+    },
+    {
+      name: 'knowledge_add',
+      description: 'Persist a research finding as `.cx/knowledge/external/research/<slug>.md` with research-specific frontmatter (topic, confidence, sources, expiresAt, profile). Writes durable state — requires `confirm=true`. `confidence=confirmed` requires at least one source.',
+      inputSchema: {
+        type: 'object',
+        required: ['confirm', 'slug', 'topic', 'body'],
+        properties: {
+          confirm: { type: 'boolean', description: 'Must be true.' },
+          cwd: { type: 'string' },
+          slug: { type: 'string', description: 'Lowercase hyphenated, max 60 chars.' },
+          topic: { type: 'string' },
+          body: { type: 'string', description: 'Findings / inferences / gaps / recommendation block. Capped at 50KB total file.' },
+          confidence: { type: 'string', enum: ['confirmed', 'inferred', 'weak'], description: 'Default: inferred.' },
+          sources: {
+            type: 'array',
+            description: 'Required when confidence=confirmed.',
+            items: {
+              type: 'object',
+              required: ['url'],
+              properties: {
+                url: { type: 'string' },
+                accessedAt: { type: 'string', description: 'ISO timestamp; default now.' },
+                span: { type: 'string', description: 'Citation locator; trimmed to 200 chars.' },
+              },
+            },
+          },
+          ttl_days: { type: 'number', description: 'Default 90.' },
+        },
+      },
+    },
+    {
+      name: 'profile_create',
+      description: 'Scaffold a draft org profile under `.cx/profiles/draft-<id>/` (requirements.md + profile.json + persona stubs + department charters). Writes durable state — requires `confirm=true`. For curated catalog work, follow `docs/concepts/profile-lifecycle.md` after creation.',
+      inputSchema: {
+        type: 'object',
+        required: ['confirm', 'id'],
+        properties: {
+          confirm: { type: 'boolean', description: 'Must be true.' },
+          cwd: { type: 'string' },
+          id: { type: 'string', description: 'Profile id (^[a-z][a-z0-9-]{1,30}$).' },
+          display_name: { type: 'string' },
+          seed_roles: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Role ids to scaffold persona files for (cap 80).',
+          },
+          seed_departments: {
+            type: 'array',
+            items: {
+              type: 'object',
+              required: ['id'],
+              properties: {
+                id: { type: 'string' },
+                displayName: { type: 'string' },
+              },
+            },
+            description: 'Departments to scaffold charters for (cap 12).',
+          },
+        },
+      },
+    },
+    {
+      name: 'profile_archive',
+      description: 'Archive a curated profile: moves `profiles/<id>.json` and its intake table into `archive/profiles/<id>/` with an archive note. Destructive — requires `confirm=true` and a substantive `reason` (>=8 chars). Observations and outcomes are preserved.',
+      inputSchema: {
+        type: 'object',
+        required: ['confirm', 'id', 'reason'],
+        properties: {
+          confirm: { type: 'boolean', description: 'Must be true.' },
+          id: { type: 'string' },
+          reason: { type: 'string', description: 'Substantive reason (>= 8 chars).' },
+        },
+      },
+    },
+    {
+      name: 'sandbox_list',
+      description: 'List Construct sandboxes under `~/.cx/sandboxes/` (id, path, createdAt). Use to find an isolated environment for QA or dry-runs without polluting the active project.',
+      inputSchema: { type: 'object', properties: {} },
+    },
+    {
+      name: 'knowledge_graph_ask',
+      description: 'GraphRAG-style global query over the entity graph in `.cx/observations/`. Detects communities via label propagation, ranks them by BM25 against the query, and returns each top community with its central members and extractive summary. Use for "tell me about how X relates across the project" questions that pure semantic retrieval handles poorly.',
+      inputSchema: {
+        type: 'object',
+        required: ['query'],
+        properties: {
+          query: { type: 'string', description: 'Natural-language question.' },
+          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).' },
+        },
+      },
+    },
+    {
+      name: 'learning_status',
+      description: 'One-shot mirror of `npm run learning:status`: active profile, observation counts (last 24h + total), research finding count, per-role outcome rollup. Use to answer "is Construct learning?" without spawning a shell.',
+      inputSchema: {
+        type: 'object',
+        properties: { cwd: { type: 'string', description: 'Project root (default: server cwd).' } },
+      },
+    },
     {
       name: 'knowledge_search',
       description: 'Search Construct\'s own documentation, knowledge base, and distilled embed observations. Call this immediately — no approval needed — when the user asks what Construct is, how a feature works, what commands exist, or anything about Construct\'s architecture or configuration. Also searches embed observations from GitHub, Jira, and other configured sources. Returns relevant excerpts with source file and heading.',
@@ -786,6 +960,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const { knowledgeSearch } = await import('../knowledge/search.mjs');
       result = knowledgeSearch({ query: args.query, topK: args.top_k, repoRoot: args.repo_root, rootDir: args.root_dir });
     }
+    else if (name === 'profile_show') result = profileShow(args);
+    else if (name === 'profile_list') result = profileList();
+    else if (name === 'profile_drafts') result = profileDrafts(args);
+    else if (name === 'profile_health') result = profileHealthTool(args);
+    else if (name === 'outcomes_summary') result = outcomesSummary(args);
+    else if (name === 'outcomes_record') result = outcomesRecord(args);
+    else if (name === 'knowledge_add') result = await knowledgeAdd(args);
+    else if (name === 'profile_create') result = profileCreate(args);
+    else if (name === 'profile_archive') result = profileArchive(args);
+    else if (name === 'sandbox_list') result = sandboxList();
+    else if (name === 'learning_status') result = learningStatus(args);
+    else if (name === 'knowledge_graph_ask') result = knowledgeGraphAsk(args);
     else result = { error: `Unknown tool: ${name}` };
   } catch (err) {
     result = { error: err.message ?? String(err) };

package/lib/mcp/tools/profile.mjs

@@ -0,0 +1,270 @@
+/**
+ * lib/mcp/tools/profile.mjs — MCP wrappers for the org-profile + learning surfaces.
+ *
+ * Bridges PR #67 capabilities (profiles, outcomes, sandboxes, knowledge_add,
+ * learning status) so subagents talking through the construct-mcp server can
+ * read the same state the CLI exposes. Operator-only surfaces (optimize_apply,
+ * optimize_rollback) remain CLI-only and are not registered here.
+ *
+ * Pattern: each export is a thin schema-validated wrapper around the existing
+ * lib/* function the CLI already uses. Errors return `{ error: string }` so
+ * the MCP dispatcher hands a structured failure back instead of crashing.
+ * Destructive operations (profile_archive) require `confirm: true`, matching
+ * the storage_reset / delete_ingested_artifacts pattern in tools/storage.mjs.
+ */
+import { resolve } from 'node:path';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  loadProfile,
+  listProfiles,
+  loadCustomProfile,
+  resolveActiveProfile,
+} from '../../profiles/loader.mjs';
+import {
+  createDraftProfile,
+  listDrafts,
+  archiveProfile,
+  profileHealth,
+} from '../../profiles/lifecycle.mjs';
+import { recordOutcome } from '../../outcomes/record.mjs';
+import { aggregateOutcomes, readSummary } from '../../outcomes/aggregate.mjs';
+import { addResearchFinding } from '../../knowledge/research-store.mjs';
+import { askGlobal } from '../../knowledge/graph.mjs';
+import { listSandboxes } from '../../sandbox.mjs';
+
+function cwdOf(args) {
+  return args && args.cwd ? resolve(String(args.cwd)) : process.cwd();
+}
+
+// Read-only: active profile.
+
+export function profileShow(args = {}) {
+  const cwd = cwdOf(args);
+  const profile = resolveActiveProfile(cwd, args.id ? String(args.id) : null);
+  return {
+    id: profile.id,
+    displayName: profile.displayName ?? profile.id,
+    tagline: profile.tagline ?? null,
+    custom: profile.custom === true,
+    roles: Array.isArray(profile.roles) ? profile.roles : [],
+    departments: Array.isArray(profile.departments)
+      ? profile.departments.map((d) => ({ id: d.id, displayName: d.displayName, roleCount: Array.isArray(d.roles) ? d.roles.length : 0 }))
+      : [],
+    intake: {
+      types: profile.intake?.types ?? [],
+      stages: profile.intake?.stages ?? [],
+    },
+    docTemplates: profile.docTemplates ?? [],
+    hooks: profile.hooks ?? null,
+    rebrand: profile.rebrand ?? null,
+  };
+}
+
+// Read-only: catalog summary.
+
+export function profileList() {
+  return {
+    profiles: listProfiles().map((id) => {
+      const p = loadProfile(id);
+      return p
+        ? {
+            id: p.id,
+            displayName: p.displayName ?? p.id,
+            tagline: p.tagline ?? null,
+            roleCount: Array.isArray(p.roles) ? p.roles.length : 0,
+            departmentCount: Array.isArray(p.departments) ? p.departments.length : 0,
+          }
+        : { id, error: 'failed to parse' };
+    }),
+  };
+}
+
+// Read-only: drafts + custom profile under .cx/.
+
+export function profileDrafts(args = {}) {
+  const cwd = cwdOf(args);
+  const drafts = listDrafts(cwd).map((d) => ({
+    id: d.id,
+    dir: d.dir,
+    hasProfile: d.hasProfile,
+    hasBrief: d.hasBrief,
+  }));
+  const custom = loadCustomProfile(cwd);
+  return {
+    drafts,
+    custom: custom ? { id: custom.id, displayName: custom.displayName ?? custom.id } : null,
+  };
+}
+
+// Read-only: per-profile health rollup.
+
+export function profileHealthTool(args = {}) {
+  const cwd = cwdOf(args);
+  const id = args.id ? String(args.id) : resolveActiveProfile(cwd).id;
+  const windowDays = Number.isFinite(args.window_days) ? Number(args.window_days) : 30;
+  return { id, windowDays, ...profileHealth(cwd, id, { windowDays }) };
+}
+
+// Read-only: outcomes rollup. Optional aggregate=true rebuilds _summary.json.
+
+export function outcomesSummary(args = {}) {
+  const cwd = cwdOf(args);
+  if (args.aggregate === true) {
+    try { aggregateOutcomes(cwd); } catch (err) { return { error: `aggregate failed: ${err.message}` }; }
+  }
+  const summary = readSummary(cwd);
+  if (!summary) return { roles: {}, note: 'no outcomes recorded yet' };
+  return summary;
+}
+
+// Mutating, gated: append an outcome line.
+
+export function outcomesRecord(args = {}) {
+  if (args.confirm !== true) {
+    return { error: 'outcomes_record requires confirm=true to write durable state' };
+  }
+  const cwd = cwdOf(args);
+  if (!args.role || typeof args.success !== 'boolean') {
+    return { error: 'outcomes_record requires role:string and success:boolean' };
+  }
+  const profile = args.profile ? String(args.profile) : resolveActiveProfile(cwd)?.id;
+  const file = recordOutcome(cwd, {
+    role: String(args.role),
+    intakeId: args.intake_id ? String(args.intake_id) : null,
+    profile,
+    success: !!args.success,
+    escalated: !!args.escalated,
+    durationMs: Number.isFinite(args.duration_ms) ? Number(args.duration_ms) : null,
+    notes: args.notes ? String(args.notes) : null,
+    source: args.source ? String(args.source) : 'mcp',
+  });
+  if (!file) return { error: 'outcomes_record: write failed' };
+  return { ok: true, file };
+}
+
+// Mutating, gated: persist a research finding.
+
+export async function knowledgeAdd(args = {}) {
+  if (args.confirm !== true) {
+    return { error: 'knowledge_add requires confirm=true to write durable state' };
+  }
+  const cwd = cwdOf(args);
+  try {
+    const res = await addResearchFinding({
+      cwd,
+      slug: String(args.slug || ''),
+      topic: String(args.topic || ''),
+      body: String(args.body || ''),
+      confidence: args.confidence ? String(args.confidence) : 'inferred',
+      sources: Array.isArray(args.sources) ? args.sources : [],
+      ttlDays: Number.isFinite(args.ttl_days) ? Number(args.ttl_days) : undefined,
+    });
+    return { ok: true, path: res.path, bytes: res.bytes };
+  } catch (err) {
+    return { error: err.message ?? String(err) };
+  }
+}
+
+// Mutating, gated: scaffold a draft profile.
+
+export function profileCreate(args = {}) {
+  if (args.confirm !== true) {
+    return { error: 'profile_create requires confirm=true to scaffold files' };
+  }
+  const cwd = cwdOf(args);
+  if (!args.id) return { error: 'profile_create requires id:string' };
+  try {
+    const res = createDraftProfile({
+      cwd,
+      id: String(args.id),
+      displayName: args.display_name ? String(args.display_name) : undefined,
+      seedRoles: Array.isArray(args.seed_roles) ? args.seed_roles.map(String) : [],
+      seedDepartments: Array.isArray(args.seed_departments) ? args.seed_departments : [],
+    });
+    return {
+      ok: true,
+      dir: res.dir,
+      briefPath: res.briefPath,
+      draftPath: res.draftPath,
+      personaPaths: res.personaPaths,
+      departmentPaths: res.departmentPaths,
+    };
+  } catch (err) {
+    return { error: err.message ?? String(err) };
+  }
+}
+
+// Mutating, gated, destructive: archive a curated profile.
+
+export function profileArchive(args = {}) {
+  if (args.confirm !== true) {
+    return { error: 'profile_archive requires confirm=true (destructive: moves files into archive/profiles/)' };
+  }
+  if (!args.id || !args.reason || String(args.reason).trim().length < 8) {
+    return { error: 'profile_archive requires id:string and reason:string (>=8 chars)' };
+  }
+  try {
+    return { ok: true, ...archiveProfile({ id: String(args.id), reason: String(args.reason) }) };
+  } catch (err) {
+    return { error: err.message ?? String(err) };
+  }
+}
+
+// Read-only: sandbox roster.
+
+export function sandboxList() {
+  return { sandboxes: listSandboxes() };
+}
+
+// Read-only: GraphRAG global query over the entity graph.
+
+export function knowledgeGraphAsk(args = {}) {
+  const cwd = cwdOf(args);
+  if (!args.query || typeof args.query !== 'string') {
+    return { error: 'knowledge_graph_ask requires query:string' };
+  }
+  const topK = Number.isFinite(args.top_k) ? Number(args.top_k) : 5;
+  const minSize = Number.isFinite(args.min_size) ? Number(args.min_size) : undefined;
+  return askGlobal({ query: String(args.query), rootDir: cwd, topK, ...(minSize !== undefined ? { minSize } : {}) });
+}
+
+// Read-only: learning dashboard mirror.
+
+export function learningStatus(args = {}) {
+  const cwd = cwdOf(args);
+
+  let observations = { total: 0, last24h: 0 };
+  try {
+    const idxPath = join(cwd, '.cx', 'observations', 'index.json');
+    if (existsSync(idxPath)) {
+      const idx = JSON.parse(readFileSync(idxPath, 'utf8'));
+      if (Array.isArray(idx)) {
+        const since = Date.now() - 24 * 60 * 60 * 1000;
+        observations = {
+          total: idx.length,
+          last24h: idx.filter((e) => Date.parse(e?.createdAt) >= since).length,
+        };
+      }
+    }
+  } catch { /* best effort */ }
+
+  let researchCount = 0;
+  try {
+    const dir = join(cwd, '.cx', 'knowledge', 'external', 'research');
+    if (existsSync(dir)) {
+      researchCount = readdirSync(dir).filter((f) => f.endsWith('.md')).length;
+    }
+  } catch { /* best effort */ }
+
+  const profile = resolveActiveProfile(cwd);
+  const outcomes = readSummary(cwd) || { roles: {} };
+
+  return {
+    profile: { id: profile.id, displayName: profile.displayName ?? profile.id, custom: profile.custom === true },
+    observations,
+    research: { count: researchCount },
+    outcomes,
+  };
+}

package/lib/observation-store.mjs

@@ -58,6 +58,20 @@ function generateId() {
   return `obs-${ts}-${rand}`;
 }
 
+const MAX_EXTRAS_BYTES = 2 * 1024;
+
+function sanitizeExtras(extras) {
+  if (extras == null) return null;
+  if (typeof extras !== 'object' || Array.isArray(extras)) return null;
+  try {
+    const serialized = JSON.stringify(extras);
+    if (Buffer.byteLength(serialized, 'utf8') > MAX_EXTRAS_BYTES) return null;
+    return JSON.parse(serialized);
+  } catch {
+    return null;
+  }
+}
+
 function clamp(str, max) {
   if (!str || str.length <= max) return str || null;
   return str.slice(0, max - 1) + '\u2026';
@@ -131,6 +145,7 @@ export async function addObservation(rootDir, {
   confidence = 0.8,
   source = null,
   gitSha = null,
+  extras = null,
 } = {}) {
   const id = generateId();
   const now = new Date().toISOString();
@@ -139,6 +154,9 @@ export async function addObservation(rootDir, {
   const clampedSummary = clamp(String(summary), MAX_SUMMARY);
   const clampedContent = clamp(String(content), MAX_CONTENT);
   const clampedTags = (Array.isArray(tags) ? tags : []).slice(0, MAX_TAGS).map(String);
+  // Structured metadata: opt-in. Capped at 2 KB stringified so a misuse can't
+  // bloat the per-id JSON. Plain object only; rejects arrays and functions.
+  const clampedExtras = sanitizeExtras(extras);
 
   const record = {
     id,
@@ -151,6 +169,7 @@ export async function addObservation(rootDir, {
     confidence: Math.max(0, Math.min(1, Number(confidence) || 0.8)),
     source: source || null,
     gitSha: gitSha ? String(gitSha).slice(0, 40) : null,
+    extras: clampedExtras,
     createdAt: now,
     updatedAt: now,
   };

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));
+}