@polymorphism-tech/morph-spec 4.10.6 → 4.10.8

package/package.json

@@ -1,82 +1,82 @@
-{
-  "name": "@polymorphism-tech/morph-spec",
-  "version": "4.10.6",
-  "description": "MORPH-SPEC: AI-First development framework with validation pipeline and multi-stack support",
-  "keywords": [
-    "claude-code",
-    "claude",
-    "ai-coding",
-    "ai-first",
-    "spec-driven",
-    "dotnet",
-    "dotnet10",
-    "blazor",
-    "agent-framework",
-    "fluent-ui",
-    "framework",
-    "developer-tools",
-    "morph",
-    "polymorphism",
-    "micro-saas"
-  ],
-  "main": "src/index.js",
-  "bin": {
-    "morph-spec": "bin/morph-spec.js"
-  },
-  "files": [
-    "bin/",
-    "src/",
-    "framework/",
-    "claude-plugin.json",
-    "docs/QUICKSTART.md",
-    "docs/CHEATSHEET.md",
-    "README.md",
-    "LICENSE",
-    "CLAUDE.md"
-  ],
-  "type": "module",
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "scripts": {
-    "start": "node bin/morph-spec.js",
-    "generate": "node scripts/generate-refs.js",
-    "test": "node --test --test-concurrency=1",
-    "test:coverage": "c8 --reporter=text --reporter=html --reporter=lcov node --test --test-concurrency=1",
-    "test:coverage:summary": "c8 --reporter=text-summary node --test --test-concurrency=1",
-    "docs": "jsdoc -c jsdoc.json",
-    "docs:watch": "jsdoc -c jsdoc.json --watch",
-    "docs:serve": "npx http-server docs/api -p 8080 -o",
-    "release": "node scripts/release.js",
-    "postinstall": "node src/scripts/global-install.js"
-  },
-  "dependencies": {
-    "chalk": "^5.3.0",
-    "commander": "^12.0.0",
-    "fs-extra": "^11.2.0",
-    "glob": "^13.0.6",
-    "handlebars": "^4.7.8",
-    "inquirer": "^9.2.0",
-    "minimatch": "^9.0.5",
-    "ora": "^8.0.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/lucasPolymorphism/morph-spec-framework.git"
-  },
-  "author": "Polymorphism Tech <contact@polymorphism.com.br>",
-  "license": "SEE LICENSE IN LICENSE",
-  "homepage": "https://polymorphism.com.br/morph-spec",
-  "bugs": {
-    "email": "support@polymorphism.com.br"
-  },
-  "private": false,
-  "publishConfig": {
-    "access": "public"
-  },
-  "devDependencies": {
-    "c8": "^11.0.0",
-    "docdash": "^2.0.2",
-    "jsdoc": "^4.0.5"
-  }
-}
+{
+  "name": "@polymorphism-tech/morph-spec",
+  "version": "4.10.8",
+  "description": "MORPH-SPEC: AI-First development framework with validation pipeline and multi-stack support",
+  "keywords": [
+    "claude-code",
+    "claude",
+    "ai-coding",
+    "ai-first",
+    "spec-driven",
+    "dotnet",
+    "dotnet10",
+    "blazor",
+    "agent-framework",
+    "fluent-ui",
+    "framework",
+    "developer-tools",
+    "morph",
+    "polymorphism",
+    "micro-saas"
+  ],
+  "main": "src/index.js",
+  "bin": {
+    "morph-spec": "bin/morph-spec.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "framework/",
+    "claude-plugin.json",
+    "docs/QUICKSTART.md",
+    "docs/CHEATSHEET.md",
+    "README.md",
+    "LICENSE",
+    "CLAUDE.md"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "start": "node bin/morph-spec.js",
+    "generate": "node scripts/generate-refs.js",
+    "test": "node --test --test-concurrency=1",
+    "test:coverage": "c8 --reporter=text --reporter=html --reporter=lcov node --test --test-concurrency=1",
+    "test:coverage:summary": "c8 --reporter=text-summary node --test --test-concurrency=1",
+    "docs": "jsdoc -c jsdoc.json",
+    "docs:watch": "jsdoc -c jsdoc.json --watch",
+    "docs:serve": "npx http-server docs/api -p 8080 -o",
+    "release": "node scripts/release.js",
+    "postinstall": "node src/scripts/global-install.js"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "fs-extra": "^11.2.0",
+    "glob": "^13.0.6",
+    "handlebars": "^4.7.8",
+    "inquirer": "^9.2.0",
+    "minimatch": "^9.0.5",
+    "ora": "^8.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lucasPolymorphism/morph-spec-framework.git"
+  },
+  "author": "Polymorphism Tech <contact@polymorphism.com.br>",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://polymorphism.com.br/morph-spec",
+  "bugs": {
+    "email": "support@polymorphism.com.br"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "c8": "^11.0.0",
+    "docdash": "^2.0.2",
+    "jsdoc": "^4.0.5"
+  }
+}

package/src/commands/agents/agent-metrics.js

@@ -0,0 +1,174 @@
+/**
+ * agent-metrics — Display agent performance metrics for a feature
+ *
+ * Reads dispatchLog from state.json, computes per-agent metrics
+ * (dispatch count, task coverage, completion rate, avg duration),
+ * and renders a table or JSON output.
+ *
+ * Usage:
+ *   morph-spec agent-metrics <feature>
+ *   morph-spec agent-metrics <feature> --json
+ *   morph-spec agent-metrics --all
+ */
+
+import { loadState, stateExists } from '../../core/state/state-manager.js';
+import { calculateMetrics, calculateAggregatedMetrics, formatDuration } from '../../lib/agents/metrics-calculator.js';
+import chalk from 'chalk';
+
+/**
+ * CLI command: morph-spec agent-metrics [feature]
+ *
+ * @param {string} [featureName] - Feature name (required unless --all)
+ * @param {Object} [options] - CLI options
+ * @param {boolean} [options.json] - Output as JSON instead of table
+ * @param {boolean} [options.all] - Aggregate metrics across all features
+ */
+export async function agentMetricsCommand(featureName, options = {}) {
+  if (!options.all && !featureName) {
+    console.error(chalk.red('Usage: morph-spec agent-metrics <feature> [--json] [--all]'));
+    process.exit(1);
+  }
+
+  if (!stateExists()) {
+    console.error(chalk.red('No state.json found.'));
+    process.exit(1);
+  }
+
+  const state = loadState();
+
+  if (options.all) {
+    return renderAggregated(state.features || {}, options);
+  }
+
+  const feature = state.features?.[featureName];
+  if (!feature) {
+    console.error(chalk.red(`Feature '${featureName}' not found.`));
+    process.exit(1);
+  }
+
+  const log = feature.dispatchLog || [];
+  if (log.length === 0) {
+    console.log(chalk.gray('\n  No dispatch events recorded.\n'));
+    return;
+  }
+
+  const result = calculateMetrics(log);
+  result.feature = featureName;
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  renderTable(featureName, result);
+}
+
+/**
+ * Render per-feature metrics table.
+ */
+function renderTable(featureName, result) {
+  const { agents, summary } = result;
+
+  console.log(chalk.bold(`\n  Agent Performance \u2014 ${featureName}`));
+  console.log('  ' + '\u2500'.repeat(70));
+
+  // Header
+  console.log(
+    '  ' +
+    pad('Agent', 28) +
+    pad('Dispatches', 12) +
+    pad('Tasks', 8) +
+    pad('Completed', 12) +
+    pad('Avg Duration', 14)
+  );
+  console.log('  ' + '\u2500'.repeat(70));
+
+  for (const agent of agents) {
+    const tasks = agent.tasksAssigned > 0 ? String(agent.tasksAssigned) : '\u2014';
+    const completed = agent.tasksAssigned > 0
+      ? `${agent.tasksCompleted}/${agent.tasksAssigned}`
+      : '\u2014';
+    const duration = formatDuration(agent.avgDurationMs);
+
+    console.log(
+      '  ' +
+      pad(agent.id, 28) +
+      pad(String(agent.dispatches), 12) +
+      pad(tasks, 8) +
+      pad(completed, 12) +
+      pad(duration, 14)
+    );
+  }
+
+  console.log();
+  const rate = summary.totalTasks > 0
+    ? `${Math.round(summary.completionRate * 100)}%`
+    : '0%';
+  console.log(`  Summary: ${summary.completedTasks} tasks completed of ${summary.totalTasks} (${rate}), avg ${formatDuration(summary.avgTaskDurationMs)}/task`);
+  console.log(`  Dispatches: ${summary.totalDispatches} total`);
+  console.log();
+}
+
+/**
+ * Render aggregated metrics across all features.
+ */
+function renderAggregated(features, options) {
+  const featureNames = Object.keys(features);
+  if (featureNames.length === 0) {
+    console.log(chalk.gray('\n  No features found.\n'));
+    return;
+  }
+
+  const result = calculateAggregatedMetrics(features);
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(chalk.bold(`\n  Agent Performance \u2014 All Features (${result.featureCount})`));
+  console.log('  ' + '\u2500'.repeat(70));
+
+  console.log(
+    '  ' +
+    pad('Agent', 28) +
+    pad('Dispatches', 12) +
+    pad('Tasks', 8) +
+    pad('Completed', 12) +
+    pad('Avg Duration', 14)
+  );
+  console.log('  ' + '\u2500'.repeat(70));
+
+  for (const agent of result.agents) {
+    const tasks = agent.tasksAssigned > 0 ? String(agent.tasksAssigned) : '\u2014';
+    const completed = agent.tasksAssigned > 0
+      ? `${agent.tasksCompleted}/${agent.tasksAssigned}`
+      : '\u2014';
+    const duration = formatDuration(agent.avgDurationMs);
+
+    console.log(
+      '  ' +
+      pad(agent.id, 28) +
+      pad(String(agent.dispatches), 12) +
+      pad(tasks, 8) +
+      pad(completed, 12) +
+      pad(duration, 14)
+    );
+  }
+
+  console.log();
+  const { summary } = result;
+  const rate = summary.totalTasks > 0
+    ? `${Math.round(summary.completionRate * 100)}%`
+    : '0%';
+  console.log(`  Summary: ${summary.completedTasks} tasks completed of ${summary.totalTasks} (${rate}), avg ${formatDuration(summary.avgTaskDurationMs)}/task`);
+  console.log(`  Dispatches: ${summary.totalDispatches} total across ${result.featureCount} features`);
+  console.log();
+}
+
+/**
+ * Right-pad a string to a given width.
+ */
+function pad(str, width) {
+  return str.length >= width ? str : str + ' '.repeat(width - str.length);
+}

package/src/commands/agents/audit-dispatch.js

@@ -0,0 +1,82 @@
+/**
+ * audit-dispatch — Display dispatch audit log for a feature
+ *
+ * Reads dispatchLog from state.json and presents a summary:
+ * - Total dispatches
+ * - Per-dispatch: timestamp, phase, mode, agents with subagentTypes
+ * - Agent coverage: which agents handled which tasks
+ *
+ * Usage:
+ *   morph-spec audit-dispatch <feature>
+ *   morph-spec audit-dispatch <feature> --json
+ */
+
+import { loadState, stateExists } from '../../core/state/state-manager.js';
+import chalk from 'chalk';
+
+/**
+ * CLI command: morph-spec audit-dispatch <feature>
+ *
+ * @param {string} featureName - Feature name
+ * @param {Object} [options] - CLI options
+ * @param {boolean} [options.json] - Output as JSON instead of table
+ */
+export async function auditDispatchCommand(featureName, options = {}) {
+  if (!featureName) {
+    console.error(chalk.red('Usage: morph-spec audit-dispatch <feature>'));
+    process.exit(1);
+  }
+
+  if (!stateExists()) {
+    console.error(chalk.red('No state.json found.'));
+    process.exit(1);
+  }
+
+  const state = loadState();
+  const feature = state.features?.[featureName];
+  if (!feature) {
+    console.error(chalk.red(`Feature '${featureName}' not found.`));
+    process.exit(1);
+  }
+
+  const log = feature.dispatchLog || [];
+
+  if (options.json) {
+    console.log(JSON.stringify(log, null, 2));
+    return;
+  }
+
+  console.log(chalk.bold(`\n  Dispatch Audit — ${featureName}`));
+  console.log('  ' + '─'.repeat(50));
+  console.log(`  Total dispatches: ${log.length}`);
+
+  if (log.length === 0) {
+    console.log(chalk.gray('\n  No dispatch events recorded.\n'));
+    return;
+  }
+
+  for (let i = 0; i < log.length; i++) {
+    const entry = log[i];
+    console.log(`\n  #${i + 1}: ${entry.timestamp} — ${entry.phase} (${entry.mode})`);
+    for (const agent of entry.agents || []) {
+      const taskCount = agent.tasks?.length || 0;
+      console.log(`      ${agent.id} → ${agent.subagentType} (${agent.group}) — ${taskCount} tasks`);
+    }
+  }
+
+  // Agent coverage summary
+  const coverage = {};
+  for (const entry of log) {
+    for (const agent of entry.agents || []) {
+      if (!coverage[agent.id]) coverage[agent.id] = { tasks: 0, dispatches: 0 };
+      coverage[agent.id].tasks += agent.tasks?.length || 0;
+      coverage[agent.id].dispatches += 1;
+    }
+  }
+
+  console.log(chalk.bold('\n  Agent Coverage:'));
+  for (const [id, data] of Object.entries(coverage)) {
+    console.log(`      ${id}: ${data.tasks} tasks across ${data.dispatches} dispatches`);
+  }
+  console.log();
+}

package/src/commands/agents/detect-agents.js

@@ -0,0 +1,275 @@
+/**
+ * detect-agents — Detect relevant agents for a feature based on keywords
+ *
+ * Supports single string input (legacy) and multi-source TextSource[] input
+ * with weighted keyword scoring. Also provides refreshAgents() for additive
+ * agent detection at phase boundaries.
+ *
+ * Usage:
+ *   morph-spec detect-agents <feature> [--proposal <path>] [--refresh] [--json] [--table]
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import chalk from 'chalk';
+import { collectPhaseOutputs } from '../../lib/agents/output-collector.js';
+import { loadAgentsFile } from '../../lib/agents/agents-manager.js';
+import { loadState, saveState, addAgent } from '../../core/state/state-manager.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Default path to agents.json in the installed package */
+const AGENTS_JSON_PATH = join(__dirname, '../../../framework/agents.json');
+
+/** Match weight constants */
+const MATCH_WEIGHTS = {
+  heading: 3,
+  body: 1,
+  domain: 2,
+};
+
+/**
+ * Detect agents relevant to a feature.
+ *
+ * @param {string|Array<{source: string, content: string, weight: number}>} sourcesOrText - Text sources or legacy string
+ * @param {Object} agentsJson - Parsed agents.json content
+ * @param {Object} [opts] - Options
+ * @param {string[]} [opts.excludeIds] - Agent IDs to exclude from detection
+ * @returns {{ detected: Array<{id: string, reason: string, keywords_matched: string[], score: number, sources: Array}>, skipped: Array<{id: string, reason: string}> }}
+ */
+export function detectAgents(sourcesOrText, agentsJson, opts = {}) {
+  // Backward compatibility: wrap string as single source
+  const sources = typeof sourcesOrText === 'string'
+    ? [{ source: 'proposal.md', content: sourcesOrText, weight: 1.0 }]
+    : sourcesOrText;
+
+  const allAgents = agentsJson.agents || {};
+  const excludeIds = new Set(opts.excludeIds || []);
+
+  const detected = [];
+  const skipped = [];
+
+  for (const [agentId, agentData] of Object.entries(allAgents)) {
+    if (excludeIds.has(agentId)) continue;
+    if (!agentData || typeof agentData !== 'object' || !agentData.tier) continue;
+
+    // Always-active agents (active_phases includes '*')
+    if (Array.isArray(agentData.active_phases) && agentData.active_phases.includes('*')) {
+      detected.push({
+        id: agentId,
+        reason: 'active_phases: *',
+        keywords_matched: [],
+        score: 0,
+        sources: [],
+      });
+      continue;
+    }
+
+    // Score across all sources
+    const keywords = agentData.keywords || [];
+    const domains = agentData.domains || [];
+    let totalScore = 0;
+    const allMatched = new Set();
+    const sourceBreakdown = [];
+
+    for (const src of sources) {
+      const textLower = src.content.toLowerCase();
+      const lines = src.content.split('\n');
+      let srcScore = 0;
+      const srcKeywords = [];
+
+      // Check keywords
+      for (const kw of keywords) {
+        const kwLower = kw.toLowerCase();
+        if (!textLower.includes(kwLower)) continue;
+
+        allMatched.add(kw);
+        srcKeywords.push(kw);
+
+        // Check if keyword appears in a heading line
+        const inHeading = lines.some(line =>
+          /^#{1,6}\s/.test(line) && line.toLowerCase().includes(kwLower)
+        );
+        srcScore += (inHeading ? MATCH_WEIGHTS.heading : MATCH_WEIGHTS.body) * src.weight;
+      }
+
+      // Check domains
+      for (const domain of domains) {
+        const domLower = domain.toLowerCase();
+        if (!textLower.includes(domLower)) continue;
+
+        allMatched.add(domain);
+        srcKeywords.push(domain);
+        srcScore += MATCH_WEIGHTS.domain * src.weight;
+      }
+
+      if (srcScore > 0) {
+        sourceBreakdown.push({
+          source: src.source,
+          keywords: srcKeywords,
+          score: srcScore,
+        });
+        totalScore += srcScore;
+      }
+    }
+
+    if (totalScore > 0) {
+      detected.push({
+        id: agentId,
+        reason: 'keyword',
+        keywords_matched: [...allMatched],
+        score: totalScore,
+        sources: sourceBreakdown,
+      });
+    } else {
+      skipped.push({
+        id: agentId,
+        reason: 'no_keyword_match',
+      });
+    }
+  }
+
+  return { detected, skipped };
+}
+
+/**
+ * Refresh agent detection using all available phase outputs.
+ * Additive only — never removes existing agents.
+ *
+ * @param {string} projectRoot - Absolute path
+ * @param {string} featureName - Feature name
+ * @returns {Promise<{added: Array, unchanged: number, total: number}>}
+ */
+export async function refreshAgents(projectRoot, featureName) {
+  const state = loadState(false);
+  const feature = state?.features?.[featureName];
+  if (!feature) {
+    return { added: [], unchanged: 0, total: 0 };
+  }
+
+  const currentAgents = new Set(feature.activeAgents || []);
+
+  const sources = collectPhaseOutputs(projectRoot, featureName);
+  if (sources.length === 0) {
+    return { added: [], unchanged: currentAgents.size, total: currentAgents.size };
+  }
+
+  let agentsJson;
+  try {
+    agentsJson = loadAgentsFile(AGENTS_JSON_PATH);
+  } catch {
+    return { added: [], unchanged: currentAgents.size, total: currentAgents.size };
+  }
+  const { detected } = detectAgents(sources, agentsJson);
+
+  const added = detected.filter(a => !currentAgents.has(a.id));
+
+  // Additive: add new agents to state
+  for (const agent of added) {
+    await addAgent(featureName, agent.id);
+  }
+
+  return {
+    added,
+    unchanged: currentAgents.size,
+    total: currentAgents.size + added.length,
+  };
+}
+
+/**
+ * Display detection diff after refresh.
+ *
+ * @param {{added: Array, unchanged: number, total: number}} result
+ * @param {string} fromPhase
+ * @param {string} toPhase
+ */
+export function displayDetectionDiff(result, fromPhase, toPhase) {
+  console.log(chalk.cyan(`\nAgent Detection Refresh (${fromPhase} \u2192 ${toPhase}):`));
+
+  for (const agent of result.added) {
+    const kws = agent.keywords_matched.join('", "');
+    console.log(chalk.green(`  + ${agent.id.padEnd(24)} (keyword: "${kws}" | score: ${agent.score})`));
+  }
+
+  console.log(chalk.gray(`  = ${result.unchanged} agents unchanged`));
+  console.log(chalk.white(`  Total: ${result.total} active agents\n`));
+}
+
+/**
+ * CLI command: morph-spec detect-agents <feature>
+ */
+export async function detectAgentsCommand(featureName, options = {}) {
+  if (!featureName) {
+    console.error(chalk.red('Usage: morph-spec detect-agents <feature> [--proposal <path>] [--refresh] [--json] [--table]'));
+    process.exit(1);
+  }
+
+  // --refresh mode: use all phase outputs and mutate state
+  if (options.refresh) {
+    const result = await refreshAgents(process.cwd(), featureName);
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      displayDetectionDiff(result, 'manual', 'refresh');
+    }
+    return;
+  }
+
+  // Resolve proposal path
+  const proposalPath = options.proposal
+    || join(process.cwd(), `.morph/features/${featureName}/0-proposal/proposal.md`);
+
+  if (!existsSync(proposalPath)) {
+    console.error(chalk.red(`Proposal not found: ${proposalPath}`));
+    console.error(chalk.gray('Create the proposal first or use --proposal <path> to specify a custom path.'));
+    process.exit(1);
+  }
+
+  // Load agents.json
+  const agentsPath = options.agentsJson || AGENTS_JSON_PATH;
+  let agentsJson;
+  try {
+    agentsJson = loadAgentsFile(agentsPath);
+  } catch (err) {
+    console.error(chalk.red(err.message));
+    process.exit(1);
+  }
+
+  const proposalText = readFileSync(proposalPath, 'utf8');
+
+  const result = detectAgents(proposalText, agentsJson, {
+    excludeIds: options.exclude ? options.exclude.split(',') : [],
+  });
+
+  const output = {
+    feature: featureName,
+    ...result,
+  };
+
+  if (options.table) {
+    // Human-readable table
+    console.log(chalk.bold(`\n  Detected Agents \u2014 ${featureName}`));
+    console.log('  ' + '\u2500'.repeat(62));
+
+    if (result.detected.length > 0) {
+      console.log(`  ${'ID'.padEnd(28)} ${'Reason'.padEnd(16)} Keywords`);
+      console.log('  ' + '\u2500'.repeat(62));
+      for (const agent of result.detected) {
+        const reason = agent.reason === 'active_phases: *' ? 'always' : agent.reason;
+        const kw = agent.keywords_matched.length > 0 ? agent.keywords_matched.join(', ') : '\u2014';
+        console.log(
+          `  ${agent.id.padEnd(28)} ${chalk.cyan(reason.padEnd(16))} ${kw}`
+        );
+      }
+    } else {
+      console.log(chalk.gray('  No agents detected.'));
+    }
+
+    console.log(`\n  Skipped: ${result.skipped.length} agents (no keyword match)`);
+    console.log();
+  } else {
+    // JSON output (default)
+    console.log(JSON.stringify(output, null, 2));
+  }
+}