@polymorphism-tech/morph-spec 4.2.0 → 4.3.1

package/src/lib/tracking/artifact-trail.js

@@ -0,0 +1,202 @@
+/**
+ * Artifact Trail — Debugging trail system
+ *
+ * Creates checkpoint artifact directories and saves:
+ * - Intermediate files (spec drafts, contract drafts)
+ * - Agent reasoning logs
+ * - Validator output logs
+ * - Failure artifacts on checkpoint failure
+ *
+ * Structure:
+ *   .morph/features/{feature}/artifacts/
+ *     checkpoint-{n}/
+ *       spec-draft.md
+ *       contracts-draft.cs
+ *       agent-reasoning.json
+ *       validator-output.json
+ *     checkpoint-{n}/failures/
+ *       failure-detail.json
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+const BASE_DIR = join(process.cwd(), '.morph/features');
+
+// ============================================================================
+// Path Helpers
+// ============================================================================
+
+function artifactsDir(feature) {
+  return join(BASE_DIR, feature, 'artifacts');
+}
+
+function checkpointDir(feature, checkpointNum) {
+  return join(artifactsDir(feature), `checkpoint-${checkpointNum}`);
+}
+
+function failuresDir(feature, checkpointNum) {
+  return join(checkpointDir(feature, checkpointNum), 'failures');
+}
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+// ============================================================================
+// Checkpoint Artifacts
+// ============================================================================
+
+/**
+ * Initialize a checkpoint artifact directory
+ * @param {string} feature - Feature name
+ * @param {number} checkpointNum - Checkpoint number
+ * @returns {string} Path to checkpoint directory
+ */
+export function initCheckpointArtifacts(feature, checkpointNum) {
+  const dir = checkpointDir(feature, checkpointNum);
+  ensureDir(dir);
+
+  const manifest = {
+    feature,
+    checkpointNum,
+    createdAt: new Date().toISOString(),
+    files: []
+  };
+
+  writeFileSync(join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2), 'utf8');
+  return dir;
+}
+
+/**
+ * Save an intermediate artifact file to a checkpoint directory
+ * @param {string} feature - Feature name
+ * @param {number} checkpointNum - Checkpoint number
+ * @param {string} filename - File name (e.g., 'spec-draft.md')
+ * @param {string} content - File content
+ * @returns {string} Full path to saved file
+ */
+export function saveArtifact(feature, checkpointNum, filename, content) {
+  const dir = ensureDir(checkpointDir(feature, checkpointNum));
+  const filePath = join(dir, filename);
+
+  writeFileSync(filePath, content, 'utf8');
+
+  // Update manifest
+  const manifestPath = join(dir, 'manifest.json');
+  if (existsSync(manifestPath)) {
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    if (!manifest.files.includes(filename)) {
+      manifest.files.push(filename);
+      manifest.updatedAt = new Date().toISOString();
+      writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
+    }
+  }
+
+  return filePath;
+}
+
+/**
+ * Save agent reasoning log
+ * @param {string} feature - Feature name
+ * @param {number} checkpointNum - Checkpoint number
+ * @param {Object} reasoning - Agent reasoning data
+ */
+export function saveAgentReasoning(feature, checkpointNum, reasoning) {
+  const entry = {
+    timestamp: new Date().toISOString(),
+    ...reasoning
+  };
+  saveArtifact(feature, checkpointNum, 'agent-reasoning.json', JSON.stringify(entry, null, 2));
+}
+
+/**
+ * Save validator output log
+ * @param {string} feature - Feature name
+ * @param {number} checkpointNum - Checkpoint number
+ * @param {Object} validatorOutput - Validator results
+ */
+export function saveValidatorOutput(feature, checkpointNum, validatorOutput) {
+  const entry = {
+    timestamp: new Date().toISOString(),
+    ...validatorOutput
+  };
+  saveArtifact(feature, checkpointNum, 'validator-output.json', JSON.stringify(entry, null, 2));
+}
+
+// ============================================================================
+// Failure Artifacts
+// ============================================================================
+
+/**
+ * Save failure artifacts when a checkpoint fails
+ * @param {string} feature - Feature name
+ * @param {number} checkpointNum - Checkpoint number
+ * @param {Object} failure - Failure details
+ * @param {string} failure.reason - Failure reason
+ * @param {Array} failure.errors - Array of error objects
+ * @param {number} failure.attemptNumber - Which retry attempt (1-3)
+ */
+export function saveFailureArtifacts(feature, checkpointNum, failure) {
+  const dir = ensureDir(failuresDir(feature, checkpointNum));
+  const filename = `failure-attempt-${failure.attemptNumber || 1}.json`;
+
+  const entry = {
+    feature,
+    checkpointNum,
+    timestamp: new Date().toISOString(),
+    ...failure
+  };
+
+  writeFileSync(join(dir, filename), JSON.stringify(entry, null, 2), 'utf8');
+  return join(dir, filename);
+}
+
+/**
+ * Get all failure artifacts for a checkpoint
+ * @param {string} feature - Feature name
+ * @param {number} checkpointNum - Checkpoint number
+ * @returns {Array} Array of failure records
+ */
+export function getFailureArtifacts(feature, checkpointNum) {
+  const dir = failuresDir(feature, checkpointNum);
+  if (!existsSync(dir)) return [];
+
+  const files = readdirSync(dir).filter(f => f.endsWith('.json'));
+
+  return files.map(f => {
+    try {
+      return JSON.parse(readFileSync(join(dir, f), 'utf8'));
+    } catch {
+      return null;
+    }
+  }).filter(Boolean);
+}
+
+/**
+ * List all checkpoints for a feature
+ * @param {string} feature - Feature name
+ * @returns {Array} Array of checkpoint info objects
+ */
+export function listCheckpointArtifacts(feature) {
+  const dir = artifactsDir(feature);
+  if (!existsSync(dir)) return [];
+
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+      .filter(d => d.isDirectory() && d.name.startsWith('checkpoint-'))
+      .map(d => {
+        const checkpointPath = join(dir, d.name);
+        const manifestPath = join(checkpointPath, 'manifest.json');
+        if (existsSync(manifestPath)) {
+          return JSON.parse(readFileSync(manifestPath, 'utf8'));
+        }
+        return { name: d.name, path: checkpointPath };
+      });
+  } catch {
+    return [];
+  }
+}

package/src/lib/trust/trust-manager.js

@@ -0,0 +1,269 @@
+/**
+ * Trust Manager — Track-record and auto-approval logic
+ *
+ * Computes trust level from checkpoint pass rate history.
+ * Enables auto-approval gates for features with proven track records.
+ *
+ * Trust levels:
+ *   low     < 80% pass rate
+ *   medium  80–90%
+ *   high    90–95%
+ *   maximum > 95%
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+// Default trust config (matches llm-interaction.json thresholds)
+const TRUST_THRESHOLDS = {
+  low: 0,
+  medium: 0.80,
+  high: 0.90,
+  maximum: 0.95
+};
+
+// Gates that can be auto-approved by trust level
+const AUTO_APPROVE_GATES = {
+  medium: ['design'],
+  high: ['design', 'tasks'],
+  maximum: ['design', 'tasks', 'proposal']
+};
+
+/**
+ * Load state.json
+ * @returns {Object} State
+ */
+function loadState() {
+  const statePath = join(process.cwd(), '.morph/state.json');
+  if (!existsSync(statePath)) return { features: {} };
+  try {
+    return JSON.parse(readFileSync(statePath, 'utf8'));
+  } catch {
+    return { features: {} };
+  }
+}
+
+/**
+ * Save state.json
+ * @param {Object} state
+ */
+function saveState(state) {
+  const statePath = join(process.cwd(), '.morph/state.json');
+  writeFileSync(statePath, JSON.stringify(state, null, 2), 'utf8');
+}
+
+/**
+ * Calculate trust level from checkpoint history
+ * @param {Array} checkpoints - Array of { passed: boolean, ... }
+ * @returns {{ level: string, passRate: number, total: number, passed: number }}
+ */
+export function calculateTrust(checkpoints = []) {
+  if (checkpoints.length === 0) {
+    return { level: 'low', passRate: 0, total: 0, passed: 0 };
+  }
+
+  const total = checkpoints.length;
+  const passed = checkpoints.filter(c => c.passed).length;
+  const passRate = passed / total;
+
+  let level = 'low';
+  if (passRate >= TRUST_THRESHOLDS.maximum) level = 'maximum';
+  else if (passRate >= TRUST_THRESHOLDS.high) level = 'high';
+  else if (passRate >= TRUST_THRESHOLDS.medium) level = 'medium';
+
+  return { level, passRate, total, passed };
+}
+
+/**
+ * Get current trust config for a feature
+ * @param {string} featureName
+ * @returns {{ level: string, passRate: number, autoApprove: string[], override?: string }}
+ */
+export function getTrust(featureName) {
+  const state = loadState();
+  const feature = state.features?.[featureName];
+
+  if (!feature) {
+    return { level: 'low', passRate: 0, autoApprove: [], source: 'default' };
+  }
+
+  // Check for manual override first
+  if (feature.trustConfig?.override) {
+    return {
+      level: feature.trustConfig.override.level,
+      passRate: feature.trustConfig.passRate || 0,
+      autoApprove: AUTO_APPROVE_GATES[feature.trustConfig.override.level] || [],
+      source: 'manual',
+      overrideReason: feature.trustConfig.override.reason,
+      overrideAt: feature.trustConfig.override.setAt
+    };
+  }
+
+  // Calculate from checkpoint history
+  const checkpoints = feature.checkpoints || [];
+  const { level, passRate, total, passed } = calculateTrust(checkpoints);
+
+  return {
+    level,
+    passRate,
+    total,
+    passed,
+    autoApprove: AUTO_APPROVE_GATES[level] || [],
+    source: 'calculated'
+  };
+}
+
+/**
+ * Manually set trust level with reason
+ * @param {string} featureName
+ * @param {string} level - 'low' | 'medium' | 'high' | 'maximum'
+ * @param {string} reason
+ */
+export function setTrust(featureName, level, reason) {
+  const validLevels = ['low', 'medium', 'high', 'maximum'];
+  if (!validLevels.includes(level)) {
+    throw new Error(`Invalid trust level: ${level}. Valid: ${validLevels.join(', ')}`);
+  }
+
+  const state = loadState();
+  if (!state.features[featureName]) {
+    throw new Error(`Feature not found: ${featureName}`);
+  }
+
+  if (!state.features[featureName].trustConfig) {
+    state.features[featureName].trustConfig = {};
+  }
+
+  state.features[featureName].trustConfig.override = {
+    level,
+    reason,
+    setAt: new Date().toISOString(),
+    setBy: 'manual'
+  };
+
+  saveState(state);
+
+  return {
+    feature: featureName,
+    level,
+    autoApprove: AUTO_APPROVE_GATES[level] || [],
+    reason
+  };
+}
+
+/**
+ * Clear manual trust override (revert to calculated)
+ * @param {string} featureName
+ */
+export function clearTrustOverride(featureName) {
+  const state = loadState();
+  if (state.features[featureName]?.trustConfig?.override) {
+    delete state.features[featureName].trustConfig.override;
+    saveState(state);
+  }
+}
+
+/**
+ * Check if a gate should be auto-approved based on trust level
+ * @param {string} featureName
+ * @param {string} gate - 'design' | 'tasks' | 'proposal'
+ * @returns {{ autoApprove: boolean, level: string, reason: string }}
+ */
+export function shouldAutoApprove(featureName, gate) {
+  const trust = getTrust(featureName);
+
+  if (!trust.autoApprove.includes(gate)) {
+    return {
+      autoApprove: false,
+      level: trust.level,
+      reason: `Trust level "${trust.level}" does not auto-approve "${gate}" gate (need: ${getMinLevelForGate(gate)})`
+    };
+  }
+
+  return {
+    autoApprove: true,
+    level: trust.level,
+    reason: `Auto-approved: ${trust.level} trust (${Math.round(trust.passRate * 100)}% pass rate, ${trust.total} checkpoints)`,
+    passRate: trust.passRate,
+    checkpointsTotal: trust.total
+  };
+}
+
+/**
+ * Get minimum trust level required for a gate
+ * @param {string} gate
+ * @returns {string}
+ */
+function getMinLevelForGate(gate) {
+  for (const [level, gates] of Object.entries(AUTO_APPROVE_GATES)) {
+    if (gates.includes(gate)) return level;
+  }
+  return 'maximum';
+}
+
+/**
+ * Get trust history for all features
+ * @returns {Array} Feature trust summaries
+ */
+export function getTrustHistory() {
+  const state = loadState();
+  const features = state.features || {};
+
+  return Object.entries(features).map(([name, feature]) => {
+    const trust = getTrust(name);
+    return {
+      feature: name,
+      level: trust.level,
+      passRate: trust.passRate,
+      checkpointsTotal: trust.total || 0,
+      checkpointsPassed: trust.passed || 0,
+      autoApprove: trust.autoApprove,
+      source: trust.source,
+      phase: feature.phase,
+      status: feature.status
+    };
+  });
+}
+
+/**
+ * Auto-calculate and update trust in state
+ * @param {string} featureName
+ * @returns {Object} Updated trust config
+ */
+export function autoCalculateTrust(featureName) {
+  const state = loadState();
+  const feature = state.features?.[featureName];
+
+  if (!feature) {
+    throw new Error(`Feature not found: ${featureName}`);
+  }
+
+  const checkpoints = feature.checkpoints || [];
+  const { level, passRate, total, passed } = calculateTrust(checkpoints);
+
+  if (!state.features[featureName].trustConfig) {
+    state.features[featureName].trustConfig = {};
+  }
+
+  state.features[featureName].trustConfig = {
+    ...state.features[featureName].trustConfig,
+    level,
+    passRate,
+    checkpointsTotal: total,
+    checkpointsPassed: passed,
+    lastCalculated: new Date().toISOString()
+  };
+
+  saveState(state);
+
+  return {
+    feature: featureName,
+    level,
+    passRate,
+    total,
+    passed,
+    autoApprove: AUTO_APPROVE_GATES[level] || []
+  };
+}
+
+export { TRUST_THRESHOLDS, AUTO_APPROVE_GATES };

package/src/lib/validators/design-system/design-system-validator.js

@@ -9,8 +9,8 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
 import { join, extname } from 'path';
-import { parseColors, parseTypography, parseSpacing } from '../design-system-generator.js';
-import { detectDesignSystem } from '../design-system-detector.js';
+import { parseColors, parseTypography, parseSpacing } from '../../generators/design-system-generator.js';
+import { detectDesignSystem } from '../../detectors/design-system-detector.js';
 
 /**
  * Validate design system compliance

package/src/lib/validators/validation-runner.js

@@ -10,7 +10,7 @@
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import chalk from 'chalk';
-import { loadState } from './state-manager.js';
+import { loadState } from '../../core/state/state-manager.js';
 import { resolveAgentsConfigPath } from '../stacks/stack-resolver.js';
 
 /**
@@ -172,63 +172,47 @@ function detectValidators(featureName, projectPath = '.') {
 async function runSingleValidator(validatorId, projectPath, featureName, options) {
   switch (validatorId) {
     case 'architecture': {
-      const { validateArchitecture } = await import('./validators/architecture-validator.js');
+      const { validateArchitecture } = await import('./architecture/architecture-validator.js');
       return await validateArchitecture(projectPath, options);
     }
 
     case 'packages': {
-      const { validatePackages } = await import('./validators/package-validator.js');
+      const { validatePackages } = await import('./packages/package-validator.js');
       return await validatePackages(projectPath, options);
     }
 
     case 'contrast': {
-      const { validateContrast } = await import('./validators/ui-contrast-validator.js');
+      const { validateContrast } = await import('./ui/ui-contrast-validator.js');
       return await validateContrast(projectPath, options);
     }
 
     case 'blazor': {
-      try {
-        const { validateBlazorPatterns } = await import('./blazor-validator.js');
-        return await validateBlazorPatterns(projectPath, options);
-      } catch {
-        return null; // Validator may not exist or have different export
-      }
+      const { validateBlazorPatterns } = await import('./blazor/blazor-validator.js');
+      return await validateBlazorPatterns(projectPath, options);
     }
 
     case 'blazor-concurrency': {
-      try {
-        const { analyzeConcurrency } = await import('./blazor-concurrency-analyzer.js');
-        return await analyzeConcurrency(projectPath, options);
-      } catch {
-        return null;
-      }
+      const { analyzeConcurrency } = await import('./blazor/blazor-concurrency-analyzer.js');
+      return await analyzeConcurrency(projectPath, options);
     }
 
     case 'blazor-state': {
-      try {
-        const { validateState } = await import('./blazor-state-validator.js');
-        return await validateState(projectPath, options);
-      } catch {
-        return null;
-      }
+      const { validateState } = await import('./blazor/blazor-state-validator.js');
+      return await validateState(projectPath, options);
     }
 
     case 'css': {
-      try {
-        const { validateCss } = await import('./css-validator.js');
-        return await validateCss(projectPath, options);
-      } catch {
-        return null;
-      }
+      const { validateCss } = await import('./css/css-validator.js');
+      return await validateCss(projectPath, options);
     }
 
     case 'contract-compliance': {
-      const { validateContracts } = await import('./validators/contract-compliance-validator.js');
+      const { validateContracts } = await import('./contracts/contract-compliance-validator.js');
       return await validateContracts(projectPath, featureName, options);
     }
 
     case 'design-system': {
-      const { validateDesignSystem } = await import('./validators/design-system-validator.js');
+      const { validateDesignSystem } = await import('./design-system/design-system-validator.js');
       return await validateDesignSystem(projectPath, featureName, options);
     }
 

package/src/utils/hooks-installer.js

@@ -0,0 +1,69 @@
+/**
+ * Claude Code Hooks Installer
+ *
+ * Merges the MORPH-SPEC agent-teams PostToolUse hook into
+ * .claude/settings.local.json without overwriting existing config.
+ *
+ * Called by `morph-spec init` and `morph-spec update`.
+ */
+
+import { join } from 'path';
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { existsSync } from 'fs';
+
+const DISPATCH_COMMAND = 'node framework/hooks/agent-teams/dispatch.js';
+
+/**
+ * Install or update the MORPH-SPEC PostToolUse hook in .claude/settings.local.json.
+ *
+ * @param {string} targetPath - Project root directory
+ * @returns {boolean} true if the hook was newly added, false if it was already present
+ */
+export async function installClaudeHooks(targetPath) {
+  const claudeDir = join(targetPath, '.claude');
+  const settingsPath = join(claudeDir, 'settings.local.json');
+
+  // Read existing settings or start empty
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(await readFile(settingsPath, 'utf-8'));
+    } catch {
+      // Malformed JSON — start fresh to avoid corrupting the file
+      settings = {};
+    }
+  }
+
+  // Ensure hooks.PostToolUse array exists
+  settings.hooks = settings.hooks || {};
+  settings.hooks.PostToolUse = settings.hooks.PostToolUse || [];
+
+  // Check if dispatch.js is already registered (avoid duplicate entries)
+  const alreadyRegistered = settings.hooks.PostToolUse.some(entry =>
+    Array.isArray(entry.hooks) &&
+    entry.hooks.some(h => h.command === DISPATCH_COMMAND)
+  );
+
+  if (alreadyRegistered) {
+    return false;
+  }
+
+  // Add the agent-teams dispatch hook
+  settings.hooks.PostToolUse.push({
+    matcher: 'Bash',
+    hooks: [
+      {
+        type: 'command',
+        command: DISPATCH_COMMAND
+      }
+    ]
+  });
+
+  // Ensure .claude directory exists
+  if (!existsSync(claudeDir)) {
+    await mkdir(claudeDir, { recursive: true });
+  }
+
+  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+  return true;
+}