chati-dev 3.2.4 → 3.3.0

package/src/installer/validator.js

@@ -1,7 +1,10 @@
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
+import yaml from 'js-yaml';
 import { hashFile } from './file-hasher.js';
 import { loadManifest } from './manifest.js';
+import { ADAPTABLE_FILES } from '../config/framework-adapter.js';
+import { validateSchema, CONFIG_SCHEMA } from '../utils/schema-validator.js';
 
 /**
  * Validate chati.dev installation
@@ -20,6 +23,7 @@ export async function validateInstallation(targetDir) {
     memories: { pass: false, details: [] },
     context: { pass: false, details: [] },
     integrity: { pass: false, details: [] },
+    config: { pass: false, details: [] },
     total: 0,
     passed: 0,
   };
@@ -171,6 +175,76 @@ export async function validateInstallation(targetDir) {
   results.total += 1;
   if (results.context.pass) results.passed += 1;
 
+  // Check provider overlays (if multiple providers configured)
+  const configYamlPath = join(targetDir, 'chati.dev', 'config.yaml');
+  if (existsSync(configYamlPath)) {
+    try {
+      const configContent = readFileSync(configYamlPath, 'utf-8');
+      const enabledProviders = [];
+      let primaryProvider = null;
+      let currentProvider = null;
+
+      for (const line of configContent.split('\n')) {
+        const provLine = line.match(/^\s{4}(\w+):$/);
+        if (provLine && ['claude', 'gemini', 'codex'].includes(provLine[1])) {
+          currentProvider = provLine[1];
+        }
+        if (currentProvider && line.includes('enabled: true')) {
+          enabledProviders.push(currentProvider);
+        }
+        if (currentProvider && line.includes('primary: true')) {
+          primaryProvider = currentProvider;
+        }
+      }
+
+      // Validate overlay completeness for each secondary provider
+      if (enabledProviders.length > 1 && primaryProvider) {
+        const secondaryProviders = enabledProviders.filter(p => p !== primaryProvider);
+        const overlayDetails = [];
+
+        for (const provider of secondaryProviders) {
+          let present = 0;
+          let missing = 0;
+          const missingFiles = [];
+
+          for (const file of ADAPTABLE_FILES) {
+            const overlayPath = join(targetDir, 'chati.dev', '.adapted', provider, file);
+            if (existsSync(overlayPath)) {
+              present++;
+            } else {
+              missing++;
+              missingFiles.push(file);
+            }
+          }
+
+          overlayDetails.push({ provider, present, missing, missingFiles });
+        }
+
+        results.context.details.push({ overlays: overlayDetails });
+      }
+    } catch {
+      // Config parsing is best-effort for validation
+    }
+  }
+
+  // Check config.yaml schema validity
+  if (existsSync(configYamlPath)) {
+    try {
+      const configData = yaml.load(readFileSync(configYamlPath, 'utf-8'));
+      const configValidation = validateSchema(configData, CONFIG_SCHEMA);
+      results.config.pass = configValidation.valid;
+      results.config.details.push({
+        errors: configValidation.errors,
+        warnings: configValidation.warnings,
+      });
+    } catch (err) {
+      results.config.pass = false;
+      results.config.details.push({ error: `YAML parse error: ${err.message}` });
+    }
+  }
+  results.total += 1;
+  if (results.config.pass) results.passed += 1;
+
   // Check integrity: verify installed files match manifest hashes
   const manifest = loadManifest(targetDir);
   if (manifest && manifest.files) {

package/src/intelligence/context-status.js

@@ -2,11 +2,15 @@ import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 
 const BRACKETS = [
-  { name: 'FRESH',    min: 60, max: 100, layers: ['L0', 'L1', 'L2', 'L3', 'L4'], budget: 2500 },
-  { name: 'MODERATE', min: 40, max: 60,  layers: ['L0', 'L1', 'L2', 'L3', 'L4'], budget: 2000 },
-  { name: 'DEPLETED', min: 25, max: 40,  layers: ['L0', 'L1', 'L2'],             budget: 1500 },
-  { name: 'CRITICAL', min: 0,  max: 25,  layers: ['L0', 'L1'],                   budget: 800 },
+  { name: 'FRESH',    min: 60, max: 100, layers: ['L0', 'L1', 'L2', 'L3', 'L4'], budget: 8000 },
+  { name: 'MODERATE', min: 40, max: 60,  layers: ['L0', 'L1', 'L2', 'L3'],       budget: 5000 },
+  { name: 'DEPLETED', min: 25, max: 40,  layers: ['L0', 'L1', 'L2'],             budget: 3000 },
+  { name: 'CRITICAL', min: 0,  max: 25,  layers: ['L0', 'L1'],                   budget: 1500 },
 ];
+// NOTE: This BRACKETS array is intentionally duplicated from src/context/bracket-tracker.js
+// for module isolation. bracket-tracker.js is the canonical source of truth.
+// If bracket ranges or budgets change, update BOTH files.
+// Format differs: here = array with `budget`, there = object with `tokenBudget`.
 
 /**
  * Get context status based on session state
@@ -40,7 +44,7 @@ export function getContextStatus(targetDir) {
 
   const bracket = BRACKETS.find(b => remainingPercent >= b.min && remainingPercent <= b.max) || BRACKETS[0];
 
-  const memoryLevels = { FRESH: 'none', MODERATE: 'metadata', DEPLETED: 'chunks', CRITICAL: 'full' };
+  const memoryLevels = { FRESH: 'full', MODERATE: 'chunks', DEPLETED: 'metadata', CRITICAL: 'none' };
 
   return {
     bracket: bracket.name,

package/src/intelligence/document-sharder.js

@@ -0,0 +1,221 @@
+/**
+ * @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 };

package/src/intelligence/elicitation.js

@@ -0,0 +1,265 @@
+/**
+ * @fileoverview Advanced elicitation techniques for Brief agent.
+ *
+ * Provides 15 structured questioning techniques that adapt
+ * to project context for deeper requirement extraction.
+ *
+ * Constitution Protocol 8 — Interaction Model.
+ */
+
+// ---------------------------------------------------------------------------
+// Techniques
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} Technique
+ * @property {string} id - Unique technique identifier
+ * @property {string} name - Human-readable name
+ * @property {string} description - When to use this technique
+ * @property {string} template - Prompt template with {placeholders}
+ * @property {string[]} bestFor - Context categories where this excels
+ */
+
+/**
+ * All 15 elicitation techniques.
+ * @type {Technique[]}
+ */
+export const TECHNIQUES = [
+  {
+    id: 'open-ended',
+    name: 'Open-Ended Questions',
+    description: 'Discover broad goals and motivations',
+    template: 'What is the primary problem you want {project} to solve?',
+    bestFor: ['greenfield', 'discovery', 'early'],
+  },
+  {
+    id: 'closed',
+    name: 'Closed Questions',
+    description: 'Confirm specific decisions quickly',
+    template: 'Should {feature} support {option_a} or {option_b}?',
+    bestFor: ['confirmation', 'late', 'refinement'],
+  },
+  {
+    id: 'scaling',
+    name: 'Scaling Questions',
+    description: 'Quantify priorities and satisfaction levels',
+    template: 'On a scale of 1-10, how important is {aspect} for your project?',
+    bestFor: ['prioritization', 'nfr', 'tradeoffs'],
+  },
+  {
+    id: 'five-whys',
+    name: 'Five Whys',
+    description: 'Drill to root cause of requirements',
+    template: 'You mentioned {requirement}. Why is that important? (And why is that? Repeat 5x)',
+    bestFor: ['root-cause', 'deep-analysis', 'unclear'],
+  },
+  {
+    id: 'scenario',
+    name: 'Scenario-Based',
+    description: 'Explore behavior through concrete situations',
+    template: 'Imagine a user is trying to {action}. Walk me through what should happen step by step.',
+    bestFor: ['user-flow', 'ux', 'behavior'],
+  },
+  {
+    id: 'constraint',
+    name: 'Constraint Analysis',
+    description: 'Identify limitations and boundaries',
+    template: 'What are the hard constraints for {project}? (budget, timeline, technology, team size)',
+    bestFor: ['planning', 'nfr', 'feasibility'],
+  },
+  {
+    id: 'analogy',
+    name: 'Analogy Questions',
+    description: 'Reference existing products for clarity',
+    template: 'Is {project} more like {product_a} or {product_b}? What would you change?',
+    bestFor: ['greenfield', 'vision', 'discovery'],
+  },
+  {
+    id: 'day-in-life',
+    name: 'Day in the Life',
+    description: 'Understand user workflows holistically',
+    template: 'Walk me through a typical day for a {persona} using {project}.',
+    bestFor: ['user-research', 'ux', 'personas'],
+  },
+  {
+    id: 'persona',
+    name: 'Persona Questions',
+    description: 'Define user types and their needs',
+    template: 'Who are the main types of users for {project}? What does each one need most?',
+    bestFor: ['user-research', 'discovery', 'early'],
+  },
+  {
+    id: 'exception',
+    name: 'Exception Questions',
+    description: 'Explore edge cases and error scenarios',
+    template: 'What should happen if {action} fails or produces unexpected results?',
+    bestFor: ['edge-cases', 'error-handling', 'robustness'],
+  },
+  {
+    id: 'moscow',
+    name: 'MoSCoW Priority',
+    description: 'Classify features by criticality',
+    template: 'For the features you described, which are Must-Have, Should-Have, Could-Have, and Won\'t-Have?',
+    bestFor: ['prioritization', 'planning', 'scope'],
+  },
+  {
+    id: 'prototype',
+    name: 'Prototype Questions',
+    description: 'Validate UI/UX assumptions early',
+    template: 'If I showed you a rough mockup of {feature}, what would you check first?',
+    bestFor: ['ux', 'visual', 'validation'],
+  },
+  {
+    id: 'acceptance',
+    name: 'Acceptance Criteria',
+    description: 'Define clear "done" criteria',
+    template: 'How will you know {feature} is working correctly? What does success look like?',
+    bestFor: ['quality', 'testing', 'refinement'],
+  },
+  {
+    id: 'edge-case',
+    name: 'Edge Case Exploration',
+    description: 'Probe boundaries systematically',
+    template: 'What happens when {input} is empty/null/very large/negative? How should {feature} behave?',
+    bestFor: ['edge-cases', 'robustness', 'quality'],
+  },
+  {
+    id: 'stakeholder-map',
+    name: 'Stakeholder Mapping',
+    description: 'Identify all parties and their interests',
+    template: 'Besides end users, who else cares about {project}? (investors, ops team, regulators, partners)',
+    bestFor: ['stakeholders', 'discovery', 'enterprise'],
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Select the top N most relevant techniques for a given context.
+ *
+ * @param {{ phase?: string, projectType?: string, keywords?: string[], userLevel?: string }} context
+ * @param {number} [topN=3]
+ * @returns {Technique[]}
+ */
+export function selectTechniques(context, topN = 3) {
+  const scored = TECHNIQUES.map(technique => ({
+    technique,
+    score: scoreTechnique(technique, context),
+  }));
+
+  // Sort by score descending
+  scored.sort((a, b) => b.score - a.score);
+
+  return scored.slice(0, topN).map(s => s.technique);
+}
+
+/**
+ * Build a formatted elicitation prompt for a specific technique.
+ *
+ * @param {Technique} technique
+ * @param {{ project?: string, feature?: string, action?: string, persona?: string }} projectContext
+ * @returns {string}
+ */
+export function buildElicitationPrompt(technique, projectContext = {}) {
+  let prompt = technique.template;
+
+  // Replace placeholders with context values or generic defaults
+  const defaults = {
+    project: 'the project',
+    feature: 'this feature',
+    action: 'perform this action',
+    persona: 'a typical user',
+    requirement: 'this requirement',
+    aspect: 'this aspect',
+    input: 'the input',
+    option_a: 'option A',
+    option_b: 'option B',
+    product_a: 'Product A',
+    product_b: 'Product B',
+  };
+
+  const merged = { ...defaults, ...projectContext };
+
+  for (const [key, value] of Object.entries(merged)) {
+    prompt = prompt.replace(new RegExp(`\\{${key}\\}`, 'g'), value);
+  }
+
+  return prompt;
+}
+
+/**
+ * Get a technique by ID.
+ *
+ * @param {string} id
+ * @returns {Technique|null}
+ */
+export function getTechnique(id) {
+  return TECHNIQUES.find(t => t.id === id) || null;
+}
+
+// ---------------------------------------------------------------------------
+// Scoring
+// ---------------------------------------------------------------------------
+
+/**
+ * Score how relevant a technique is for a given context.
+ *
+ * @param {Technique} technique
+ * @param {{ phase?: string, projectType?: string, keywords?: string[], userLevel?: string }} context
+ * @returns {number}
+ */
+function scoreTechnique(technique, context) {
+  let score = 0;
+
+  // Phase matching
+  if (context.phase) {
+    const phaseMap = {
+      discover: ['discovery', 'early', 'greenfield', 'user-research', 'vision'],
+      plan: ['planning', 'prioritization', 'scope', 'tradeoffs', 'nfr', 'feasibility'],
+      build: ['refinement', 'quality', 'testing', 'edge-cases', 'robustness'],
+      deploy: ['confirmation', 'late', 'validation'],
+    };
+    const phaseKeywords = phaseMap[context.phase] || [];
+    for (const kw of phaseKeywords) {
+      if (technique.bestFor.includes(kw)) {
+        score += 3;
+      }
+    }
+  }
+
+  // Project type matching
+  if (context.projectType === 'greenfield' && technique.bestFor.includes('greenfield')) {
+    score += 2;
+  }
+  if (context.projectType === 'brownfield' && technique.bestFor.includes('refinement')) {
+    score += 2;
+  }
+
+  // Keyword matching
+  if (context.keywords) {
+    for (const kw of context.keywords) {
+      if (technique.bestFor.includes(kw.toLowerCase())) {
+        score += 2;
+      }
+      if (technique.description.toLowerCase().includes(kw.toLowerCase())) {
+        score += 1;
+      }
+    }
+  }
+
+  // User level adjustment
+  if (context.userLevel === 'beginner') {
+    if (['open-ended', 'scenario', 'analogy'].includes(technique.id)) {
+      score += 1; // Easier techniques for beginners
+    }
+  }
+  if (context.userLevel === 'expert') {
+    if (['five-whys', 'constraint', 'stakeholder-map'].includes(technique.id)) {
+      score += 1; // More advanced for experts
+    }
+  }
+
+  return score;
+}

package/src/intelligence/timeline.js

@@ -6,6 +6,11 @@
  * results, handoffs, and deviations.
  */
 
+/**
+ * @deprecated Not currently imported by any production module.
+ * Retained for potential future integration. Remove if still unused by v4.0.
+ */
+
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';