@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/embed/config.mjs

@@ -0,0 +1,355 @@
+/**
+ * lib/embed/config.mjs — embed mode configuration schema and loader.
+ *
+ * Reads embed.yaml from ~/.construct/embed.yaml (or a supplied path) and validates
+ * the file against the expected schema. Returns a parsed, normalized config object.
+ *
+ * Schema:
+ *
+ *   sources:
+ *     - provider: github
+ *       repo: owner/name           # single repo
+ *       repos: [owner/a, owner/b]  # OR list of repos
+ *       refs: [prs, issues, commits]
+ *       branch: main               # for commits ref
+ *       limit: 25
+ *
+ *     - provider: slack
+ *       channel: C12345678         # single channel ID or name
+ *       channels: [general, eng]   # OR list
+ *       refs: [messages]
+ *       oldest: 86400              # seconds of history (default 24h)
+ *
+ *     - provider: linear
+ *       team: ENG                  # team key (optional)
+ *       project: My Project        # project name filter (optional)
+ *       refs: [issues, cycles]
+ *       states: [Todo, In Progress]
+ *
+ *     - provider: jira
+ *       project: PROJ              # project key
+ *       projects: [PROJ, INFRA]    # OR list
+ *       refs: [issues, sprints]
+ *       jql: "project = PROJ AND sprint in openSprints()"  # override JQL
+ *
+ *   outputs:
+ *     - type: markdown            # write snapshot to a file
+ *       path: .cx/snapshot.md
+ *     - type: slack               # post to a Slack channel
+ *       provider: slack
+ *       channel: C12345
+ *     - type: dashboard           # push to the Construct dashboard
+ *
+ *   approval:
+ *     require:                    # action types that need approval before dispatch
+ *       - issue.create
+ *       - pr.merge
+ *     timeout_ms: 3600000         # how long to wait before auto-expiring (default: 1h)
+ *     fallback: reject            # reject | proceed (default: reject)
+ *
+ *   snapshot:
+ *     intervalMs: 300000          # how often to regenerate full snapshot (default: 5m)
+ *     maxItems: 100               # max items per source in snapshot
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const DEFAULTS = {
+  snapshot: { intervalMs: 300_000, maxItems: 100 },
+  approval: { require: [], timeout_ms: 3_600_000, fallback: 'reject' },
+  roles: { primary: null, secondary: null },
+};
+
+/**
+ * Target types for embed output routing.
+ *
+ * targets:
+ *   - type: repo
+ *     ref: github.com/org/project-x          # remote — interact via provider
+ *   - type: repo
+ *     path: /Users/user/Github/local-project  # local filesystem
+ *   - type: repo
+ *     ref: github.com/org/project-y
+ *     path: /Users/user/Github/project-y      # both — prefer local, fall back to remote
+ *   - type: workspace                         # always present as fallback
+ *     path: ~/.construct/workspace
+ *
+ * roles:
+ *   primary: product-manager    # shapes embed analysis lens
+ *   secondary: architect        # persistent background concern
+ */
+export const DEFAULT_WORKSPACE_PATH = path.join(os.homedir(), '.construct', 'workspace');
+
+export const WORKSPACE_DOCS_LANES = ['adrs', 'prds', 'memos', 'notes', 'intake'];
+
+export const OPERATING_PROFILE_VERSION = 'embed-operating-profile/v1';
+
+export const DEFAULT_OPERATING_PROFILE = {
+  schemaVersion: OPERATING_PROFILE_VERSION,
+  mode: 'embed',
+  mission: 'Maintain situational awareness across connected project systems and turn weak signals into actionable plans, drafts, risks, and approval-queued work.',
+  strategy: {
+    defaultPosture: 'assistive',
+    autonomy: 'read-first',
+    writePolicy: 'approval-required-for-high-risk',
+    dependencyPolicy: 'zero-deps',
+    precedence: 'approval rules override operating profile preferences',
+  },
+  focalResources: [
+    { type: 'plan', path: 'plan.md', purpose: 'active implementation plan' },
+    { type: 'architecture', path: 'docs/concepts/architecture.md', purpose: 'system architecture and operating model' },
+    { type: 'knowledge', path: '.cx/knowledge', purpose: 'typed project knowledge and ingested evidence' },
+    { type: 'runtime', path: '.cx/roadmap.md', purpose: 'generated roadmap output' },
+  ],
+  approach: [
+    'read configured sources',
+    'compare observed activity with mission and focal resources',
+    'identify gaps, risks, stale decisions, and missing artifacts',
+    'draft roadmaps, PRDs, RFCs, ADRs, memos, status updates, summaries, and wireframes',
+    'route high-risk writes through the approval queue',
+  ],
+  authority: {
+    read: 'autonomous',
+    summarize: 'autonomous',
+    draftArtifacts: 'autonomous',
+    createIssues: 'approval-queued',
+    updateIssues: 'approval-queued',
+    publishDocs: 'approval-queued',
+    externalPost: 'approval-queued',
+    repoWrites: 'approval-queued',
+  },
+  responsibilities: {
+    gapAnalysis: true,
+    issueLifecycle: { create: 'approval-queued', update: 'approval-queued', dedupe: 'recommend' },
+    artifacts: {
+      roadmaps: 'generate',
+      prds: 'draft',
+      rfcs: 'draft',
+      adrs: 'draft',
+      memos: 'draft',
+      statusUpdates: 'generate',
+      summaries: 'generate',
+      wireframes: 'draft',
+      risks: 'generate',
+    },
+  },
+  riskModel: {
+    detect: ['blocked work', 'missing owner', 'stale cadence', 'source errors', 'missing focal resource', 'unapproved high-risk action'],
+    dashboardStatus: { ok: 'no known gaps', attention: 'gaps or source errors exist', blocked: 'required focal resource or approval path missing' },
+  },
+};
+
+export const EMPTY_CONFIG = {
+  sources: [],
+  outputs: [],
+  targets: [{ type: 'workspace', path: DEFAULT_WORKSPACE_PATH }],
+  roles: { ...DEFAULTS.roles },
+  snapshot: { ...DEFAULTS.snapshot },
+  approval: { ...DEFAULTS.approval },
+  operatingProfile: DEFAULT_OPERATING_PROFILE,
+};
+
+function deepMerge(base, override) {
+  if (!override || typeof override !== 'object' || Array.isArray(override)) return base;
+  const merged = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    if (Array.isArray(value)) merged[key] = value;
+    else if (value && typeof value === 'object' && base[key] && typeof base[key] === 'object' && !Array.isArray(base[key])) {
+      merged[key] = deepMerge(base[key], value);
+    } else {
+      merged[key] = value;
+    }
+  }
+  return merged;
+}
+
+export function loadEmbedConfig(configPath) {
+  if (!fs.existsSync(configPath)) {
+    throw new Error(`Embed config not found: ${configPath}`);
+  }
+
+  const raw = fs.readFileSync(configPath, 'utf8');
+  // Minimal YAML subset parser: handles the flat-ish schema we use.
+  // Full YAML parsing requires a dep; we use a hand-rolled parser for zero-dep core.
+  const parsed = parseEmbedYaml(raw);
+  return normalize(parsed);
+}
+
+export function normalize(raw) {
+  const config = {
+    sources: [],
+    outputs: [],
+    targets: [],
+    roles: { ...DEFAULTS.roles, ...(raw.roles ?? {}) },
+    snapshot: { ...DEFAULTS.snapshot, ...(raw.snapshot ?? {}) },
+    approval: { ...DEFAULTS.approval, ...(raw.approval ?? {}) },
+    operatingProfile: deepMerge(DEFAULT_OPERATING_PROFILE, raw.operatingProfile ?? {}),
+  };
+
+  for (const src of raw.sources ?? []) {
+    if (!src.provider) throw new Error('Each source must have a "provider" field');
+    config.sources.push({
+      ...src,
+      provider: src.provider,
+      refs: Array.isArray(src.refs) ? src.refs : [src.refs ?? 'status'],
+      intervalMs: src.intervalMs ?? 60_000,
+    });
+  }
+
+  for (const out of raw.outputs ?? []) {
+    if (!out.type) throw new Error('Each output must have a "type" field');
+    config.outputs.push({ ...out });
+  }
+
+  // Targets: explicit list, always has workspace fallback
+  for (const t of raw.targets ?? []) {
+    if (!t.type) throw new Error('Each target must have a "type" field');
+    config.targets.push({ ...t });
+  }
+  // Ensure workspace fallback is always present
+  if (!config.targets.some((t) => t.type === 'workspace')) {
+    config.targets.push({ type: 'workspace', path: DEFAULT_WORKSPACE_PATH });
+  }
+
+  return config;
+}
+
+/**
+ * Hand-rolled parser for the embed YAML schema.
+ * Supports: top-level keys, nested objects, lists of objects, scalar values.
+ * Not a general YAML parser — only handles what embed.yaml uses.
+ */
+export function parseEmbedYaml(text) {
+  const lines = text.split('\n');
+  const root = {};
+  let i = 0;
+
+  function peek() { return lines[i]; }
+  function advance() { return lines[i++]; }
+  function indent(line) { return line.match(/^(\s*)/)[1].length; }
+  function isComment(line) { return line.trimStart().startsWith('#'); }
+  function isEmpty(line) { return line.trim() === ''; }
+
+  function parseValue(val) {
+    const v = val.trim();
+    if (v === 'true') return true;
+    if (v === 'false') return false;
+    if (v === 'null' || v === '~' || v === '') return null;
+    if (v === '[]') return [];
+    if (v === '{}') return {};
+    // Inline flow list: [a, b, c]
+    if (v.startsWith('[') && v.endsWith(']')) {
+      const inner = v.slice(1, -1).trim();
+      if (inner === '') return [];
+      return inner.split(',').map((s) => parseValue(s.trim()));
+    }
+    const n = Number(v);
+    if (!Number.isNaN(n) && v !== '') return n;
+    // Strip quotes
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+      return v.slice(1, -1);
+    }
+    return v;
+  }
+
+  function parseBlock(baseIndent) {
+    const obj = {};
+    while (i < lines.length) {
+      const line = peek();
+      if (isEmpty(line) || isComment(line)) { advance(); continue; }
+      const lineIndent = indent(line);
+      if (lineIndent < baseIndent) break;
+      if (lineIndent > baseIndent) { advance(); continue; } // skip malformed
+
+      advance();
+      const trimmed = line.trim();
+
+      // List item
+      if (trimmed.startsWith('- ')) {
+        // Not expected at block level — handled by parseList
+        break;
+      }
+
+      const colonIdx = trimmed.indexOf(':');
+      if (colonIdx === -1) continue;
+      const key = trimmed.slice(0, colonIdx).trim();
+      const rest = trimmed.slice(colonIdx + 1);
+
+      if (rest.trim() === '') {
+        // Next lines are either a list or nested object
+        const nextLine = lines[i];
+        if (!nextLine) { obj[key] = null; continue; }
+        const nextTrimmed = nextLine.trimStart();
+        if (nextTrimmed.startsWith('- ')) {
+          obj[key] = parseList(lineIndent + 2);
+        } else {
+          obj[key] = parseBlock(lineIndent + 2);
+        }
+      } else {
+        obj[key] = parseValue(rest);
+      }
+    }
+    return obj;
+  }
+
+  function parseList(baseIndent) {
+    const arr = [];
+    while (i < lines.length) {
+      const line = peek();
+      if (isEmpty(line) || isComment(line)) { advance(); continue; }
+      const lineIndent = indent(line);
+      if (lineIndent < baseIndent) break;
+
+      const trimmed = line.trim();
+      if (!trimmed.startsWith('- ')) break;
+      advance();
+
+      const rest = trimmed.slice(2).trim();
+      if (rest === '') {
+        // Multi-line list item object
+        arr.push(parseBlock(lineIndent + 2));
+      } else if (rest.includes(':')) {
+        // Inline object in list: "- provider: github"
+        const item = {};
+        const colonIdx = rest.indexOf(':');
+        const key = rest.slice(0, colonIdx).trim();
+        const val = rest.slice(colonIdx + 1).trim();
+        item[key] = val === '' ? parseBlock(lineIndent + 2) : parseValue(val);
+        // Consume continuation keys at same level
+        while (i < lines.length) {
+          const next = lines[i];
+          if (isEmpty(next) || isComment(next)) { i++; continue; }
+          if (indent(next) <= lineIndent) break;
+          i++;
+          const nt = next.trim();
+          const ci = nt.indexOf(':');
+          if (ci === -1) continue;
+          const nk = nt.slice(0, ci).trim();
+          const nv = nt.slice(ci + 1).trim();
+          if (nv === '') {
+            const nextNext = lines[i];
+            if (nextNext && nextNext.trimStart().startsWith('- ')) {
+              item[nk] = parseList(indent(next) + 2);
+            } else {
+              item[nk] = parseBlock(indent(next) + 2);
+            }
+          } else {
+            item[nk] = parseValue(nv);
+          }
+        }
+        arr.push(item);
+      } else {
+        arr.push(parseValue(rest));
+      }
+    }
+    return arr;
+  }
+
+  return parseBlock(0);
+}
+
+export function defaultEmbedConfigPath() {
+  return path.join(os.homedir(), '.construct', 'embed.yaml');
+}

package/lib/embed/conflict-detection.mjs

@@ -0,0 +1,264 @@
+/**
+ * lib/embed/conflict-detection.mjs — Detect overlaps and contradictions
+ * between new intake signals and existing PRDs, ADRs, RFCs.
+ *
+ * Uses semantic similarity (via lib/embed/semantic.mjs) to compare new
+ * signals against the corpus of existing artifacts. Flags potential
+ * conflicts when similarity exceeds configurable thresholds.
+ *
+ * Two detection modes:
+ *   1. Overlap detection — new signal addresses same topic as existing artifact
+ *   2. Contradiction detection — new signal contradicts a documented decision
+ *
+ * Storage:
+ *   ~/.cx/product-intel/artifact-index.json — cached artifact embeddings
+ *   Rebuilt on first use or when artifact file count changes.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { embed, cosineSimilarity, extractTextFromPacket } from './semantic.mjs';
+import { listArtifacts } from './artifact.mjs';
+
+const INDEX_DIR = join(homedir(), '.cx', 'product-intel');
+const INDEX_FILE = join(INDEX_DIR, 'artifact-index.json');
+
+const OVERLAP_THRESHOLD = 0.6;
+const CONTRADICTION_THRESHOLD = 0.7;
+const STALE_INDEX_HOURS = 24;
+
+/**
+ * Ensure index directory exists.
+ */
+function ensureDir() {
+  if (!existsSync(INDEX_DIR)) mkdirSync(INDEX_DIR, { recursive: true });
+}
+
+let _artifactIndex = null;
+
+/**
+ * Build or load the artifact index (cached by count + mtime).
+ * Index maps artifact path → { text, embedding, type, title }.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.rootDir] - Project root
+ * @param {boolean} [opts.forceRebuild] - Force rebuild even if cache is fresh
+ * @returns {Promise<Array<{ path: string, type: string, title: string, text: string, embedding: Float32Array|null }>>}
+ */
+export async function buildArtifactIndex({ rootDir, forceRebuild = false } = {}) {
+  const root = rootDir || process.cwd();
+  ensureDir();
+
+  const artifacts = listArtifacts({ rootDir: root });
+  const cacheKey = artifacts.map(a => `${a.relativePath}:${statSync(a.path).mtimeMs}`).join('|');
+  const cacheHash = cacheKey.length;
+
+  // Check if cached index is fresh
+  if (!forceRebuild && existsSync(INDEX_FILE)) {
+    try {
+      const cached = JSON.parse(readFileSync(INDEX_FILE, 'utf8'));
+      if (cached.cacheHash === cacheHash && cached.index?.length === artifacts.length) {
+        const age = Date.now() - new Date(cached.builtAt).getTime();
+        if (age < STALE_INDEX_HOURS * 60 * 60 * 1000) {
+          _artifactIndex = cached.index;
+          return _artifactIndex;
+        }
+      }
+    } catch { /* rebuild */ }
+  }
+
+  // Build index — read artifact files, extract text, generate embeddings
+  const index = [];
+  for (const artifact of artifacts) {
+    try {
+      const content = readFileSync(artifact.path, 'utf8');
+      const text = extractArtifactText(content, artifact);
+      const vector = await embed(text);
+      index.push({
+        path: artifact.relativePath,
+        type: artifact.type,
+        title: artifact.title,
+        status: artifact.status,
+        text: text.slice(0, 2000),
+        embedding: vector ? Array.from(vector) : null,
+      });
+    } catch {
+      // skip unreadable artifacts
+    }
+  }
+
+  _artifactIndex = index;
+
+  // Persist index (without large embeddings if too many)
+  const persistent = index.map(a => ({
+    ...a,
+    embedding: a.embedding ? Array.from(a.embedding) : null,
+  }));
+
+  writeFileSync(INDEX_FILE, JSON.stringify({
+    cacheHash,
+    builtAt: new Date().toISOString(),
+    artifactCount: artifacts.length,
+    index: persistent,
+  }, null, 2) + '\n');
+
+  return index;
+}
+
+/**
+ * Extract searchable text from an artifact file.
+ *
+ * @param {string} content - Raw markdown content
+ * @param {object} artifact - Artifact metadata
+ * @returns {string} Cleaned text for embedding
+ */
+function extractArtifactText(content, artifact) {
+  // Strip frontmatter
+  const body = content.replace(/^---[\s\S]*?---\n*/, '');
+
+  // Extract key sections based on type
+  const title = artifact.title || '';
+  const type = artifact.type || '';
+
+  const sections = [];
+
+  if (type === 'adr') {
+    const context = body.match(/## Context\s*\n([\s\S]*?)(?=^## )/m)?.[1] || '';
+    const decision = body.match(/## Decision\s*\n([\s\S]*?)(?=^## )/m)?.[1] || '';
+    sections.push(title, context, decision);
+  } else if (type === 'prd') {
+    const problem = body.match(/## Problem\s*\n([\s\S]*?)(?=^## )/m)?.[1] || '';
+    const goals = body.match(/## Goals\s*\n([\s\S]*?)(?=^## )/m)?.[1] || '';
+    sections.push(title, problem, goals);
+  } else if (type === 'rfc') {
+    const summary = body.match(/## Summary\s*\n([\s\S]*?)(?=^## )/m)?.[1] || '';
+    const motivation = body.match(/## Motivation\s*\n([\s\S]*?)(?=^## )/m)?.[1] || '';
+    sections.push(title, summary, motivation);
+  } else {
+    // Generic — use first 2000 chars
+    sections.push(title, body.slice(0, 2000));
+  }
+
+  return sections.filter(Boolean).join('\n').slice(0, 3000);
+}
+
+/**
+ * Check a new intake signal for potential conflicts with existing artifacts.
+ *
+ * @param {object} packet - Intake packet with triage, excerpt
+ * @param {object} [opts]
+ * @param {string} [opts.rootDir]
+ * @param {number} [opts.overlapThreshold=0.6]
+ * @param {number} [opts.contradictionThreshold=0.7]
+ * @returns {Promise<Array<{ type: 'overlap'|'contradiction', severity: string, artifact: string, similarity: number, summary: string }>>}
+ */
+export async function detectConflicts(packet, { rootDir, overlapThreshold = OVERLAP_THRESHOLD, contradictionThreshold = CONTRADICTION_THRESHOLD } = {}) {
+  const text = extractTextFromPacket(packet);
+  if (!text) return [];
+
+  const signalVec = await embed(text);
+  if (!signalVec) return [];
+
+  const index = await buildArtifactIndex({ rootDir });
+  const conflicts = [];
+
+  for (const entry of index) {
+    if (!entry.embedding) continue;
+    const entryVec = new Float32Array(entry.embedding);
+    const sim = cosineSimilarity(signalVec, entryVec);
+
+    if (sim >= overlapThreshold) {
+      // Determine if this is overlap or potential contradiction
+      const isAdr = entry.type === 'adr';
+      const isContradictory = isAdr && sim >= contradictionThreshold;
+
+      conflicts.push({
+        type: isContradictory ? 'contradiction' : 'overlap',
+        severity: sim >= 0.8 ? 'high' : sim >= 0.7 ? 'medium' : 'low',
+        artifact: entry.path,
+        artifactType: entry.type,
+        title: entry.title,
+        status: entry.status,
+        similarity: Number(sim.toFixed(3)),
+        summary: isContradictory
+          ? `Potential contradiction with ${entry.type.toUpperCase()}-${entry.title} (similarity: ${sim.toFixed(2)})`
+          : `Overlaps with ${entry.type.toUpperCase()}-${entry.title} (similarity: ${sim.toFixed(2)})`,
+      });
+    }
+  }
+
+  return conflicts.sort((a, b) => b.similarity - a.similarity);
+}
+
+/**
+ * Scan all pending intake items for inter-item conflicts
+ * (two items addressing same topic from different angles).
+ *
+ * @param {Array<object>} pendingPackets
+ * @param {object} [opts]
+ * @param {number} [opts.threshold=0.7]
+ * @returns {Promise<Array<{ itemA: string, itemB: string, similarity: number, summary: string }>>}
+ */
+export async function detectInterItemConflicts(pendingPackets, { threshold = 0.7 } = {}) {
+  if (pendingPackets.length < 2) return [];
+
+  const items = [];
+  for (const packet of pendingPackets) {
+    const text = extractTextFromPacket(packet);
+    if (!text) continue;
+    const vector = await embed(text);
+    if (vector) {
+      items.push({ id: packet.id, text, embedding: vector });
+    }
+  }
+
+  const conflicts = [];
+  for (let i = 1; i < items.length; i++) {
+    for (let j = 0; j < i; j++) {
+      const sim = cosineSimilarity(items[i].embedding, items[j].embedding);
+      if (sim >= threshold) {
+        conflicts.push({
+          itemA: items[i].id,
+          itemB: items[j].id,
+          similarity: Number(sim.toFixed(3)),
+          summary: `Intake items conflict: ${items[i].id.slice(0, 20)} vs ${items[j].id.slice(0, 20)} (${(sim * 100).toFixed(0)}% similar)`,
+        });
+      }
+    }
+  }
+
+  return conflicts.sort((a, b) => b.similarity - a.similarity);
+}
+
+/**
+ * Reset the cached artifact index (call when artifacts change).
+ */
+export function resetArtifactIndex() {
+  _artifactIndex = null;
+  if (existsSync(INDEX_FILE)) {
+    const { unlinkSync } = require('node:fs');
+    try { unlinkSync(INDEX_FILE); } catch { /* ignore */ }
+  }
+}
+
+/**
+ * Get artifact index stats.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.rootDir]
+ * @returns {Promise<{ total: number, byType: object, cached: boolean }>}
+ */
+export async function artifactIndexStats({ rootDir } = {}) {
+  const index = await buildArtifactIndex({ rootDir });
+  const byType = {};
+  for (const entry of index) {
+    byType[entry.type] = (byType[entry.type] || 0) + 1;
+  }
+  return {
+    total: index.length,
+    byType,
+    indexed: index.filter(e => e.embedding).length,
+    cached: _artifactIndex !== null,
+  };
+}