@geraldmaron/construct 1.0.4 → 1.0.6

package/lib/intake/tables/research.mjs

@@ -0,0 +1,85 @@
+/**
+ * lib/intake/tables/research.mjs — Research intake classification.
+ *
+ * Loop: question → gather → analyze → synthesize → recommend. Covers analysis,
+ * market intelligence, evaluation, advisory work. Output is a written
+ * recommendation, not a shipped product.
+ */
+
+export const INTAKE_TYPES = ['question', 'study', 'synthesis', 'report', 'experiment', 'ops', 'unknown'];
+export const STAGES = ['question', 'gather', 'analyze', 'synthesize', 'recommend'];
+
+export const UNKNOWN_TRIAGE = {
+  intakeType: 'unknown',
+  rdStage: 'unknown',
+  primaryOwner: 'researcher',
+  recommendedChain: ['researcher'],
+  recommendedAction: 'summarize',
+  risk: 'low',
+  requiresApproval: false,
+};
+
+export const CLASSIFICATION_TABLE = [
+  {
+    intakeType: 'study',
+    keywords: ['interview', 'user study', 'survey', 'focus group', 'usability test', 'diary study', 'ethnography'],
+    rdStage: 'gather',
+    primaryOwner: 'ux-researcher',
+    recommendedChain: ['ux-researcher', 'researcher'],
+    recommendedAction: 'create-experiment',
+    risk: 'low',
+    requiresApproval: false,
+  },
+  {
+    intakeType: 'experiment',
+    keywords: ['hypothesis', 'experiment', 'controlled trial', 'a/b test', 'pilot', 'falsifiable'],
+    rdStage: 'analyze',
+    primaryOwner: 'evaluator',
+    recommendedChain: ['evaluator', 'researcher', 'data-analyst'],
+    recommendedAction: 'evaluate',
+    risk: 'low',
+    requiresApproval: false,
+  },
+  {
+    intakeType: 'report',
+    keywords: ['report', 'finding', 'dashboard', 'metric', 'benchmark', 'baseline', 'comparison'],
+    rdStage: 'recommend',
+    primaryOwner: 'data-analyst',
+    recommendedChain: ['data-analyst', 'researcher', 'reviewer'],
+    recommendedAction: 'evaluate',
+    risk: 'low',
+    requiresApproval: false,
+  },
+  {
+    intakeType: 'synthesis',
+    keywords: ['synthesis', 'literature review', 'meta', 'state of the art', 'roundup', 'survey paper', 'taxonomy'],
+    rdStage: 'synthesize',
+    primaryOwner: 'researcher',
+    recommendedChain: ['researcher', 'reviewer'],
+    recommendedAction: 'research',
+    risk: 'low',
+    requiresApproval: false,
+  },
+  {
+    intakeType: 'question',
+    keywords: ['question', 'research question', 'what is', 'why does', 'how do', 'investigate', 'figure out', 'understand'],
+    rdStage: 'question',
+    primaryOwner: 'researcher',
+    recommendedChain: ['researcher'],
+    recommendedAction: 'clarify',
+    risk: 'low',
+    requiresApproval: false,
+  },
+  {
+    intakeType: 'ops',
+    keywords: ['process', 'methodology', 'template', 'protocol', 'consent form', 'data handling'],
+    rdStage: 'gather',
+    primaryOwner: 'operator',
+    recommendedChain: ['operator', 'researcher'],
+    recommendedAction: 'create-runbook',
+    risk: 'low',
+    requiresApproval: false,
+  },
+];
+
+export default { INTAKE_TYPES, STAGES, CLASSIFICATION_TABLE, UNKNOWN_TRIAGE };

package/lib/intake/tables/rnd.mjs

@@ -0,0 +1,175 @@
+/**
+ * lib/intake/tables/rnd.mjs — RND intake classification table.
+ *
+ * Extracted from lib/intake/classify.mjs as part of B2. Behavior must remain
+ * byte-identical for RND inputs; tests/intake/golden-rnd.test.mjs is the
+ * regression guard.
+ *
+ * Schema: { INTAKE_TYPES, STAGES, CLASSIFICATION_TABLE, UNKNOWN_TRIAGE }.
+ * UNKNOWN_TRIAGE handles the no-match fallback for this profile.
+ */
+
+export const INTAKE_TYPES = [
+  'user-signal',
+  'bug',
+  'requirement',
+  'research',
+  'experiment',
+  'eval-finding',
+  'architecture',
+  'incident',
+  'launch-asset',
+  'ops',
+  'security',
+  'legal-compliance',
+  'unknown',
+];
+
+export const STAGES = [
+  'signal',
+  'framing',
+  'hypothesis',
+  'research',
+  'artifact',
+  'design',
+  'implementation',
+  'evaluation',
+  'release',
+  'operations',
+  'unknown',
+];
+
+export const UNKNOWN_TRIAGE = {
+  intakeType: 'unknown',
+  rdStage: 'unknown',
+  primaryOwner: 'orchestrator',
+  recommendedChain: ['orchestrator'],
+  recommendedAction: 'summarize',
+  risk: 'low',
+  requiresApproval: false,
+};
+
+export const CLASSIFICATION_TABLE = [
+  {
+    intakeType: 'security',
+    keywords: ['security', 'secret', 'cve', 'vulnerability', 'vuln', 'exploit', 'leak', 'auth bypass', 'privilege escalation', 'sqli', 'xss', 'csrf', 'rce'],
+    rdStage: 'operations',
+    primaryOwner: 'security',
+    recommendedChain: ['security', 'engineer', 'reviewer'],
+    recommendedAction: 'diagnose',
+    risk: 'high',
+    requiresApproval: true,
+  },
+  {
+    intakeType: 'incident',
+    keywords: ['incident', 'outage', 'slo breach', 'sla breach', 'latency spike', 'availability', 'down', 'p0 ', 'p1 ', 'pagerduty', '5xx', 'oncall'],
+    rdStage: 'operations',
+    primaryOwner: 'sre',
+    recommendedChain: ['sre', 'debugger', 'platform-engineer'],
+    recommendedAction: 'create-runbook',
+    risk: 'high',
+    requiresApproval: true,
+  },
+  {
+    intakeType: 'legal-compliance',
+    keywords: ['gdpr', 'ccpa', 'hipaa', 'sox', 'soc2', 'license', 'lawsuit', 'dpa', 'data retention', 'pii', 'subpoena', 'compliance audit'],
+    rdStage: 'operations',
+    primaryOwner: 'legal-compliance',
+    recommendedChain: ['legal-compliance', 'security', 'product-manager'],
+    recommendedAction: 'clarify',
+    risk: 'high',
+    requiresApproval: true,
+  },
+  {
+    intakeType: 'architecture',
+    keywords: ['architecture', 'adr', 'rfc', 'interface', 'tradeoff', 'boundary', 'system design', 'data model', 'api contract', 'migration plan'],
+    rdStage: 'design',
+    primaryOwner: 'architect',
+    recommendedChain: ['architect', 'devil-advocate', 'engineer'],
+    recommendedAction: 'draft-rfc',
+    risk: 'medium',
+    requiresApproval: false,
+  },
+  {
+    intakeType: 'eval-finding',
+    keywords: ['eval', 'evaluation', 'hallucination', 'judge', 'trace', 'score regression', 'recall@', 'precision@', 'mrr', 'ndcg', 'failure case', 'rubric'],
+    rdStage: 'evaluation',
+    primaryOwner: 'evaluator',
+    recommendedChain: ['evaluator', 'ai-engineer', 'trace-reviewer'],
+    recommendedAction: 'evaluate',
+    risk: 'medium',
+    requiresApproval: false,
+  },
+  {
+    intakeType: 'bug',
+    keywords: ['bug', 'broken', 'error', 'stack trace', 'regression', 'crash', 'exception', 'fails', 'failing', 'throws', 'not working', 'reproduce', 'repro:'],
+    rdStage: 'implementation',
+    primaryOwner: 'debugger',
+    recommendedChain: ['debugger', 'engineer', 'qa', 'reviewer'],
+    recommendedAction: 'diagnose',
+    risk: 'medium',
+    requiresApproval: false,
+  },
+  {
+    intakeType: 'experiment',
+    keywords: ['hypothesis', 'experiment', 'spike', 'prototype', 'falsifiable', 'research question', 'a/b test', 'pilot'],
+    rdStage: 'hypothesis',
+    primaryOwner: 'rd-lead',
+    recommendedChain: ['rd-lead', 'researcher', 'evaluator'],
+    recommendedAction: 'create-experiment',
+    risk: 'low',
+    requiresApproval: false,
+  },
+  {
+    intakeType: 'launch-asset',
+    keywords: ['release', 'changelog', 'version bump', 'ship', 'launch', 'rollout', 'cut a release', 'rc1', 'rc2', 'release candidate'],
+    rdStage: 'release',
+    primaryOwner: 'release-manager',
+    recommendedChain: ['release-manager', 'qa', 'docs-keeper'],
+    recommendedAction: 'release-review',
+    risk: 'medium',
+    requiresApproval: false,
+  },
+  {
+    intakeType: 'research',
+    keywords: ['competitor', 'market', 'pricing', 'positioning', 'industry', 'state of the art', 'literature', 'benchmark study', 'desk research'],
+    rdStage: 'research',
+    primaryOwner: 'business-strategist',
+    recommendedChain: ['business-strategist', 'researcher', 'product-manager'],
+    recommendedAction: 'research',
+    risk: 'low',
+    requiresApproval: false,
+  },
+  {
+    intakeType: 'user-signal',
+    keywords: ['customer', 'feedback', 'pain point', 'user says', 'user feedback', 'support ticket', 'churn', 'nps', 'usability', 'frustrated'],
+    rdStage: 'signal',
+    primaryOwner: 'product-manager',
+    recommendedChain: ['product-manager', 'ux-researcher', 'researcher'],
+    recommendedAction: 'clarify',
+    risk: 'low',
+    requiresApproval: false,
+  },
+  {
+    intakeType: 'requirement',
+    keywords: ['acceptance criteria', 'requirement', 'must have', 'should have', 'feature request', 'prd', 'use case', 'success metric'],
+    rdStage: 'framing',
+    primaryOwner: 'product-manager',
+    recommendedChain: ['product-manager', 'architect', 'engineer'],
+    recommendedAction: 'draft-prd',
+    risk: 'low',
+    requiresApproval: false,
+  },
+  {
+    intakeType: 'ops',
+    keywords: ['runbook', 'cron', 'scheduled job', 'maintenance', 'backup', 'restore', 'capacity plan', 'cost optimization', 'dependency upgrade'],
+    rdStage: 'operations',
+    primaryOwner: 'operations',
+    recommendedChain: ['operations', 'sre', 'engineer'],
+    recommendedAction: 'create-runbook',
+    risk: 'low',
+    requiresApproval: false,
+  },
+];
+
+export default { INTAKE_TYPES, STAGES, CLASSIFICATION_TABLE, UNKNOWN_TRIAGE };

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/knowledge/research-store.mjs

@@ -0,0 +1,109 @@
+/**
+ * lib/knowledge/research-store.mjs — Persist research findings into the knowledge base.
+ *
+ * Wraps the existing document-ingest pipeline so research output written via
+ * `construct knowledge add --source=research` lands in
+ * `.cx/knowledge/external/research/<slug>.md` with research-specific frontmatter
+ * (topic, confidence, sources, expiresAt, profile). The file is then synced into
+ * the SQL/vector index via the standard `syncFileStateToSql` path.
+ *
+ * Schema (frontmatter):
+ *   kind: research-finding
+ *   topic: string
+ *   confidence: confirmed | inferred | weak
+ *   sources: [{ url, accessedAt, span? }]
+ *   expiresAt: ISO date (default +90d)
+ *   profile: <profile-id>
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { syncFileStateToSql } from '../storage/sync.mjs';
+import { resolveActiveProfile } from '../profiles/loader.mjs';
+
+const ROOT = '.cx/knowledge/external/research';
+const MAX_BYTES = 50 * 1024;
+const DEFAULT_TTL_DAYS = 90;
+
+const VALID_CONFIDENCE = new Set(['confirmed', 'inferred', 'weak']);
+
+/**
+ * @param {object} args
+ * @param {string} args.cwd - project root
+ * @param {string} args.slug - filename slug (lowercase, hyphenated)
+ * @param {string} args.topic - human-readable topic line
+ * @param {string} args.body - the FINDINGS / INFERENCES / GAPS / RECOMMENDATION block
+ * @param {string} [args.confidence] - confirmed | inferred | weak
+ * @param {Array<{url:string,accessedAt?:string,span?:string}>} [args.sources]
+ * @param {number} [args.ttlDays] - override default expiry
+ * @returns {Promise<{path:string,bytes:number}>}
+ */
+export async function addResearchFinding({
+  cwd,
+  slug,
+  topic,
+  body,
+  confidence = 'inferred',
+  sources = [],
+  ttlDays = DEFAULT_TTL_DAYS,
+}) {
+  if (!cwd) throw new Error('addResearchFinding: cwd is required');
+  if (!slug || !/^[a-z0-9][a-z0-9-]{0,60}$/.test(slug)) {
+    throw new Error('addResearchFinding: slug must be lowercase, hyphenated, max 60 chars');
+  }
+  if (!topic || typeof topic !== 'string') {
+    throw new Error('addResearchFinding: topic is required');
+  }
+  if (!body || typeof body !== 'string') {
+    throw new Error('addResearchFinding: body is required');
+  }
+  if (!VALID_CONFIDENCE.has(confidence)) {
+    throw new Error(`addResearchFinding: confidence must be one of ${Array.from(VALID_CONFIDENCE).join(', ')}`);
+  }
+  if (confidence === 'confirmed' && (!Array.isArray(sources) || sources.length === 0)) {
+    throw new Error('addResearchFinding: confidence=confirmed requires at least one source');
+  }
+
+  const profile = resolveActiveProfile(cwd);
+  const now = new Date();
+  const expiresAt = new Date(now.getTime() + ttlDays * 24 * 60 * 60 * 1000).toISOString();
+
+  const outDir = join(cwd, ROOT);
+  mkdirSync(outDir, { recursive: true });
+  const outPath = join(outDir, `${slug}.md`);
+
+  const fmSources = (Array.isArray(sources) ? sources : [])
+    .filter((s) => s && typeof s.url === 'string')
+    .map((s) => ({
+      url: s.url,
+      accessedAt: s.accessedAt || now.toISOString(),
+      ...(s.span ? { span: String(s.span).slice(0, 200) } : {}),
+    }));
+
+  const frontmatter = [
+    '---',
+    'kind: research-finding',
+    `topic: ${JSON.stringify(topic)}`,
+    `confidence: ${confidence}`,
+    `sources: ${JSON.stringify(fmSources)}`,
+    `created: ${now.toISOString()}`,
+    `expiresAt: ${expiresAt}`,
+    `profile: ${profile?.id ?? 'rnd'}`,
+    '---',
+    '',
+  ].join('\n');
+
+  const fullText = frontmatter + body.trim() + '\n';
+  if (Buffer.byteLength(fullText, 'utf8') > MAX_BYTES) {
+    throw new Error(`addResearchFinding: file exceeds ${MAX_BYTES} bytes`);
+  }
+
+  writeFileSync(outPath, fullText);
+
+  // Best-effort sync into SQL/vector index. The file is the source of truth;
+  // index lag never blocks the operator.
+  try {
+    await syncFileStateToSql(cwd, { project: profile?.id ?? 'rnd' });
+  } catch { /* best effort */ }
+
+  return { path: outPath, bytes: Buffer.byteLength(fullText, 'utf8') };
+}