chati-dev 4.2.1 → 4.3.0

package/src/intelligence/decision-engine.js

@@ -1,256 +0,0 @@
-/**
- * IDS Decision Engine — Intelligent Deduplication & Similarity scoring.
- *
- * Before creating any new artifact, scores existing registry entities
- * for similarity. Enforces Constitution Article XIV: REUSE > ADAPT > CREATE.
- *
- * NOTE: This module handles intent-level similarity with weighted scoring.
- * For entity-level routing (COMPASS registry lookup), see `decision/engine.js`.
- *
- * Algorithm:
- *   similarity = (keywordOverlap * 0.6) + (purposeSimilarity * 0.4)
- *   >= 90% → REUSE, 60-89% → ADAPT, < 60% → CREATE
- */
-
-import { existsSync, readFileSync } from 'fs';
-
-
-/**
- * @typedef {object} DecisionIntent
- * @property {string[]} keywords - Keywords describing what we want to create
- * @property {string} purpose - One-line description of the intended artifact
- */
-
-/**
- * @typedef {object} DecisionResult
- * @property {string} decision - 'REUSE' | 'ADAPT' | 'CREATE'
- * @property {string|null} matchId - The best matching entity ID (null for CREATE)
- * @property {number} similarity - 0-100 similarity score
- * @property {string} reasoning - Human-readable explanation
- * @property {object|null} match - The best matching entity data
- */
-
-/**
- * Evaluate a creation intent against the entity registry.
- *
- * @param {DecisionIntent} intent - What we want to create
- * @param {string} registryPath - Absolute path to entity-registry.yaml
- * @returns {DecisionResult}
- */
-export function evaluateDecision(intent, registryPath) {
-  if (!intent || !intent.keywords || !intent.purpose) {
-    return {
-      decision: 'CREATE',
-      matchId: null,
-      similarity: 0,
-      reasoning: 'No intent provided, defaulting to CREATE.',
-      match: null,
-    };
-  }
-
-  const entities = loadRegistryEntities(registryPath);
-  if (entities.length === 0) {
-    return {
-      decision: 'CREATE',
-      matchId: null,
-      similarity: 0,
-      reasoning: 'Registry empty or not found, defaulting to CREATE.',
-      match: null,
-    };
-  }
-
-  let bestMatch = null;
-  let bestScore = 0;
-  let bestId = null;
-
-  for (const entity of entities) {
-    const score = calculateIntentSimilarity(intent, entity);
-    if (score > bestScore) {
-      bestScore = score;
-      bestMatch = entity;
-      bestId = entity.id;
-    }
-  }
-
-  const similarity = Math.round(bestScore * 100);
-  let decision;
-  let reasoning;
-
-  if (similarity >= 90) {
-    decision = 'REUSE';
-    reasoning = `Entity "${bestId}" is ${similarity}% similar. Reuse as-is (Article XIV).`;
-  } else if (similarity >= 60) {
-    decision = 'ADAPT';
-    reasoning = `Entity "${bestId}" is ${similarity}% similar. Adapt for current needs (adaptability: ${bestMatch?.adaptability ?? 'unknown'}).`;
-  } else {
-    decision = 'CREATE';
-    reasoning = bestId
-      ? `Best match "${bestId}" is only ${similarity}% similar. Create new artifact.`
-      : 'No sufficiently similar entity found. Create new artifact.';
-  }
-
-  return {
-    decision,
-    matchId: similarity >= 60 ? bestId : null,
-    similarity,
-    reasoning,
-    match: similarity >= 60 ? bestMatch : null,
-  };
-}
-
-/**
- * Calculate combined similarity between an intent and an entity.
- *
- * similarity = (keywordOverlap * 0.6) + (purposeSimilarity * 0.4)
- *
- * @param {DecisionIntent} intent
- * @param {{ keywords: string[], purpose: string }} entity
- * @returns {number} 0.0 to 1.0
- */
-export function calculateIntentSimilarity(intent, entity) {
-  const kwScore = keywordOverlap(intent.keywords, entity.keywords || []);
-  const purposeScore = purposeSimilarity(intent.purpose, entity.purpose || '');
-  return (kwScore * 0.6) + (purposeScore * 0.4);
-}
-
-/**
- * Calculate keyword overlap using token-based Jaccard similarity.
- *
- * @param {string[]} a - Intent keywords
- * @param {string[]} b - Entity keywords
- * @returns {number} 0.0 to 1.0
- */
-export function keywordOverlap(a, b) {
-  if (!a || !b || a.length === 0 || b.length === 0) return 0;
-
-  const setA = new Set(a.map(k => k.toLowerCase().trim()));
-  const setB = new Set(b.map(k => k.toLowerCase().trim()));
-
-  let intersection = 0;
-  for (const k of setA) {
-    if (setB.has(k)) intersection++;
-  }
-
-  const union = new Set([...setA, ...setB]).size;
-  return union === 0 ? 0 : intersection / union;
-}
-
-/**
- * Calculate purpose similarity using token overlap (bag-of-words).
- *
- * @param {string} a - Intent purpose
- * @param {string} b - Entity purpose
- * @returns {number} 0.0 to 1.0
- */
-export function purposeSimilarity(a, b) {
-  if (!a || !b) return 0;
-
-  const tokenize = (text) => {
-    return text
-      .toLowerCase()
-      .replace(/[^a-z0-9\s]/g, '')
-      .split(/\s+/)
-      .filter(t => t.length > 2); // Skip tiny words
-  };
-
-  const tokensA = new Set(tokenize(a));
-  const tokensB = new Set(tokenize(b));
-
-  if (tokensA.size === 0 || tokensB.size === 0) return 0;
-
-  let intersection = 0;
-  for (const t of tokensA) {
-    if (tokensB.has(t)) intersection++;
-  }
-
-  const union = new Set([...tokensA, ...tokensB]).size;
-  return union === 0 ? 0 : intersection / union;
-}
-
-/**
- * Load and flatten entity registry into a searchable array.
- *
- * @param {string} registryPath - Absolute path to entity-registry.yaml
- * @returns {Array<{ id: string, keywords: string[], purpose: string, path: string, type: string, adaptability: number }>}
- */
-export function loadRegistryEntities(registryPath) {
-  if (!registryPath || !existsSync(registryPath)) return [];
-
-  try {
-    const raw = readFileSync(registryPath, 'utf-8');
-    return parseRegistryEntities(raw);
-  } catch { /* expected: file may not exist */
-    return [];
-  }
-}
-
-/**
- * Parse registry YAML into flat entity array.
- * Uses simple regex parsing consistent with the codebase pattern.
- *
- * @param {string} raw - Raw YAML content
- * @returns {Array<{ id: string, keywords: string[], purpose: string, path: string, type: string, adaptability: number }>}
- */
-export function parseRegistryEntities(raw) {
-  const entities = [];
-  const lines = raw.split('\n');
-
-  let currentCategory = null;
-  let currentEntity = null;
-  let currentData = {};
-
-  for (const line of lines) {
-    // Category header (agents:, templates:, etc.) — 2-space indent under entities:
-    const categoryMatch = line.match(/^ {2}(\w[\w-]*):\s*$/);
-    if (categoryMatch && !line.match(/^\s{4}/)) {
-      // Save previous entity
-      if (currentEntity && currentData.purpose) {
-        entities.push({ id: `${currentCategory}/${currentEntity}`, ...currentData });
-      }
-      currentCategory = categoryMatch[1];
-      currentEntity = null;
-      currentData = {};
-      continue;
-    }
-
-    // Entity header (e.g., "    orchestrator:") — 4-space indent
-    const entityMatch = line.match(/^ {4}([\w][\w-]*):\s*$/);
-    if (entityMatch) {
-      // Save previous entity
-      if (currentEntity && currentData.purpose) {
-        entities.push({ id: `${currentCategory}/${currentEntity}`, ...currentData });
-      }
-      currentEntity = entityMatch[1];
-      currentData = { keywords: [], purpose: '', path: '', type: '', adaptability: 0.5 };
-      continue;
-    }
-
-    if (!currentEntity) continue;
-
-    // Entity fields (6-space indent)
-    const pathMatch = line.match(/^\s{6}path:\s*(.+)/);
-    if (pathMatch) { currentData.path = pathMatch[1].trim(); continue; }
-
-    const typeMatch = line.match(/^\s{6}type:\s*(.+)/);
-    if (typeMatch) { currentData.type = typeMatch[1].trim(); continue; }
-
-    const purposeMatch = line.match(/^\s{6}purpose:\s*"?([^"]*)"?\s*$/);
-    if (purposeMatch) { currentData.purpose = purposeMatch[1].trim(); continue; }
-
-    const adaptMatch = line.match(/^\s{6}adaptability:\s*([\d.]+)/);
-    if (adaptMatch) { currentData.adaptability = parseFloat(adaptMatch[1]); continue; }
-
-    const kwMatch = line.match(/^\s{6}keywords:\s*\[(.+)\]/);
-    if (kwMatch) {
-      currentData.keywords = kwMatch[1].split(',').map(k => k.trim().replace(/^['"]|['"]$/g, ''));
-      continue;
-    }
-  }
-
-  // Save last entity
-  if (currentEntity && currentData.purpose) {
-    entities.push({ id: `${currentCategory}/${currentEntity}`, ...currentData });
-  }
-
-  return entities;
-}

package/src/intelligence/document-sharder.js

@@ -1,221 +0,0 @@
-/**
- * @fileoverview Document sharding for large PRDs and specifications.
- *
- * Splits large documents into manageable shards while respecting
- * heading boundaries and providing overlap for context continuity.
- *
- * Constitution Article XII — Context Bracket Management.
- */
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-/** Default maximum shard size in characters (~2K tokens). */
-const DEFAULT_MAX_SHARD_SIZE = 8_000;
-
-/** Overlap characters between shards for context continuity. */
-const DEFAULT_OVERLAP = 800;
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-/**
- * @typedef {object} Shard
- * @property {number} index - Shard index (0-based)
- * @property {string} content - Shard content
- * @property {string[]} sections - Section headings in this shard
- * @property {number} startOffset - Character offset in original document
- * @property {number} endOffset - End character offset
- * @property {boolean} hasOverlap - Whether this shard has overlap from previous
- */
-
-/**
- * Split a document into shards, respecting heading boundaries.
- *
- * @param {string} content - Full document content
- * @param {{ maxShardSize?: number, overlap?: number }} [options={}]
- * @returns {Shard[]}
- */
-export function shardDocument(content, options = {}) {
-  if (!content || typeof content !== 'string') {
-    return [];
-  }
-
-  const maxSize = options.maxShardSize || DEFAULT_MAX_SHARD_SIZE;
-  const overlap = options.overlap || DEFAULT_OVERLAP;
-
-  // If content fits in one shard, return as-is
-  if (content.length <= maxSize) {
-    return [{
-      index: 0,
-      content,
-      sections: extractSections(content),
-      startOffset: 0,
-      endOffset: content.length,
-      hasOverlap: false,
-    }];
-  }
-
-  // Find heading boundaries (## or # markers)
-  const headingPattern = /^#{1,3}\s+.+$/gm;
-  const headings = [];
-  let match;
-
-  while ((match = headingPattern.exec(content)) !== null) {
-    headings.push({ offset: match.index, text: match[0].trim() });
-  }
-
-  // Build shards at heading boundaries
-  const shards = [];
-  let currentStart = 0;
-
-  while (currentStart < content.length) {
-    let endPos = currentStart + maxSize;
-
-    if (endPos >= content.length) {
-      // Last shard
-      endPos = content.length;
-    } else {
-      // Find the best heading boundary to split at
-      const bestBreak = findBestBreak(headings, currentStart, endPos);
-      if (bestBreak > currentStart) {
-        endPos = bestBreak;
-      } else {
-        // No heading found — break at paragraph boundary
-        const paragraphBreak = content.lastIndexOf('\n\n', endPos);
-        if (paragraphBreak > currentStart) {
-          endPos = paragraphBreak;
-        }
-      }
-    }
-
-    const shardContent = content.slice(currentStart, endPos);
-    const hasOverlap = currentStart > 0;
-
-    shards.push({
-      index: shards.length,
-      content: shardContent,
-      sections: extractSections(shardContent),
-      startOffset: currentStart,
-      endOffset: endPos,
-      hasOverlap,
-    });
-
-    // Advance with overlap
-    currentStart = Math.max(currentStart + 1, endPos - overlap);
-  }
-
-  return shards;
-}
-
-/**
- * Reassemble shards back into a document, removing overlaps.
- *
- * @param {Shard[]} shards
- * @returns {string}
- */
-export function reassembleShards(shards) {
-  if (!shards || shards.length === 0) return '';
-  if (shards.length === 1) return shards[0].content;
-
-  // Sort by index
-  const sorted = [...shards].sort((a, b) => a.index - b.index);
-
-  // Use non-overlapping portions
-  const parts = [];
-  for (let i = 0; i < sorted.length; i++) {
-    const shard = sorted[i];
-    if (i === 0) {
-      // First shard: use everything up to where next shard's unique content starts
-      if (sorted.length > 1) {
-        const nextStart = sorted[1].startOffset;
-        const overlapStart = shard.endOffset - nextStart;
-        if (overlapStart > 0) {
-          parts.push(shard.content.slice(0, shard.content.length - overlapStart));
-        } else {
-          parts.push(shard.content);
-        }
-      } else {
-        parts.push(shard.content);
-      }
-    } else if (i === sorted.length - 1) {
-      // Last shard: use from overlap end to end
-      const prevEnd = sorted[i - 1].endOffset;
-      const overlapLength = prevEnd - shard.startOffset;
-      if (overlapLength > 0) {
-        parts.push(shard.content.slice(overlapLength));
-      } else {
-        parts.push(shard.content);
-      }
-    } else {
-      // Middle shard: use from overlap end to before next shard's overlap
-      const prevEnd = sorted[i - 1].endOffset;
-      const startOverlap = prevEnd - shard.startOffset;
-      const nextStart = sorted[i + 1].startOffset;
-      const endOverlap = shard.endOffset - nextStart;
-
-      const start = Math.max(0, startOverlap);
-      const end = endOverlap > 0 ? shard.content.length - endOverlap : shard.content.length;
-      parts.push(shard.content.slice(start, end));
-    }
-  }
-
-  return parts.join('');
-}
-
-/**
- * Find the shard containing a specific section heading.
- *
- * @param {Shard[]} shards
- * @param {string} sectionName - Heading text to find (partial match)
- * @returns {Shard|null}
- */
-export function getShardForSection(shards, sectionName) {
-  if (!shards || !sectionName) return null;
-
-  const lower = sectionName.toLowerCase();
-  return shards.find(shard =>
-    shard.sections.some(s => s.toLowerCase().includes(lower))
-  ) || null;
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Find the best heading boundary to break at within a range.
- *
- * @param {{ offset: number, text: string }[]} headings
- * @param {number} start
- * @param {number} end
- * @returns {number} Offset of best break point, or 0 if none found
- */
-function findBestBreak(headings, start, end) {
-  // Find the last heading that starts before end and after start
-  let bestOffset = 0;
-  for (const heading of headings) {
-    if (heading.offset > start && heading.offset <= end) {
-      bestOffset = heading.offset;
-    }
-  }
-  return bestOffset;
-}
-
-/**
- * Extract section headings from content.
- *
- * @param {string} content
- * @returns {string[]}
- */
-function extractSections(content) {
-  const headings = content.match(/^#{1,3}\s+.+$/gm) || [];
-  return headings.map(h => h.replace(/^#+\s+/, '').trim());
-}
-
-/**
- * Exported constants for testing.
- */
-export { DEFAULT_MAX_SHARD_SIZE, DEFAULT_OVERLAP };