@polymorphism-tech/morph-spec 4.2.0 → 4.3.0

package/docs/next-generation/MIGRATION-GUIDE.md

@@ -0,0 +1,253 @@
+# Migration Guide — MORPH-SPEC v2.x → v3.0
+
+This guide covers migrating an existing MORPH-SPEC v2.x installation to v3.0.0.
+
+---
+
+## What Changes in v3.0
+
+### state.json Schema (breaking)
+
+v3.0 adds required fields to `state.json`:
+
+| Field | Where | Description |
+|-------|-------|-------------|
+| `version` | root | Updated from `2.x.x` → `3.0.0` |
+| `threads` | root | New `{}` object for thread tracking |
+| `features.*.threadMetrics` | per-feature | Thread statistics object |
+| `features.*.trustConfig` | per-feature | Trust level and override |
+| `features.*.contextBundles` | per-feature | Array of context bundle references |
+| `features.*.checkpoints` | per-feature | Array (if not already present) |
+| `metadata.migratedAt` | metadata | Migration timestamp |
+
+### agents.json (additive, non-breaking)
+
+v3.0 adds 4 new agents. Existing agents are preserved unchanged:
+- `vector-search-expert` — Azure AI Search + RAG
+- `thread-orchestrator` — Parallel execution coordination
+- `context-optimizer` — Token efficiency
+- `observability-expert` — App Insights, Serilog, OpenTelemetry
+
+### New CLI Commands
+
+All new — no existing commands changed:
+- `morph-spec threads [list|status|kill|analytics|wait-all|wait-any]`
+- `morph-spec trust [status|set|history|auto-calculate|clear]`
+- `morph-spec migrate [status|v2-to-v3|rollback-to-v2]`
+- `morph-spec hop [list|render]`
+- `morph-spec analytics [feature|context|project]`
+- `morph-spec core-four`
+- `morph-spec parallel [plan|run|status]`
+- `morph-spec fusion [run|aggregate]`
+- `morph-spec mcp [optimize|list]`
+- `morph-spec micro-agent [create|list|show]`
+- `morph-spec prime`
+
+### New Framework Files
+
+83 new files added across:
+- `src/lib/` — 15 new library files
+- `src/commands/` — 11 new command files
+- `src/migrations/` — 2 migration scripts
+- `framework/templates/meta-prompts/` — 12 HOP templates
+- `framework/standards/` — 23 new standards files
+- `framework/workflows/configs/zero-touch.json`
+- `test/integration/` — 4 integration test suites
+- `docs/next-generation/` — 6 documentation files
+
+---
+
+## Prerequisites
+
+Before migrating:
+
+- [ ] MORPH-SPEC CLI version ≥ 4.2.0 (`morph-spec --version`)
+- [ ] Node.js ≥ 18 (`node --version`)
+- [ ] Git working tree clean (`git status`)
+- [ ] Current `.morph/state.json` is valid JSON
+
+```bash
+# Verify CLI version
+morph-spec --version
+# Should show: 4.2.0 or higher
+
+# Check migration status before starting
+morph-spec migrate status
+```
+
+---
+
+## Step-by-Step Migration
+
+### Step 1: Check current state
+
+```bash
+morph-spec migrate status
+```
+
+Expected output:
+```
+📊 Migration Status
+
+state.json
+  Version:      ⚠ Needs migration (current: v2.1.1)
+  Needs update: Yes
+  Has backup:   No
+
+agents.json files
+  ⚠ .morph/config/agents.json
+    Missing: vector-search-expert, thread-orchestrator, context-optimizer, observability-expert
+```
+
+### Step 2: Run the migration
+
+```bash
+morph-spec migrate v2-to-v3
+```
+
+This will:
+1. Backup `state.json` → `state.v2.backup.json`
+2. Update `state.json` version to `3.0.0`
+3. Add `threads: {}` to root
+4. Add `threadMetrics`, `trustConfig`, `contextBundles` to each feature
+5. Add 4 new agents to each `agents.json` file found
+
+Expected output:
+```
+🚀 Migrating MORPH-SPEC v2 → v3.0
+
+Step 1: Migrating state.json (2.1.1 → 3.0.0)
+  ✓ Migration complete: v2.1.1 → 3.0.0
+  Backup: .morph/state.v2.backup.json
+  Changes:
+    • Version: 2.1.1 → 3.0.0
+    • Added: threads: {}
+    • Feature "user-auth": added threadMetrics, trustConfig, contextBundles, checkpoints
+    • Updated metadata.lastUpdated and migratedAt
+
+Step 2: Updating agents.json files
+  ✓ .morph/config/agents.json: added vector-search-expert, thread-orchestrator, context-optimizer, observability-expert
+  – stacks/blazor-azure/.morph/config/agents.json: already up to date
+
+✅ Migration complete! MORPH-SPEC is now on v3.0.0
+```
+
+### Step 3: Verify migration
+
+```bash
+morph-spec doctor --v3
+```
+
+All checks should pass:
+```
+✅ 8/8 — All v3.0 checks passed!
+```
+
+### Step 4: Commit the migration
+
+```bash
+git add .morph/state.json .morph/config/agents.json
+git commit -m "chore(migration): upgrade MORPH-SPEC state to v3.0.0"
+```
+
+---
+
+## Rollback
+
+If the migration causes issues, restore the v2 backup:
+
+```bash
+morph-spec migrate rollback-to-v2 --force
+```
+
+This restores `state.v2.backup.json` → `state.json`.
+
+**Note:** `agents.json` changes are NOT rolled back (additive only, safe to keep).
+
+---
+
+## Manual Migration (Fallback)
+
+If the automated migration fails, update `state.json` manually:
+
+```json
+{
+  "version": "3.0.0",
+  "threads": {},
+  "features": {
+    "your-feature": {
+      "threadMetrics": {
+        "totalThreads": 0,
+        "completedThreads": 0,
+        "failedThreads": 0,
+        "parallelBatches": 0
+      },
+      "trustConfig": {
+        "level": "low",
+        "passRate": 0,
+        "lastCalculated": "2026-02-19T10:00:00.000Z"
+      },
+      "contextBundles": [],
+      "checkpoints": []
+    }
+  },
+  "metadata": {
+    "migratedAt": "2026-02-19T10:00:00.000Z",
+    "migratedFrom": "2.1.1"
+  }
+}
+```
+
+---
+
+## Post-Migration: Enable v3.0 Features
+
+After migration, v3.0 features are available immediately:
+
+```bash
+# Check trust level (starts at "low")
+morph-spec trust status
+
+# View thread management
+morph-spec threads list
+
+# Try context priming
+morph-spec prime feature
+
+# Explore HOPs
+morph-spec hop list
+```
+
+**Trust level** starts at `low` until checkpoints accumulate. To reach `maximum` trust (required for zero-touch), complete 10+ checkpoints with >95% pass rate.
+
+---
+
+## Troubleshooting
+
+### "state.json not found"
+
+Run `morph-spec state init` first to create the initial state.
+
+### "agents.json: Failed to parse"
+
+Check for JSON syntax errors: `cat .morph/config/agents.json | node -e "JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'))"`
+
+### "migration fails with unknown version"
+
+The migration handles any version string that isn't `3.0.0`. If your version field is missing or corrupted, set it manually to `2.1.1` before running migration.
+
+### Rollback backup missing
+
+If `state.v2.backup.json` is gone but you need v2:
+- Restore from git: `git show HEAD:.morph/state.json > .morph/state.json`
+- Or re-run migration (it's idempotent for already-migrated files)
+
+---
+
+## Related
+
+- [Thread Management](THREAD-MANAGEMENT.md) — New thread features in v3.0
+- [Context Optimization](CONTEXT-OPTIMIZATION.md) — Using new context tools
+- [Meta-Prompts](META-PROMPTS.md) — HOP system overview
+- `src/migrations/v2-to-v3.js` — Migration script source
+- `src/migrations/agents-update.js` — Agents update script source

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.0",
+  "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,96 @@
+/**
+ * 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.cyan(`\n  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);
+  }
+}