@polymorphism-tech/morph-spec 4.3.0 → 4.3.2

package/CLAUDE.md

@@ -0,0 +1,155 @@
+# MORPH-SPEC - Claude Code Instructions
+
+> by Polymorphism Tech
+
+Spec-driven development system. Specialized agent hub for multi-stack projects with Infrastructure as Code.
+
+---
+
+## CRITICAL RULES
+
+### NEVER:
+- Skip to code without a specification
+- Implement without design approval
+- Ignore standards in `.morph/standards/`
+- Create infrastructure manually
+- Generate code without defined contracts
+
+### ALWAYS:
+- Follow the 5 mandatory phases
+- Generate outputs in `.morph/project/outputs/{feature}/`
+- Document decisions in `decisions.md`
+- Checkpoint every 3 implemented tasks
+- Use Infrastructure as Code
+
+---
+
+## WORKFLOW (5 Phases)
+
+| Phase | Trigger | Actions | Output | Pause? |
+|-------|---------|---------|--------|--------|
+| **1. SETUP** | Feature request | Read project context, identify stack, activate agents, create folder | proposal.md | No |
+| **2. DESIGN** | Setup done | Spec + contracts + decisions + costs | spec.md, contracts, decisions.md | **Yes** |
+| **3. CLARIFY** | Design approved | Ambiguities, questions, edge cases | Updated spec | No |
+| **4. TASKS** | Clarifications resolved | Break into tasks, ordering, checkpoints, dependencies | tasks.md | **Yes** |
+| **5. IMPLEMENT** | Tasks approved | Task by task, checkpoint every 3, recap | Code + recap.md | No |
+
+---
+
+## PROJECT STRUCTURE
+
+```
+project/
+├── CLAUDE.md
+├── .morph/
+│   ├── config/                     # config.json, agents.json
+│   ├── standards/                  # coding, architecture, stack-specific
+│   ├── templates/                  # Output templates
+│   ├── project/
+│   │   ├── context/                # detection-log.md, project.md
+│   │   ├── standards/              # inferred.md, overrides.md
+│   │   └── outputs/{feature}/     # Features in development
+│   │       ├── proposal.md, spec.md, tasks.md
+│   │       ├── contracts, decisions.md, recap.md
+└── .claude/commands/               # Slash commands
+```
+
+---
+
+## AGENTS
+
+### Tier 1 — Orchestrators (Always Active)
+
+| Agent | Responsibilities |
+|-------|-----------------|
+| **Standards Architect** | Standards, naming, review, cross-cutting concerns |
+| **AI System Architect** | Agent systems, AI integrations, LLM orchestration |
+| **Thread Orchestrator** | Parallel execution, thread management, context optimization |
+
+### Tier 2 — Domain Leaders
+
+| Agent | Responsibilities |
+|-------|-----------------|
+| **Tech Lead** | Architecture decisions, code quality, task breakdown |
+| **DevOps Engineer** | CI/CD, deployment pipelines, infrastructure |
+| **QA Lead** | Test strategies, validation, quality gates |
+
+### Tier 3 — Specialists (Activated by keywords)
+
+| Agent | Keywords |
+|-------|---------|
+| **Next.js Expert** | nextjs, react, frontend, app router, pages |
+| **Blazor Builder** | blazor, razor, mudblazor, fluent ui |
+| **API Designer** | api, endpoint, rest, openapi, swagger |
+| **.NET Senior** | dotnet, csharp, minimal api, ef core |
+| **EF Modeler** | entity framework, migrations, dbcontext |
+| **Azure Architect** | azure, container apps, bicep, app service |
+| **Bicep Architect** | bicep, iac, arm template, azure resources |
+| **Azure Deploy Specialist** | deploy, ci/cd, github actions, azure devops |
+| **Container Specialist** | docker, dockerfile, compose, kubernetes |
+| **Supabase Expert** | supabase, postgresql, rls, realtime, pgvector |
+| **Azure Identity** | auth, authentication, entra id, jwt, oauth |
+| **Clerk Auth** | clerk, auth0, authentication, social login |
+| **Asaas Financial** | payment, billing, subscription, asaas |
+| **Resend Email** | email, resend, smtp, notifications |
+| **Hangfire Orchestrator** | background jobs, queue, scheduling, hangfire |
+| **MS Agent Expert** | semantic kernel, microsoft agents, ai pipeline |
+| **UI/UX Designer** | design, ux, wireframe, mockup, figma |
+| **SEO Growth Hacker** | seo, performance, analytics, lighthouse |
+| **PO/PM Advisor** | product, roadmap, requirements, user stories |
+| **Prompt Engineer** | prompts, system prompts, llm, few-shot |
+| **Context Optimizer** | context window, token optimization, chunking |
+| **Vector Search Expert** | vector db, embeddings, semantic search, rag |
+| **Observability Expert** | logging, tracing, metrics, opentelemetry |
+| **Code Analyzer** | refactor, analysis, code review, complexity |
+| **Testing Specialist** | tests, coverage, tdd, bdd, vitest, jest, xunit |
+
+### Tier 4 — Validators
+
+| Agent | Responsibilities |
+|-------|-----------------|
+| **Contract Compliance Validator** | Ensures implementation matches spec contracts |
+
+---
+
+## TEMPLATES
+
+> ALWAYS use `morph-spec template render` to render. NEVER fill placeholders manually.
+
+### Placeholders: `{{PLACEHOLDER}}`
+
+| Placeholder | Example |
+|-------------|---------|
+| `{{FEATURE_NAME}}` | `scheduled-reports` |
+| `{{FEATURE_NAME_PASCAL}}` | `ScheduledReports` |
+| `{{FEATURE_NAME_CAMEL}}` | `scheduledReports` |
+| `{{STACK}}` | `blazor-azure` or `nextjs-supabase` |
+| `{{DATE}}`, `{{AUTHOR}}`, `{{NAMESPACE}}` | Auto from config.json |
+
+---
+
+## COMMANDS
+
+| Command | Action |
+|---------|--------|
+| `/morph-proposal {feature}` | Full spec pipeline (phases 1-4, auto-continuation with pauses) |
+| `/morph-apply {feature}` | Implement feature (phase 5) |
+| `/morph-status` | Dashboard |
+| `/morph-archive {feature}` | Archive completed feature |
+| `/morph-infra {action}` | Manage infrastructure |
+| `/morph-preflight` | Pre-deploy validation |
+| `/morph-troubleshoot {error}` | Error troubleshooting |
+
+---
+
+## REFERENCES
+
+- `.morph/config/config.json` — Project configuration
+- `.morph/config/agents.json` — Full agent definitions
+- `.morph/standards/` — Coding, architecture, stack-specific standards
+- `.morph/project/context/` — Detection log, project context
+- `.morph/project/standards/inferred.md` — Auto-detected project standards
+
+---
+
+*MORPH-SPEC v4.3.0 by Polymorphism Tech*

package/bin/morph-spec.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 import { program } from 'commander';
 import chalk from 'chalk';
@@ -141,7 +141,7 @@ program
 program
   .command('doctor')
   .description('Check MORPH installation health')
-  .option('--v3', 'Run v3.0 specific checks (lib files, HOPs, standards, agents, migration status)')
+  .option('--full', 'Run full health check (lib files, commands, HOPs, standards, agents, state)')
   .action(doctorCommand);
 
 program
@@ -256,7 +256,7 @@ generateCommand
   .description('Auto-generate recap.md from project data (state, validation, contracts)')
   .option('--quiet', 'Suppress output')
   .action(async (feature, options) => {
-    const { generateRecap } = await import('../src/lib/recap-generator.js');
+    const { generateRecap } = await import('../src/lib/generators/recap-generator.js');
     await generateRecap('.', feature, options);
   });
 

package/bin/task-manager.cjs

@@ -8,6 +8,7 @@
  */
 
 const fs = require('fs').promises;
+const fsSync = require('fs');
 const path = require('path');
 
 // Simple ANSI color helpers (chalk v5 is ESM-only, can't require in CJS)
@@ -22,6 +23,68 @@ const chalk = {
   bold: (s) => `\x1b[1m${s}\x1b[0m`,
 };
 
+// ============================================================================
+// v3 Schema Helpers
+// ============================================================================
+
+/**
+ * Parse tasks.md to extract task stubs for v3 state format.
+ * Looks for headings like: ### T001 — Task title
+ */
+async function parseTasksMd(featureName) {
+  const tasksPath = path.join(process.cwd(), `.morph/project/outputs/${featureName}/tasks.md`);
+  let content = '';
+  try {
+    content = await fs.readFile(tasksPath, 'utf-8');
+  } catch {
+    return [];
+  }
+
+  const tasks = [];
+  const headingRe = /^###\s+(T\d+)\s+[—–-]\s+(.+)$/gm;
+  let match;
+  while ((match = headingRe.exec(content)) !== null) {
+    tasks.push({
+      id: match[1],
+      title: match[2].trim(),
+      status: 'pending',
+      dependencies: [],
+      files: [],
+      checkpoint: null
+    });
+  }
+  return tasks;
+}
+
+/**
+ * Ensure feature.taskList exists (array of individual task objects).
+ * In v3 state, feature.tasks is a counter object {total, completed, ...}.
+ * Individual task objects live in feature.taskList.
+ */
+async function ensureTaskList(feature, featureName) {
+  if (Array.isArray(feature.tasks)) {
+    // v2 format: tasks IS the array
+    return feature.tasks;
+  }
+  // v3 format: use taskList or build from tasks.md
+  if (!feature.taskList || feature.taskList.length === 0) {
+    feature.taskList = await parseTasksMd(featureName);
+  }
+  return feature.taskList;
+}
+
+/**
+ * After modifying taskList, sync counts back to feature.tasks counter.
+ */
+function syncCounters(feature) {
+  if (Array.isArray(feature.tasks)) return; // v2, nothing to sync
+  const list = feature.taskList || [];
+  feature.tasks.completed = list.filter(t => t.status === 'completed').length;
+  feature.tasks.inProgress = list.filter(t => t.status === 'in_progress').length;
+  feature.tasks.pending = list.filter(t => t.status === 'pending').length;
+  // Don't touch feature.tasks.total — it is the authoritative count
+}
+
 class TaskManager {
   constructor(statePath = '.morph/state.json') {
     this.statePath = statePath;
@@ -46,7 +109,12 @@ class TaskManager {
    * Save state.json
    */
   async saveState(state) {
-    state.project.updatedAt = new Date().toISOString();
+    // v3 state uses metadata.lastUpdated, v2 used project.updatedAt
+    if (state.metadata) {
+      state.metadata.lastUpdated = new Date().toISOString();
+    } else if (state.project) {
+      state.project.updatedAt = new Date().toISOString();
+    }
     await fs.writeFile(this.statePath, JSON.stringify(state, null, 2), 'utf-8');
   }
 
@@ -65,11 +133,12 @@ class TaskManager {
       throw new Error(`Feature '${featureName}' not found in state.json`);
     }
 
+    const taskList = await ensureTaskList(feature, featureName);
     const results = [];
     const tasksToComplete = [];
 
     for (const taskId of taskIds) {
-      const task = feature.tasks.find(t => t.id === taskId);
+      const task = taskList.find(t => t.id === taskId);
 
       if (!task) {
         console.error(chalk.red(`❌ Task ${taskId} not found`));
@@ -82,7 +151,7 @@ class TaskManager {
       }
 
       // Validate dependencies
-      const missingDeps = this.checkDependencies(task, feature.tasks);
+      const missingDeps = this.checkDependencies(task, taskList);
       if (missingDeps.length > 0) {
         console.error(chalk.red(`❌ Cannot complete ${taskId}: missing dependencies: ${missingDeps.join(', ')}`));
         continue;
@@ -118,11 +187,12 @@ class TaskManager {
       }
     }
 
-    // Update progress
-    feature.progress = this.calculateProgress(feature.tasks);
+    // Sync v3 counters then compute progress
+    syncCounters(feature);
+    feature.progress = this.calculateProgress(taskList);
 
     // Auto-checkpoint every 3 tasks
-    const recentCompleted = this.getRecentCompleted(feature.tasks, 3);
+    const recentCompleted = this.getRecentCompleted(taskList, 3);
     if (recentCompleted.length === 3) {
       const lastCheckpoint = feature.checkpoints[feature.checkpoints.length - 1];
       const shouldAutoCheckpoint = !lastCheckpoint ||
@@ -138,6 +208,21 @@ class TaskManager {
     // Save state
     await this.saveState(state);
 
+    // Run TaskCompleted agent-teams hook for each completed task (non-blocking)
+    for (const task of results) {
+      try {
+        const { executeHook, formatHookResults } = await import('../src/lib/hooks/hook-executor.js');
+        const hookResult = await executeHook(process.cwd(), featureName, 'TaskCompleted', {
+          taskId: task.id
+        });
+        if (!hookResult.passed && hookResult.errors.length > 0) {
+          console.log(formatHookResults(hookResult, 'TaskCompleted'));
+        }
+      } catch {
+        // Hook executor unavailable — non-blocking
+      }
+    }
+
     // Auto-generate metadata.json (for quick LLM access)
     await this.generateMetadata(featureName, feature);
 
@@ -145,7 +230,7 @@ class TaskManager {
     this.displayProgress(feature);
 
     // Suggest next task
-    const nextTask = this.getNextTask(feature.tasks);
+    const nextTask = this.getNextTask(taskList);
     if (nextTask) {
       console.log(chalk.cyan(`\n⏭️  Next: ${nextTask.id} - ${nextTask.title}`));
       if (nextTask.dependencies && nextTask.dependencies.length > 0) {
@@ -167,7 +252,7 @@ class TaskManager {
     try {
       console.log(chalk.cyan('\n🔍 Running code validation...'));
 
-      const { runValidation, formatValidationResults } = await import('../src/lib/validation-runner.js');
+      const { runValidation, formatValidationResults } = await import('../src/lib/validators/validation-runner.js');
       const result = await runValidation('.', featureName, { verbose: true });
 
       formatValidationResults(result);
@@ -243,7 +328,7 @@ class TaskManager {
 
     // Run checkpoint hooks (new enhanced validation system)
     try {
-      const { runCheckpointHooks, shouldRunCheckpoint } = await import('../src/lib/checkpoint-hooks.js');
+      const { runCheckpointHooks, shouldRunCheckpoint } = await import('../src/lib/checkpoints/checkpoint-hooks.js');
 
       if (shouldRunCheckpoint(tasksCompleted, 3)) {
         checkpointResult = await runCheckpointHooks(featureName, checkpointNum);
@@ -268,7 +353,7 @@ class TaskManager {
       // Fallback to old validation if checkpoint-hooks not available
       console.log(chalk.yellow('⚠️  Checkpoint hooks not available, using legacy validation'));
       try {
-        const { runValidation } = await import('../src/lib/validation-runner.js');
+        const { runValidation } = await import('../src/lib/validators/validation-runner.js');
         const result = await runValidation('.', featureName, { verbose: false });
         validationNote = result.passed
           ? ' | Validation: PASSED'
@@ -333,7 +418,7 @@ class TaskManager {
         return;
       }
 
-      const { extractFeatureMetadata } = await import('../src/lib/metadata-extractor.js');
+      const { extractFeatureMetadata } = await import('../src/lib/generators/metadata-extractor.js');
       const metadata = extractFeatureMetadata(feature);
 
       const outputPath = path.join(
@@ -410,7 +495,8 @@ class TaskManager {
       throw new Error(`Feature '${featureName}' not found`);
     }
 
-    const task = feature.tasks.find(t => t.id === taskId);
+    const taskList = await ensureTaskList(feature, featureName);
+    const task = taskList.find(t => t.id === taskId);
 
     if (!task) {
       throw new Error(`Task ${taskId} not found`);
@@ -422,13 +508,14 @@ class TaskManager {
     }
 
     // Validate dependencies
-    const missingDeps = this.checkDependencies(task, feature.tasks);
+    const missingDeps = this.checkDependencies(task, taskList);
     if (missingDeps.length > 0) {
       throw new Error(`Cannot start ${taskId}: missing dependencies: ${missingDeps.join(', ')}`);
     }
 
     task.status = 'in_progress';
     task.startedAt = new Date().toISOString();
+    syncCounters(feature);
 
     await this.saveState(state);
 
@@ -446,7 +533,8 @@ class TaskManager {
       throw new Error(`Feature '${featureName}' not found`);
     }
 
-    const nextTask = this.getNextTask(feature.tasks);
+    const taskList = await ensureTaskList(feature, featureName);
+    const nextTask = this.getNextTask(taskList);
 
     if (nextTask) {
       console.log(chalk.cyan(`\n⏭️  Next task: ${nextTask.id} - ${nextTask.title}`));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "4.3.0",
+  "version": "4.3.2",
   "description": "MORPH-SPEC: AI-First development framework with validation pipeline and multi-stack support",
   "keywords": [
     "claude-code",
@@ -48,6 +48,7 @@
     "docs:serve": "npx http-server docs/api -p 8080 -o"
   },
   "dependencies": {
+    "@polymorphism-tech/morph-spec": "^4.3.1",
     "ajv": "^8.12.0",
     "ajv-formats": "^3.0.1",
     "chalk": "^5.3.0",

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

@@ -71,7 +71,8 @@ export async function agentsReviewAggregateCommand(feature, options) {
   const agentList = options.agents.split(',').map(a => a.trim());
   const strategy = options.strategy || 'best-of-n';
 
-  console.log(chalk.cyan(`\n  Aggregate Reviews — ${feature}\n`));
+  console.log(chalk.yellow('\n  ⚠ [STUB] This command returns mock data. Real aggregation not yet implemented.\n'));
+  console.log(chalk.cyan(`  Aggregate Reviews — ${feature}\n`));
   console.log(`  Agents:   ${agentList.join(', ')}`);
   console.log(`  Strategy: ${strategy}`);
   console.log('');

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

@@ -123,6 +123,34 @@ export function detectAgentsCommand(input, options) {
   const config = loadAgentsConfig();
   const result = detectAgents(userInput, config);
 
+  // Stack-aware filtering: penalize stack-mismatched agents
+  try {
+    const projectConfigPath = join(process.cwd(), '.morph/config/config.json');
+    const projectConfig = JSON.parse(readFileSync(projectConfigPath, 'utf8'));
+    const stack = projectConfig?.project?.stack || projectConfig?.project?.language || '';
+    const isJsStack = stack === 'nodejs' || stack === 'javascript' || stack === 'nextjs';
+
+    if (isJsStack) {
+      const dotnetKeywords = ['dotnet', '.net', 'csharp', 'c#', 'blazor', 'razor', 'azure', 'bicep',
+        'ef core', 'entity framework', 'hangfire', 'mudblazor', 'fluent ui', 'asp.net'];
+      const hasExplicitDotnetRequest = dotnetKeywords.some(k => userInput.toLowerCase().includes(k));
+
+      if (!hasExplicitDotnetRequest) {
+        const dotnetAgents = new Set([
+          'dotnet-senior', 'azure-architect', 'ef-modeler', 'bicep-architect',
+          'blazor-builder', 'blazor-concurrency-validator', 'hangfire-orchestrator',
+          'azure-deploy-specialist'
+        ]);
+        result.core = result.core.filter(id => !dotnetAgents.has(id));
+        result.specialists = result.specialists.filter(id => !dotnetAgents.has(id));
+        result.all = result.all.filter(id => !dotnetAgents.has(id));
+        result.matches = result.matches.filter(m => !dotnetAgents.has(m.id));
+      }
+    }
+  } catch {
+    // Config not found or unreadable — skip stack filtering
+  }
+
   // Enrich with complexity analysis
   try {
     result.complexity = analyzeRequestComplexity(userInput);
@@ -141,7 +169,9 @@ export function detectAgentsCommand(input, options) {
   }
 
   // Enrich with skill paths for each detected agent
-  const allAgents = [...(config.agents.core || []), ...(config.agents.specialists || [])];
+  const allAgents = Object.entries(config.agents || {})
+    .filter(([id]) => !id.startsWith('_'))
+    .map(([id, agent]) => ({ id, ...agent }));
   result.skillPaths = result.all
     .map(id => {
       const agent = allAgents.find(a => a.id === id);

package/src/commands/project/detect.js

@@ -3,7 +3,7 @@ import ora from 'ora';
 import chalk from 'chalk';
 import { logger } from '../../utils/logger.js';
 import { detectProject, getDetectionSummary } from '../../lib/detectors/index.js';
-import { ensureDir, writeFile } from '../../utils/file-copier.js';
+import { ensureDir, writeFile, readJson, writeJson, pathExists } from '../../utils/file-copier.js';
 
 export async function detectCommand(options) {
   const targetPath = options.path || process.cwd();
@@ -84,6 +84,16 @@ export async function detectCommand(options) {
       const standardsPath = join(standardsDir, 'inferred.md');
       await writeFile(standardsPath, results.inferred.markdown);
 
+      // Update config.json with detected stack and architecture
+      const configPath = join(targetPath, '.morph', 'config', 'config.json');
+      if (await pathExists(configPath)) {
+        const projectConfig = await readJson(configPath);
+        projectConfig.project = projectConfig.project || {};
+        projectConfig.project.stack = results.structure.stack;
+        projectConfig.project.architecture = results.structure.architecture;
+        await writeJson(configPath, projectConfig);
+      }
+
       spinner.succeed('Results saved!');
       logger.dim(`  - ${logPath}`);
       logger.dim(`  - ${standardsPath}`);