@polymorphism-tech/morph-spec 4.2.0 → 4.3.1

package/docs/next-generation/THREAD-MANAGEMENT.md

@@ -0,0 +1,240 @@
+# Thread Management — MORPH-SPEC v3.0
+
+Thread management is the v3.0 system for coordinating multi-agent execution within a single feature. Threads allow parallel, sequential, and hybrid agent workflows with full lifecycle tracking.
+
+---
+
+## Thread Types
+
+| Thread | Code | Purpose | Auto-kill? |
+|--------|------|---------|------------|
+| **Base Thread** | B | Single agent, sequential implementation | No |
+| **Parallel Thread** | P | Isolated domain worker in a parallel squad | No |
+| **Fusion Thread** | F | One of N agents solving the same problem | No |
+| **Long-Running** | L | Persistent background agent with stop hooks | Yes (on stop hook) |
+| **Zero-Touch** | Z | Autonomous agent with auto-approval (requires max trust) | No |
+
+### Choosing a Thread Type
+
+```
+Is this a single, sequential implementation?
+  └─ YES → B-Thread (Base)
+
+Do you want N agents working on different domains simultaneously?
+  └─ YES → P-Thread (Parallel) per domain
+
+Do you want N agents solving the SAME problem (pick best result)?
+  └─ YES → F-Thread (Fusion)
+
+Will the agent run for >30 minutes or need periodic check-ins?
+  └─ YES → L-Thread (Long-Running)
+
+Is trust level "maximum" (>95% checkpoint pass rate)?
+  └─ YES → Z-Thread (Zero-Touch) eligible
+```
+
+---
+
+## Thread Lifecycle
+
+```
+pending → running → completed
+                 └→ failed
+                 └→ killed
+```
+
+Each thread stores its state in `.morph/state.json` under `threads`:
+
+```json
+{
+  "threads": {
+    "thr_abc12345": {
+      "id": "thr_abc12345",
+      "type": "parallel",
+      "feature": "user-auth",
+      "agent": "dotnet-senior",
+      "status": "running",
+      "startedAt": "2026-02-19T10:00:00Z",
+      "completedAt": null,
+      "metrics": {
+        "tasksCompleted": 3,
+        "filesCreated": 5,
+        "filesModified": 2,
+        "checkpointsPassed": 1,
+        "checkpointsFailed": 0
+      }
+    }
+  }
+}
+```
+
+---
+
+## CLI Reference
+
+### List threads
+
+```bash
+morph-spec threads list
+morph-spec threads list --feature user-auth
+morph-spec threads list --status running
+morph-spec threads list --type parallel
+```
+
+### Thread status
+
+```bash
+morph-spec threads status thr_abc12345
+```
+
+### Kill a thread
+
+```bash
+morph-spec threads kill thr_abc12345
+```
+
+### Analytics
+
+```bash
+morph-spec threads analytics --feature user-auth
+```
+
+### Wait for completion
+
+```bash
+# Wait for ALL threads in a feature
+morph-spec threads wait-all user-auth --timeout 60
+
+# Wait for ANY thread to complete
+morph-spec threads wait-any user-auth --timeout 30
+```
+
+---
+
+## P-Thread Isolation Rules
+
+Parallel threads (P-Threads) MUST follow strict isolation:
+
+| Rule | Description |
+|------|-------------|
+| **File ownership** | Each P-Thread writes ONLY to its assigned file set |
+| **Read-only shared** | Shared files (spec.md, contracts, standards) are READ-ONLY |
+| **No cross-writes** | Never write to another thread's files |
+| **Report on done** | Submit PARALLEL WORKER REPORT when complete |
+| **No external calls** | Don't spawn additional threads |
+
+### P-Thread Report Format
+
+```
+## PARALLEL WORKER REPORT
+
+**Thread ID:** {id}
+**Status:** completed | failed | blocked
+
+**Files Created:**
+- path/to/file1.cs
+- path/to/file2.cs
+
+**Tasks Completed:** T001, T002, T003
+
+**Blockers (if any):** None
+
+**Notes:** Any important implementation decisions
+```
+
+---
+
+## L-Thread Stop Hooks
+
+Long-running threads respond to stop hooks. Configure in `.claude/settings.local.json`:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node framework/hooks/agent-teams/validate-and-continue.js {feature}"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Stop hooks run every N seconds (configurable in `zero-touch.json`):
+
+```json
+{
+  "monitoring": {
+    "stopHooks": {
+      "enabled": true,
+      "interval": 30,
+      "hooks": ["validate-and-continue", "validate-checkpoints"]
+    }
+  }
+}
+```
+
+---
+
+## Thread Metrics Tracking
+
+Each feature tracks aggregate thread metrics in `state.json`:
+
+```json
+{
+  "features": {
+    "user-auth": {
+      "threadMetrics": {
+        "totalThreads": 3,
+        "completedThreads": 2,
+        "failedThreads": 0,
+        "parallelBatches": 1
+      }
+    }
+  }
+}
+```
+
+Access via:
+
+```bash
+morph-spec analytics feature user-auth
+```
+
+---
+
+## Decision Tree: When to Use Threads
+
+```
+Feature complexity?
+  SIMPLE (1-5 files) → B-Thread only, no parallelization
+  MEDIUM (6-15 files) → Consider P-Threads by domain
+  HIGH (>15 files) → P-Threads mandatory for speed
+
+Multiple independent domains?
+  YES → Spawn P-Thread per domain (backend, frontend, infra)
+  NO  → Single B-Thread is fine
+
+Need best-quality output from N attempts?
+  YES → F-Thread (Fusion) with aggregation
+
+Long implementation (>30 mins estimated)?
+  YES → L-Thread with stop hooks for periodic validation
+
+Trust level maximum + fully automated pipeline?
+  YES → Z-Thread (check with: morph-spec trust status)
+```
+
+---
+
+## Related
+
+- [Parallel Execution](PARALLEL-EXECUTION.md) — Squad templates and P-Thread coordination
+- [Context Optimization](CONTEXT-OPTIMIZATION.md) — Token efficiency during thread execution
+- [Migration Guide](MIGRATION-GUIDE.md) — Upgrading state.json to v3.0 thread schema

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "4.2.0",
-  "description": "MORPH-SPEC v3: AI-First development framework with validation pipeline, .NET 10, Microsoft Agent Framework, and Fluent UI Blazor",
+  "version": "4.3.1",
+  "description": "MORPH-SPEC: AI-First development framework with validation pipeline and multi-stack support",
   "keywords": [
     "claude-code",
     "claude",
@@ -40,9 +40,9 @@
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
     "start": "node bin/morph-spec.js",
-    "test": "node --test",
-    "test:coverage": "c8 --reporter=text --reporter=html --reporter=lcov node --test",
-    "test:coverage:summary": "c8 --reporter=text-summary node --test",
+    "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"

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

@@ -0,0 +1,97 @@
+/**
+ * Agents Fuse CLI command — F-Thread fusion execution
+ *
+ * Usage:
+ *   morph-spec agents fuse --prompt "..." --count=3 --strategy=best-of-n [--feature=<f>]
+ *   morph-spec agents review aggregate <feature> --agents=a1,a2,a3
+ */
+
+import chalk from 'chalk';
+import { runFusion, aggregateResults, displayFusionSummary } from '../../lib/execution/fusion-executor.js';
+
+export async function agentsFuseCommand(options) {
+  if (!options.prompt) {
+    console.error(chalk.red('--prompt is required'));
+    process.exit(1);
+  }
+
+  const count = parseInt(options.count || '3', 10);
+  const strategy = options.strategy || 'best-of-n';
+  const feature = options.feature || 'fusion-session';
+  const agents = options.agents ? options.agents.split(',').map(a => a.trim()) : null;
+
+  console.log(chalk.cyan(`\n  F-Thread Fusion Execution\n`));
+  console.log(`  Strategy:  ${strategy}`);
+  console.log(`  Agents:    ${count}`);
+  console.log(`  Feature:   ${feature}`);
+  console.log(`  Prompt:    ${options.prompt.substring(0, 80)}${options.prompt.length > 80 ? '...' : ''}`);
+  console.log('');
+
+  try {
+    const fusionSession = await runFusion(options.prompt, {
+      feature,
+      count,
+      strategy,
+      agents
+    });
+
+    console.log(chalk.cyan(`  ${fusionSession.threads.length} fusion threads spawned:\n`));
+    for (let i = 0; i < fusionSession.threads.length; i++) {
+      const thread = fusionSession.threads[i];
+      const agent = fusionSession.agentConfigs[i];
+      console.log(`  ${chalk.gray(thread.id.substring(0, 8))} — Agent: ${agent.agentId} (${thread.status})`);
+    }
+
+    console.log(chalk.yellow('\n  ⚠ Fusion threads spawned. To aggregate results:'));
+    console.log(chalk.gray('  1. Execute each thread using the Task tool with the agent configs'));
+    console.log(chalk.gray('  2. Collect results from each agent'));
+    console.log(chalk.gray('  3. Run: morph-spec agents fuse-aggregate --results=<file> --strategy=' + strategy));
+    console.log('');
+
+    if (options.json) {
+      console.log(JSON.stringify({
+        threads: fusionSession.threads.map(t => ({ id: t.id, agent: t.agent, status: t.status })),
+        agentConfigs: fusionSession.agentConfigs,
+        strategy,
+        feature
+      }, null, 2));
+    }
+  } catch (err) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+}
+
+export async function agentsReviewAggregateCommand(feature, options) {
+  if (!options.agents) {
+    console.error(chalk.red('--agents is required (comma-separated list)'));
+    process.exit(1);
+  }
+
+  const agentList = options.agents.split(',').map(a => a.trim());
+  const strategy = options.strategy || 'best-of-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('');
+
+  // Mock results for demo — in real usage, results come from agent output files
+  const mockResults = agentList.map((agentId, i) => ({
+    agentId,
+    content: `Agent ${agentId} review for ${feature}`,
+    checkpointsPassed: Math.floor(Math.random() * 3) + 2,
+    checkpointsFailed: Math.floor(Math.random() * 2),
+    errors: Math.floor(Math.random() * 2),
+    warnings: Math.floor(Math.random() * 3)
+  }));
+
+  try {
+    const aggregated = aggregateResults(mockResults, strategy);
+    displayFusionSummary(aggregated);
+  } catch (err) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+}

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

@@ -0,0 +1,112 @@
+/**
+ * Micro Agent CLI command
+ *
+ * Usage:
+ *   morph-spec micro-agent create <name> --base-agent=<agent> --mission="..." [--standards=file1,file2]
+ *   morph-spec micro-agent list
+ *   morph-spec micro-agent show <name>
+ */
+
+import chalk from 'chalk';
+import {
+  createMicroAgent, saveMicroAgent, listMicroAgents, getMicroAgent
+} from '../../lib/agents/micro-agent-factory.js';
+
+export async function microAgentCreateCommand(name, options) {
+  try {
+    if (!options.baseAgent) {
+      console.error(chalk.red('--base-agent is required'));
+      process.exit(1);
+    }
+    if (!options.mission) {
+      console.error(chalk.red('--mission is required'));
+      process.exit(1);
+    }
+
+    const standards = options.standards ? options.standards.split(',').map(s => s.trim()) : [];
+
+    const agent = createMicroAgent({
+      name,
+      baseAgent: options.baseAgent,
+      standards,
+      mission: options.mission,
+      tools: options.tools ? options.tools.split(',').map(t => t.trim()) : null
+    });
+
+    const filePath = saveMicroAgent(agent);
+
+    console.log(chalk.green(`\n  ✓ Micro-agent created: ${name}`));
+    console.log(`  Base agent: ${options.baseAgent}`);
+    console.log(`  Standards: ${standards.length > 0 ? standards.join(', ') : '(none)'}`);
+    console.log(`  Context estimate: ${agent.contextEstimate.total.toLocaleString()} tokens`);
+    console.log(`  Saved to: ${chalk.gray(filePath)}`);
+    console.log('');
+  } catch (err) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+}
+
+export async function microAgentListCommand(options) {
+  try {
+    const agents = listMicroAgents();
+
+    if (agents.length === 0) {
+      console.log(chalk.gray('\n  No micro-agents found. Create one with: morph-spec micro-agent create\n'));
+      return;
+    }
+
+    console.log(chalk.cyan(`\n  Micro-Agents (${agents.length})\n`));
+    console.log('  ' + 'Name'.padEnd(20) + ' ' + 'Base'.padEnd(20) + ' ' + 'Standards'.padEnd(12) + ' ' + 'Context');
+    console.log('  ' + '─'.repeat(70));
+
+    for (const agent of agents) {
+      console.log(
+        '  ' +
+        agent.id.padEnd(20) + ' ' +
+        (agent.baseAgent || '—').padEnd(20) + ' ' +
+        String(agent.standards).padEnd(12) + ' ' +
+        `${(agent.contextEstimate / 1000).toFixed(1)}K tokens`
+      );
+    }
+    console.log('');
+  } catch (err) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+}
+
+export async function microAgentShowCommand(name, options) {
+  try {
+    const agent = getMicroAgent(name);
+    if (!agent) {
+      console.error(chalk.red(`Micro-agent not found: ${name}`));
+      process.exit(1);
+    }
+
+    console.log(chalk.cyan(`\n  Micro-Agent: ${name}\n`));
+    console.log(`  Base agent:  ${agent.baseAgent}`);
+    console.log(`  Domain:      ${agent.domain}`);
+    console.log(`  Created:     ${agent.createdAt}`);
+    console.log(`\n  Mission:\n  ${agent.mission}`);
+
+    if (agent.standards?.length > 0) {
+      console.log('\n  Standards:');
+      agent.standards.forEach(s => console.log(`    - ${s}`));
+    }
+
+    console.log('\n  Context estimate:');
+    console.log(`    Standards: ${agent.contextEstimate?.standards?.toLocaleString() || 0} tokens`);
+    console.log(`    Overhead:  ${agent.contextEstimate?.overhead?.toLocaleString() || 0} tokens`);
+    console.log(`    Total:     ${agent.contextEstimate?.total?.toLocaleString() || 0} tokens`);
+
+    if (options.showPrompt) {
+      console.log(chalk.cyan('\n  Generated Prompt:'));
+      console.log(agent.prompt);
+    }
+    console.log('');
+  } catch (err) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+}

package/src/commands/agents/spawn-team.js

@@ -1,7 +1,10 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
+import { join } from 'path';
 import { getFeature } from '../../core/state/state-manager.js';
 import { orchestrateTeam } from '../../lib/orchestration/team-orchestrator.js';
+import { spawnParallel } from '../../lib/execution/parallel-executor.js';
+import { renderHOP } from '../../lib/hops/hop-composer.js';
 
 /**
  * Spawn Team Command - Generate agent team configurations
@@ -15,6 +18,35 @@ const program = new Command();
 /**
  * Spawn team action function
  */
+/**
+ * Spawn team in parallel mode
+ * --parallel backend,frontend,infra
+ */
+export async function spawnTeamParallelCommand(featureName, squads, options = {}) {
+  const squadList = squads.split(',').map(s => s.trim());
+  const maxConcurrent = parseInt(options.maxConcurrent || '3', 10);
+
+  console.log(chalk.cyan(`\n  Spawning ${squadList.length} parallel squads for: ${featureName}\n`));
+
+  const threadConfigs = squadList.map(squad => ({
+    agent: squad,
+    mission: `Implement ${squad} domain for ${featureName}`,
+    meta: { squad }
+  }));
+
+  try {
+    const threads = await spawnParallel({ feature: featureName, threadConfigs, maxConcurrent });
+    console.log(chalk.green(`  ✓ ${threads.length} threads spawned in parallel`));
+    for (const t of threads) {
+      console.log(`    ${chalk.gray(t.id.substring(0, 8))} — ${t.agent} (${t.status})`);
+    }
+    console.log(`\n  Monitor with: morph-spec threads wait-all ${featureName}\n`);
+  } catch (err) {
+    console.error(chalk.red(`  Error: ${err.message}`));
+    process.exit(1);
+  }
+}
+
 export async function spawnTeamCommand(featureName, options = {}) {
     try {
       // Get feature state
@@ -94,12 +126,44 @@ export async function spawnTeamCommand(featureName, options = {}) {
         });
       }
 
-      // Show Task tool usage
+      // Show Task tool usage (with HOP rendering)
       console.log(chalk.bold('\n📝 Task Tool Usage:'));
       console.log(chalk.gray('\nUse the following pattern to spawn the team:\n'));
 
-      console.log(chalk.cyan('```typescript'));
-      console.log(chalk.white(`{
+      // Try to render backend squad HOP if applicable
+      let hopPrompt = null;
+      const hasBackend = teamConfig.teammates.some(t => t.id.includes('dotnet') || t.id.includes('api') || t.id.includes('ef'));
+      if (hasBackend && options.useHop !== false) {
+        try {
+          const frameworkRoot = join(process.cwd(), 'framework');
+          const domainLeaders = teamConfig.teammates
+            .filter(t => t.tier === 2)
+            .map(t => `- ${t.id}: ${t.role}`)
+            .join('\n');
+          hopPrompt = renderHOP('hop-backend-squad', {
+            AGENT_ID: teamConfig.teamHierarchy.teamLead,
+            MISSION: `Implement ${featureName}`,
+            SPEC_SUMMARY: `Feature: ${featureName}. See spec.md for full details.`,
+            ADDITIONAL_LEADERS: domainLeaders,
+            TASKS: teamConfig.teammates.filter(t => t.tier === 3).map((t, i) => `- T${String(i+1).padStart(3,'0')}: ${t.role}`).join('\n'),
+            DELIVERABLES: 'See spec.md deliverables section',
+            CONSTRAINTS: 'Follow all architecture and security standards',
+            FEATURE_NAME: featureName
+          }, { frameworkRoot });
+        } catch {
+          hopPrompt = null;
+        }
+      }
+
+      if (hopPrompt) {
+        console.log(chalk.cyan('HOP-rendered prompt (backend squad):'));
+        console.log(chalk.gray('─'.repeat(60)));
+        console.log(chalk.white(hopPrompt.substring(0, 800) + (hopPrompt.length > 800 ? '\n...[truncated]' : '')));
+        console.log(chalk.gray('─'.repeat(60)));
+        console.log(chalk.dim('\nFull HOP: morph-spec hop render hop-backend-squad output.md \'{...}\''));
+      } else {
+        console.log(chalk.cyan('```typescript'));
+        console.log(chalk.white(`{
   subagent_type: "general-purpose",
   description: "Implement ${featureName}",
   prompt: \`You are the Team Lead (${teamConfig.teamHierarchy.teamLead})...
@@ -123,7 +187,8 @@ Standards to follow: [coding.md, architecture.md]
 Deliverables: [list specific outputs]
 \`
 }`));
-      console.log(chalk.cyan('```\n'));
+        console.log(chalk.cyan('```\n'));
+      }
 
       // Show individual teammates
       console.log(chalk.bold('Individual Teammates:'));