chati-dev 3.3.1 → 4.0.0

package/scripts/doctor/checks/schemas.js

@@ -0,0 +1,61 @@
+/**
+ * @fileoverview Doctor check: JSON Schema validation.
+ *
+ * Validates that all expected schema files exist and contain valid JSON.
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+const EXPECTED_SCHEMAS = [
+  'session.schema.json',
+  'config.schema.json',
+  'context.schema.json',
+  'memory.schema.json',
+  'task.schema.json',
+];
+
+/**
+ * Run schema validation check.
+ *
+ * @param {string} frameworkDir - Path to framework directory
+ * @returns {{ pass: boolean, details: string, severity: string, fixable: boolean, fixId: string|null }}
+ */
+export function checkSchemas(frameworkDir) {
+  const schemasDir = join(frameworkDir, 'schemas');
+  if (!existsSync(schemasDir)) {
+    return { pass: false, details: 'schemas/ directory not found', severity: 'critical', fixable: false, fixId: null };
+  }
+
+  const missing = [];
+  const invalid = [];
+
+  for (const schema of EXPECTED_SCHEMAS) {
+    const schemaPath = join(schemasDir, schema);
+    if (!existsSync(schemaPath)) {
+      missing.push(schema);
+      continue;
+    }
+    try {
+      JSON.parse(readFileSync(schemaPath, 'utf8'));
+    } catch {
+      invalid.push(schema);
+    }
+  }
+
+  if (missing.length > 0 || invalid.length > 0) {
+    const issues = [];
+    if (missing.length) issues.push(`missing: ${missing.join(', ')}`);
+    if (invalid.length) issues.push(`invalid JSON: ${invalid.join(', ')}`);
+    return {
+      pass: false,
+      details: issues.join('; '),
+      severity: missing.length > 0 ? 'critical' : 'warning',
+      fixable: false,
+      fixId: null,
+    };
+  }
+
+  const actualSchemas = readdirSync(schemasDir).filter(f => f.endsWith('.json'));
+  return { pass: true, details: `${actualSchemas.length} schemas valid`, severity: 'info', fixable: false, fixId: null };
+}

package/scripts/doctor/fixes/reference-fix.js

@@ -0,0 +1,100 @@
+/**
+ * @fileoverview Doctor fix: Broken path references.
+ *
+ * Scans entity-registry.yaml for broken path references and
+ * attempts to locate the correct paths.
+ */
+
+import { readFileSync, writeFileSync, existsSync, readdirSync } from 'fs';
+import { join, basename } from 'path';
+import yaml from 'js-yaml';
+
+/**
+ * Fix broken path references in entity-registry.yaml.
+ *
+ * @param {string} frameworkDir - Path to framework directory
+ * @returns {{ fixed: boolean, details: string, fixedPaths: string[] }}
+ */
+export function fixBrokenReferences(frameworkDir) {
+  const regPath = join(frameworkDir, 'data', 'entity-registry.yaml');
+  if (!existsSync(regPath)) {
+    return { fixed: false, details: 'entity-registry.yaml not found', fixedPaths: [] };
+  }
+
+  try {
+    const content = readFileSync(regPath, 'utf8');
+    const registry = yaml.load(content);
+
+    if (!registry || !registry.entities) {
+      return { fixed: false, details: 'No entities section found', fixedPaths: [] };
+    }
+
+    const fixedPaths = [];
+    let updatedContent = content;
+
+    for (const category of Object.values(registry.entities)) {
+      for (const [name, entity] of Object.entries(category)) {
+        if (!entity.path) continue;
+
+        // Path in registry is relative to project root (e.g., "chati.dev/agents/...")
+        const relPath = entity.path.replace(/^chati\.dev\//, '');
+        const fullPath = join(frameworkDir, relPath);
+
+        if (existsSync(fullPath)) continue;
+
+        // Try to find the file by name
+        const fileName = basename(relPath);
+        const found = findFile(frameworkDir, fileName);
+
+        if (found) {
+          const newPath = 'chati.dev/' + found;
+          updatedContent = updatedContent.replace(
+            `path: ${entity.path}`,
+            `path: ${newPath}`
+          );
+          fixedPaths.push(`${name}: ${entity.path} -> ${newPath}`);
+        }
+      }
+    }
+
+    if (fixedPaths.length === 0) {
+      return { fixed: false, details: 'No broken references found', fixedPaths: [] };
+    }
+
+    writeFileSync(regPath, updatedContent, 'utf8');
+    return { fixed: true, details: `Fixed ${fixedPaths.length} path reference(s)`, fixedPaths };
+  } catch (err) {
+    return { fixed: false, details: `Fix failed: ${err.message}`, fixedPaths: [] };
+  }
+}
+
+/**
+ * Search for a file by name within the framework directory.
+ *
+ * @param {string} dir - Directory to search
+ * @param {string} fileName - File name to find
+ * @param {string} [prefix=''] - Path prefix for recursion
+ * @param {number} [depth=0] - Current depth
+ * @returns {string|null} Relative path from frameworkDir or null
+ */
+function findFile(dir, fileName, prefix = '', depth = 0) {
+  if (depth > 4) return null;
+
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isFile() && entry.name === fileName) {
+        return rel;
+      }
+      if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules') {
+        const found = findFile(join(dir, entry.name), fileName, rel, depth + 1);
+        if (found) return found;
+      }
+    }
+  } catch {
+    // Permission error or inaccessible directory
+  }
+
+  return null;
+}

package/scripts/doctor/fixes/registry-fix.js

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview Doctor fix: Registry count correction.
+ *
+ * Auto-fixes entity_count mismatch in entity-registry.yaml
+ * by counting actual entities and updating metadata.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import yaml from 'js-yaml';
+
+/**
+ * Fix entity count mismatch in entity-registry.yaml.
+ *
+ * @param {string} frameworkDir - Path to framework directory
+ * @returns {{ fixed: boolean, details: string }}
+ */
+export function fixRegistryCount(frameworkDir) {
+  const regPath = join(frameworkDir, 'data', 'entity-registry.yaml');
+  if (!existsSync(regPath)) {
+    return { fixed: false, details: 'entity-registry.yaml not found' };
+  }
+
+  try {
+    const content = readFileSync(regPath, 'utf8');
+    const registry = yaml.load(content);
+
+    if (!registry || !registry.entities) {
+      return { fixed: false, details: 'No entities section found' };
+    }
+
+    // Count actual entities
+    let entityCount = 0;
+    for (const category of Object.values(registry.entities)) {
+      if (typeof category === 'object' && category !== null) {
+        entityCount += Object.keys(category).length;
+      }
+    }
+
+    const declaredCount = registry.metadata?.entity_count || 0;
+    if (entityCount === declaredCount) {
+      return { fixed: false, details: 'Entity count already correct' };
+    }
+
+    // Update the count using regex to preserve YAML formatting
+    const updatedContent = content.replace(
+      /entity_count:\s*\d+/,
+      `entity_count: ${entityCount}`
+    );
+
+    writeFileSync(regPath, updatedContent, 'utf8');
+    return { fixed: true, details: `Updated entity_count from ${declaredCount} to ${entityCount}` };
+  } catch (err) {
+    return { fixed: false, details: `Fix failed: ${err.message}` };
+  }
+}

package/scripts/doctor/index.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+
+/**
+ * @fileoverview Doctor — Modular diagnostic system with auto-fix capability.
+ *
+ * Orchestrates individual check modules and fix modules to provide
+ * comprehensive framework health validation and automatic repair.
+ *
+ * Exports:
+ *   runDoctor(frameworkDir, options) → DoctorReport
+ *   formatDoctorReport(report) → human-readable string
+ *
+ * DoctorReport:
+ *   { overall, checks, fixes, timestamp, summary }
+ */
+
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+
+// Check modules
+import { checkRegistry } from './checks/registry.js';
+import { checkSchemas } from './checks/schemas.js';
+import { checkConstitution } from './checks/constitution.js';
+import { checkAgents } from './checks/agents.js';
+import { checkPrismLayers } from './checks/prism-layers.js';
+import { checkDomainAlignment } from './checks/domain-alignment.js';
+
+// Fix modules
+import { fixRegistryCount } from './fixes/registry-fix.js';
+import { fixBrokenReferences } from './fixes/reference-fix.js';
+
+/**
+ * Map of fixId to fix function.
+ */
+const FIX_REGISTRY = {
+  'registry-count': fixRegistryCount,
+  'broken-references': fixBrokenReferences,
+};
+
+/**
+ * All available check functions.
+ */
+const CHECK_REGISTRY = {
+  registry: checkRegistry,
+  schemas: checkSchemas,
+  constitution: checkConstitution,
+  agents: checkAgents,
+  prismLayers: checkPrismLayers,
+  domainAlignment: checkDomainAlignment,
+};
+
+/**
+ * Run the doctor diagnostic suite.
+ *
+ * @param {string} frameworkDir - Path to the framework directory
+ * @param {object} [options={}] - Configuration options
+ * @param {boolean} [options.fix=false] - Run auto-fix for fixable issues
+ * @param {string[]} [options.checks] - Specific checks to run (default: all)
+ * @returns {object} DoctorReport
+ */
+export function runDoctor(frameworkDir, options = {}) {
+  const { fix = false, checks: checkFilter } = options;
+
+  if (!existsSync(frameworkDir)) {
+    return {
+      overall: 'UNHEALTHY',
+      checks: {
+        frameworkDir: { pass: false, details: `Directory not found: ${frameworkDir}`, severity: 'critical', fixable: false, fixId: null },
+      },
+      fixes: [],
+      timestamp: new Date().toISOString(),
+      summary: { total: 1, passed: 0, failed: 1, criticalFailures: 1, warnings: 0, fixesApplied: 0 },
+    };
+  }
+
+  // Run checks
+  const checksToRun = checkFilter
+    ? Object.entries(CHECK_REGISTRY).filter(([name]) => checkFilter.includes(name))
+    : Object.entries(CHECK_REGISTRY);
+
+  const checkResults = {};
+  for (const [name, checkFn] of checksToRun) {
+    checkResults[name] = checkFn(frameworkDir);
+  }
+
+  // Run fixes if requested
+  const fixes = [];
+  if (fix) {
+    for (const [name, result] of Object.entries(checkResults)) {
+      if (!result.pass && result.fixable && result.fixId) {
+        const fixFn = FIX_REGISTRY[result.fixId];
+        if (fixFn) {
+          const fixResult = fixFn(frameworkDir);
+          fixes.push({ check: name, fixId: result.fixId, ...fixResult });
+
+          // Re-run the check if fix was applied
+          if (fixResult.fixed) {
+            const checkFn = CHECK_REGISTRY[name];
+            if (checkFn) {
+              checkResults[name] = checkFn(frameworkDir);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // Determine overall health
+  const criticalFailures = Object.values(checkResults).filter(c => !c.pass && c.severity === 'critical');
+  const warnings = Object.values(checkResults).filter(c => !c.pass && c.severity === 'warning');
+
+  let overall;
+  if (criticalFailures.length > 0) {
+    overall = 'UNHEALTHY';
+  } else if (warnings.length > 0) {
+    overall = 'DEGRADED';
+  } else {
+    overall = 'HEALTHY';
+  }
+
+  return {
+    overall,
+    checks: checkResults,
+    fixes,
+    timestamp: new Date().toISOString(),
+    summary: {
+      total: Object.keys(checkResults).length,
+      passed: Object.values(checkResults).filter(c => c.pass).length,
+      failed: Object.values(checkResults).filter(c => !c.pass).length,
+      criticalFailures: criticalFailures.length,
+      warnings: warnings.length,
+      fixesApplied: fixes.filter(f => f.fixed).length,
+    },
+  };
+}
+
+/**
+ * Format a DoctorReport into a human-readable string.
+ *
+ * @param {object} report - DoctorReport from runDoctor
+ * @returns {string} Formatted report
+ */
+export function formatDoctorReport(report) {
+  const statusSymbol = {
+    HEALTHY: '[OK]',
+    DEGRADED: '[WARN]',
+    UNHEALTHY: '[FAIL]',
+  };
+
+  const checkSymbol = (check) => check.pass ? '[PASS]' : '[FAIL]';
+
+  const lines = [
+    '=== Doctor Report ===',
+    `Status: ${statusSymbol[report.overall] || '[ ? ]'} ${report.overall}`,
+    `Time:   ${report.timestamp}`,
+    '',
+  ];
+
+  if (report.summary) {
+    lines.push(`Summary: ${report.summary.passed}/${report.summary.total} checks passed`);
+    if (report.summary.criticalFailures > 0) {
+      lines.push(`         ${report.summary.criticalFailures} critical failure(s)`);
+    }
+    if (report.summary.warnings > 0) {
+      lines.push(`         ${report.summary.warnings} warning(s)`);
+    }
+    if (report.summary.fixesApplied > 0) {
+      lines.push(`         ${report.summary.fixesApplied} fix(es) applied`);
+    }
+    lines.push('');
+  }
+
+  lines.push('Checks:');
+  for (const [name, check] of Object.entries(report.checks)) {
+    const symbol = checkSymbol(check);
+    const severity = check.severity !== 'info' ? ` (${check.severity})` : '';
+    const fixable = check.fixable ? ' [fixable]' : '';
+    lines.push(`  ${symbol} ${name}: ${check.details}${severity}${fixable}`);
+  }
+
+  if (report.fixes && report.fixes.length > 0) {
+    lines.push('');
+    lines.push('Fixes:');
+    for (const fix of report.fixes) {
+      const symbol = fix.fixed ? '[FIXED]' : '[SKIP]';
+      lines.push(`  ${symbol} ${fix.check}: ${fix.details}`);
+    }
+  }
+
+  lines.push('');
+  lines.push('=== End Report ===');
+
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// CLI entrypoint
+// ---------------------------------------------------------------------------
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const args = process.argv.slice(2);
+  const fix = args.includes('--fix');
+  const frameworkDir = args.find(a => !a.startsWith('--')) || join(process.cwd(), 'chati.dev');
+
+  const report = runDoctor(frameworkDir, { fix });
+  console.log(formatDoctorReport(report));
+
+  if (report.overall === 'UNHEALTHY') {
+    process.exit(1);
+  }
+}

package/scripts/health-check.js

@@ -146,14 +146,14 @@ function checkAgents(frameworkDir) {
   const orchestratorDir = join(frameworkDir, 'orchestrator');
 
   const expectedAgents = {
-    'planning/greenfield-wu.md': 'greenfield-wu',
-    'planning/brownfield-wu.md': 'brownfield-wu',
-    'planning/brief.md': 'brief',
-    'planning/detail.md': 'detail',
-    'planning/architect.md': 'architect',
-    'planning/ux.md': 'ux',
-    'planning/phases.md': 'phases',
-    'planning/tasks.md': 'tasks',
+    'discover/greenfield-wu.md': 'greenfield-wu',
+    'discover/brownfield-wu.md': 'brownfield-wu',
+    'discover/brief.md': 'brief',
+    'plan/detail.md': 'detail',
+    'plan/architect.md': 'architect',
+    'plan/ux.md': 'ux',
+    'plan/phases.md': 'phases',
+    'plan/tasks.md': 'tasks',
     'quality/qa-planning.md': 'qa-planning',
     'quality/qa-implementation.md': 'qa-implementation',
     'build/dev.md': 'dev',

package/src/autonomy/surface-criteria.js

@@ -0,0 +1,226 @@
+/**
+ * Surface Criteria — 7 codified checkpoints for autonomous execution pause.
+ *
+ * Defines WHEN the system should surface a decision to the user instead
+ * of proceeding autonomously. Each criterion has a severity level:
+ *   critical — always pause, cannot be batch-confirmed
+ *   warning  — pause unless already confirmed, batchable
+ *
+ * Short-circuit: critical criteria (C003, C006, C007) are checked first.
+ * Batch confirm: C001 + C002 can be grouped into a single user prompt.
+ * Session memory: once confirmed, a criterion can be skipped for the session.
+ */
+
+/**
+ * The 7 surface criteria.
+ */
+export const CRITERIA = {
+  C001: {
+    id: 'C001',
+    name: 'ambiguous_requirement',
+    severity: 'warning',
+    description: 'Requirement is ambiguous and can be interpreted multiple ways.',
+  },
+  C002: {
+    id: 'C002',
+    name: 'multiple_approaches',
+    severity: 'warning',
+    description: 'Multiple valid implementation approaches exist.',
+  },
+  C003: {
+    id: 'C003',
+    name: 'destructive_operation',
+    severity: 'critical',
+    description: 'Action would delete, overwrite, or irreversibly modify existing data or code.',
+  },
+  C004: {
+    id: 'C004',
+    name: 'external_interaction',
+    severity: 'warning',
+    description: 'Action involves external systems (APIs, deployments, notifications).',
+  },
+  C005: {
+    id: 'C005',
+    name: 'cost_threshold',
+    severity: 'warning',
+    description: 'Estimated cost exceeds defined threshold for the session.',
+  },
+  C006: {
+    id: 'C006',
+    name: 'scope_creep',
+    severity: 'critical',
+    description: 'Proposed changes extend beyond the original scope or task definition.',
+  },
+  C007: {
+    id: 'C007',
+    name: 'security_sensitive',
+    severity: 'critical',
+    description: 'Action involves credentials, secrets, permissions, or security-sensitive operations.',
+  },
+};
+
+/**
+ * Check if a criterion has already been confirmed in this session.
+ *
+ * @param {string} criterionId - e.g., 'C001'
+ * @param {Set<string>|string[]} sessionDecisions - Previously confirmed criteria
+ * @returns {boolean}
+ */
+export function isAlreadyConfirmed(criterionId, sessionDecisions) {
+  if (!sessionDecisions) return false;
+  if (sessionDecisions instanceof Set) return sessionDecisions.has(criterionId);
+  if (Array.isArray(sessionDecisions)) return sessionDecisions.includes(criterionId);
+  return false;
+}
+
+/**
+ * Evaluate surface criteria for a given action context.
+ *
+ * @param {object} action - The action being evaluated
+ * @param {string} [action.type] - Action type (e.g., 'write', 'delete', 'deploy', 'create')
+ * @param {string} [action.target] - Target of the action (e.g., file path, resource name)
+ * @param {string} [action.description] - Human-readable action description
+ * @param {string[]} [action.tags] - Semantic tags (e.g., ['destructive', 'external', 'security'])
+ * @param {number} [action.estimatedCost] - Estimated cost in dollars
+ * @param {object} context - Evaluation context
+ * @param {Set<string>|string[]} [context.sessionDecisions] - Previously confirmed criteria
+ * @param {number} [context.costThreshold] - Cost threshold for C005 (default: 1.0)
+ * @param {string[]} [context.taskScope] - Original task scope keywords
+ * @returns {{ shouldPause: boolean, triggers: Array<{ id: string, name: string, severity: string, reason: string }>, batchable: boolean }}
+ */
+export function evaluateSurfaceCriteria(action, context = {}) {
+  if (!action) {
+    return { shouldPause: false, triggers: [], batchable: false };
+  }
+
+  const triggers = [];
+  const sessionDecisions = context.sessionDecisions || new Set();
+  const tags = new Set((action.tags || []).map(t => t.toLowerCase()));
+  const actionType = (action.type || '').toLowerCase();
+
+  // --- Critical criteria first (short-circuit) ---
+
+  // C003: Destructive operation
+  if (isDestructive(actionType, tags) && !isAlreadyConfirmed('C003', sessionDecisions)) {
+    triggers.push({
+      id: 'C003',
+      name: CRITERIA.C003.name,
+      severity: 'critical',
+      reason: `Destructive operation: ${action.description || action.type || 'unknown'}`,
+    });
+  }
+
+  // C006: Scope creep
+  if (isScopeCreep(action, context) && !isAlreadyConfirmed('C006', sessionDecisions)) {
+    triggers.push({
+      id: 'C006',
+      name: CRITERIA.C006.name,
+      severity: 'critical',
+      reason: `Changes extend beyond original task scope.`,
+    });
+  }
+
+  // C007: Security sensitive
+  if (isSecuritySensitive(actionType, tags, action.target) && !isAlreadyConfirmed('C007', sessionDecisions)) {
+    triggers.push({
+      id: 'C007',
+      name: CRITERIA.C007.name,
+      severity: 'critical',
+      reason: `Security-sensitive operation: ${action.description || action.target || 'unknown'}`,
+    });
+  }
+
+  // --- Warning criteria ---
+
+  // C001: Ambiguous requirement
+  if (tags.has('ambiguous') && !isAlreadyConfirmed('C001', sessionDecisions)) {
+    triggers.push({
+      id: 'C001',
+      name: CRITERIA.C001.name,
+      severity: 'warning',
+      reason: 'Requirement is ambiguous.',
+    });
+  }
+
+  // C002: Multiple approaches
+  if (tags.has('multiple_approaches') && !isAlreadyConfirmed('C002', sessionDecisions)) {
+    triggers.push({
+      id: 'C002',
+      name: CRITERIA.C002.name,
+      severity: 'warning',
+      reason: 'Multiple valid approaches exist.',
+    });
+  }
+
+  // C004: External interaction
+  if (isExternal(actionType, tags) && !isAlreadyConfirmed('C004', sessionDecisions)) {
+    triggers.push({
+      id: 'C004',
+      name: CRITERIA.C004.name,
+      severity: 'warning',
+      reason: `External interaction: ${action.description || action.type || 'unknown'}`,
+    });
+  }
+
+  // C005: Cost threshold
+  const costThreshold = context.costThreshold ?? 1.0;
+  if (action.estimatedCost && action.estimatedCost > costThreshold && !isAlreadyConfirmed('C005', sessionDecisions)) {
+    triggers.push({
+      id: 'C005',
+      name: CRITERIA.C005.name,
+      severity: 'warning',
+      reason: `Estimated cost $${action.estimatedCost.toFixed(2)} exceeds threshold $${costThreshold.toFixed(2)}.`,
+    });
+  }
+
+  // Determine if batchable (only if ALL triggers are warnings, no critical)
+  const hasCritical = triggers.some(t => t.severity === 'critical');
+  const warningOnly = triggers.length > 0 && !hasCritical;
+  const batchable = warningOnly && triggers.length > 1;
+
+  return {
+    shouldPause: triggers.length > 0,
+    triggers,
+    batchable,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Internal detection helpers
+// ---------------------------------------------------------------------------
+
+function isDestructive(actionType, tags) {
+  return (
+    tags.has('destructive') ||
+    ['delete', 'remove', 'drop', 'reset', 'force-push', 'overwrite'].includes(actionType)
+  );
+}
+
+function isSecuritySensitive(actionType, tags, target) {
+  if (tags.has('security') || tags.has('credentials') || tags.has('secrets')) return true;
+  if (target && /\.(env|pem|key|secret|credentials|password)/i.test(target)) return true;
+  if (['chmod', 'chown'].includes(actionType)) return true;
+  return false;
+}
+
+function isExternal(actionType, tags) {
+  return (
+    tags.has('external') ||
+    ['deploy', 'publish', 'push', 'send', 'notify'].includes(actionType)
+  );
+}
+
+function isScopeCreep(action, context) {
+  if (!context.taskScope || context.taskScope.length === 0) return false;
+  if (!action.tags || action.tags.length === 0) return false;
+
+  const scopeSet = new Set(context.taskScope.map(s => s.toLowerCase()));
+  const actionTags = action.tags.map(t => t.toLowerCase());
+
+  // If action has 'scope_creep' tag explicitly
+  if (actionTags.includes('scope_creep')) return true;
+
+  // If none of the action tags overlap with task scope, it may be scope creep
+  const hasOverlap = actionTags.some(t => scopeSet.has(t));
+  return !hasOverlap && actionTags.length > 0;
+}