@geraldmaron/construct 1.0.5 → 1.0.6

package/lib/knowledge/graph.mjs

@@ -0,0 +1,213 @@
+/**
+ * lib/knowledge/graph.mjs — GraphRAG-style entity index + global query.
+ *
+ * Phase C9 foundations:
+ *   - buildGraph(rootDir): derive nodes + edges from `.cx/observations/entities.json`.
+ *   - detectCommunities(graph): pure-JS label propagation. Deterministic
+ *     (sorted neighbor scan, lowest-id tiebreak). O(V+E) per iteration.
+ *   - summarizeCommunity(community, entities): extractive summary over the
+ *     member entities, ranked by degree centrality. Requires no LLM call,
+ *     so the primitive works in solo mode without a provider configured.
+ *   - askGlobal({ query, rootDir }): rank communities by overlap with the
+ *     query terms + their members' search text, return the top communities
+ *     with member entities and the question they best answer.
+ *
+ * Full Leiden (modularity optimization + refinement) would need an external
+ * graph library and is blocked by ADR-0001 (zero-npm-core). Label propagation
+ * is the deterministic alternative. Produces useful coarse communities on
+ * the small graphs Construct sessions accumulate (typically <500 entities).
+ * Swap implementations later by replacing `detectCommunities` only.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { rankByBm25 } from '../storage/embeddings.mjs';
+
+const OBS_DIR = '.cx/observations';
+const ENTITIES_FILE = 'entities.json';
+
+const MAX_LP_ITERATIONS = 30;
+const MAX_COMMUNITY_TOP_TERMS = 8;
+const MIN_COMMUNITY_SIZE = 2;
+
+function readEntities(rootDir) {
+  const p = path.join(rootDir, OBS_DIR, ENTITIES_FILE);
+  if (!existsSync(p)) return [];
+  try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return []; }
+}
+
+/**
+ * Build an undirected graph from the entity store. Nodes are entity names;
+ * edges come from `relatedEntities[]`. Returns:
+ *   { nodes: Map<name, entity>, adj: Map<name, Set<name>> }
+ */
+export function buildGraph(rootDir) {
+  const entities = readEntities(rootDir);
+  const nodes = new Map();
+  const adj = new Map();
+  for (const e of entities) {
+    if (!e?.name) continue;
+    nodes.set(e.name, e);
+    if (!adj.has(e.name)) adj.set(e.name, new Set());
+  }
+  for (const e of entities) {
+    if (!e?.name) continue;
+    for (const other of e.relatedEntities || []) {
+      if (!nodes.has(other)) continue;
+      adj.get(e.name).add(other);
+      adj.get(other).add(e.name);
+    }
+  }
+  return { nodes, adj };
+}
+
+/**
+ * Run synchronous label propagation. Each node starts with its own label;
+ * iteratively adopt the most frequent label among neighbors, with a sorted
+ * neighbor scan and lowest-id tiebreak so the result is deterministic.
+ *
+ * Returns: Map<name, communityId> plus a stable grouping.
+ */
+export function detectCommunities(graph) {
+  const labels = new Map();
+  const sortedNodes = [...graph.nodes.keys()].sort();
+  for (const n of sortedNodes) labels.set(n, n);
+
+  for (let iter = 0; iter < MAX_LP_ITERATIONS; iter++) {
+    let changed = false;
+    for (const node of sortedNodes) {
+      const neighbors = [...(graph.adj.get(node) || [])].sort();
+      if (neighbors.length === 0) continue;
+
+      const counts = new Map();
+      for (const nb of neighbors) {
+        const lbl = labels.get(nb);
+        counts.set(lbl, (counts.get(lbl) || 0) + 1);
+      }
+
+      // highest-count label, lowest-id tiebreak
+      let bestLabel = labels.get(node);
+      let bestCount = -1;
+      const sortedLabels = [...counts.entries()].sort((a, b) => {
+        if (b[1] !== a[1]) return b[1] - a[1];
+        return a[0] < b[0] ? -1 : 1;
+      });
+      if (sortedLabels.length > 0) {
+        [bestLabel, bestCount] = sortedLabels[0];
+      }
+
+      if (bestCount > 0 && bestLabel !== labels.get(node)) {
+        labels.set(node, bestLabel);
+        changed = true;
+      }
+    }
+    if (!changed) break;
+  }
+
+  const communities = new Map();
+  for (const [node, label] of labels) {
+    if (!communities.has(label)) communities.set(label, []);
+    communities.get(label).push(node);
+  }
+  // Stable order: by size desc, then alphabetical on canonical label
+  const grouped = [...communities.entries()]
+    .map(([id, members]) => ({ id, members: members.sort() }))
+    .sort((a, b) => {
+      if (b.members.length !== a.members.length) return b.members.length - a.members.length;
+      return a.id < b.id ? -1 : 1;
+    });
+  return { labels, communities: grouped };
+}
+
+/**
+ * Extractive community summary. Picks the top-N members by intra-community
+ * degree (the "central" nodes of the cluster) and harvests their summaries
+ * into a short text block. Deterministic and dependency-free.
+ */
+export function summarizeCommunity(group, graph) {
+  if (!group?.members?.length) return { id: group?.id, size: 0, topMembers: [], summary: '' };
+  const memberSet = new Set(group.members);
+  const scored = group.members.map((name) => {
+    const neighbors = graph.adj.get(name) || new Set();
+    let degree = 0;
+    for (const nb of neighbors) if (memberSet.has(nb)) degree++;
+    return { name, degree };
+  }).sort((a, b) => {
+    if (b.degree !== a.degree) return b.degree - a.degree;
+    return a.name < b.name ? -1 : 1;
+  });
+
+  const topMembers = scored.slice(0, MAX_COMMUNITY_TOP_TERMS);
+  const lines = [];
+  for (const { name } of topMembers) {
+    const entity = graph.nodes.get(name);
+    if (!entity) continue;
+    const summary = (entity.summary || '').trim();
+    if (summary) lines.push(`- ${entity.name}: ${summary}`);
+    else lines.push(`- ${entity.name}`);
+  }
+  return {
+    id: group.id,
+    size: group.members.length,
+    topMembers: topMembers.map((m) => m.name),
+    summary: lines.join('\n'),
+  };
+}
+
+/**
+ * Global query over the entity graph. Builds the graph, detects communities,
+ * scores each community by BM25 over its concatenated member summaries, and
+ * returns the top communities with members.
+ *
+ * Intentionally returns structured data instead of a synthesized prose
+ * answer: the LM-based response synthesis is the next layer up and belongs
+ * in the persona prompt, not in this retrieval primitive. Solo mode can
+ * consume the raw result without calling an external model.
+ *
+ * @param {object} args
+ * @param {string} args.query  - natural-language question
+ * @param {string} args.rootDir - project root containing `.cx/observations/`
+ * @param {number} [args.topK=5] - max communities to return
+ * @param {number} [args.minSize=MIN_COMMUNITY_SIZE] - skip singleton communities
+ * @returns {{ query, communities: Array<{ id, size, topMembers, summary, score }>, totalEntities, totalCommunities }}
+ */
+export function askGlobal({ query, rootDir, topK = 5, minSize = MIN_COMMUNITY_SIZE } = {}) {
+  if (!query || typeof query !== 'string') {
+    return { query: query || '', communities: [], totalEntities: 0, totalCommunities: 0 };
+  }
+  const graph = buildGraph(rootDir);
+  if (graph.nodes.size === 0) {
+    return { query, communities: [], totalEntities: 0, totalCommunities: 0 };
+  }
+
+  const { communities } = detectCommunities(graph);
+  const eligible = communities.filter((g) => g.members.length >= minSize);
+  if (eligible.length === 0) {
+    return {
+      query,
+      communities: [],
+      totalEntities: graph.nodes.size,
+      totalCommunities: communities.length,
+    };
+  }
+
+  const summaries = eligible.map((group) => summarizeCommunity(group, graph));
+  const docs = summaries.map((s, i) => ({
+    id: String(i),
+    text: `${s.topMembers.join(' ')}\n${s.summary}`,
+  }));
+  const ranked = rankByBm25(docs, query, { limit: topK });
+
+  const out = [];
+  for (const r of ranked) {
+    const summary = summaries[Number(r.id)];
+    if (!summary) continue;
+    out.push({ ...summary, score: r.score });
+  }
+
+  return {
+    query,
+    communities: out,
+    totalEntities: graph.nodes.size,
+    totalCommunities: communities.length,
+  };
+}

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