@polymorphism-tech/morph-spec 4.2.0 → 4.3.0

package/docs/v3.0/EXECUTION-FLOW.md

@@ -1,1304 +0,0 @@
-# MORPH-SPEC v3.0 - Execution Flow & Code Architecture
-
-> How the finished framework will actually work: runtime flows, code execution paths, and concrete examples
-
-**Status:** Technical Design ✅
-**Last Updated:** 2026-02-18
-
----
-
-## Table of Contents
-
-- [Runtime Architecture](#runtime-architecture)
-- [Execution Scenarios](#execution-scenarios)
-- [Code Flow Examples](#code-flow-examples)
-- [State Management Flow](#state-management-flow)
-- [Key Classes & Interfaces](#key-classes--interfaces)
-
----
-
-## Runtime Architecture
-
-### Component Interaction Map
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                    MORPH-SPEC v3.0 Runtime                       │
-└─────────────────────────────────────────────────────────────────┘
-
-USER COMMAND: morph-spec feature create user-auth --request "..."
-    ↓
-┌──────────────────────────────────────────────────────────────────┐
-│ CLI Layer (src/commands/feature-create.js)                       │
-├──────────────────────────────────────────────────────────────────┤
-│ 1. Parse arguments                                                │
-│ 2. Validate inputs                                                │
-│ 3. Load project context (state.json, agents.json)                │
-└──────────────────────────────────────────────────────────────────┘
-    ↓
-┌──────────────────────────────────────────────────────────────────┐
-│ Workflow Detection Layer (src/lib/workflow-detector.js)          │
-├──────────────────────────────────────────────────────────────────┤
-│ 1. Analyze request keywords                                       │
-│ 2. Estimate complexity (files, lines)                            │
-│ 3. Check trust history (state.json)                              │
-│ 4. Score workflows (fast-track/standard/full-morph/fusion/etc.)  │
-│ 5. Return: { workflow: 'full-morph', confidence: 0.92 }          │
-└──────────────────────────────────────────────────────────────────┘
-    ↓
-┌──────────────────────────────────────────────────────────────────┐
-│ Thread Manager (src/lib/thread-manager.js)                       │
-├──────────────────────────────────────────────────────────────────┤
-│ 1. Create feature entry in state.json                            │
-│ 2. Determine thread type (parallel/fusion/long-running)          │
-│ 3. Initialize thread metrics tracking                            │
-│ 4. Create thread instances:                                      │
-│    - If P-Thread → spawn 3-5 parallel threads                    │
-│    - If F-Thread → spawn N fusion threads                        │
-│    - If base → single thread                                     │
-│ 5. Register threads in state.json                                │
-└──────────────────────────────────────────────────────────────────┘
-    ↓
-┌──────────────────────────────────────────────────────────────────┐
-│ Context Optimizer (src/lib/context-optimizer.js)                 │
-├──────────────────────────────────────────────────────────────────┤
-│ 1. Detect feature type (feature/bug/refactor/design/infra)       │
-│ 2. Load appropriate prime file (.morph/context/*-prime.md)       │
-│ 3. Select relevant standards (3-5 files vs all 71)               │
-│ 4. Select relevant agents (domain-specific)                      │
-│ 5. Check for context bundles (resume from checkpoint?)           │
-│ 6. Return optimized context (~500 tokens vs 23K)                 │
-└──────────────────────────────────────────────────────────────────┘
-    ↓
-┌──────────────────────────────────────────────────────────────────┐
-│ Agent Executor (src/lib/agent-executor.js)                       │
-├──────────────────────────────────────────────────────────────────┤
-│ 1. Load agents.json hierarchy                                    │
-│ 2. Identify required agents (workflow-detector output)           │
-│ 3. For each agent:                                               │
-│    a. Render HOP template (meta-prompts/squad-leader.md)         │
-│    b. Inject context (primed context from optimizer)             │
-│    c. Inject standards (selective list)                          │
-│    d. Inject tasks (from tasks.json)                             │
-│ 4. Return agent configuration objects                            │
-└──────────────────────────────────────────────────────────────────┘
-    ↓
-┌──────────────────────────────────────────────────────────────────┐
-│ Parallel Executor (src/lib/parallel-executor.js) - IF P-THREAD   │
-├──────────────────────────────────────────────────────────────────┤
-│ 1. Analyze task dependencies (tasks.json)                        │
-│ 2. Create parallel groups:                                       │
-│    - PG001: [T001, T002, T003] (independent)                     │
-│    - PG002: [T004, T005] (depends on PG001)                      │
-│ 3. For each parallel group:                                      │
-│    a. Spawn N threads (max-concurrent=3)                         │
-│    b. Execute simultaneously                                     │
-│    c. Collect results in thread-coordinator                      │
-│ 4. Wait for all threads in group before next group               │
-└──────────────────────────────────────────────────────────────────┘
-    ↓
-┌──────────────────────────────────────────────────────────────────┐
-│ Fusion Aggregator (src/lib/fusion-executor.js) - IF F-THREAD     │
-├──────────────────────────────────────────────────────────────────┤
-│ 1. Spawn 3 agents with same prompt (different models)            │
-│ 2. Execute in parallel (sandbox environments)                    │
-│ 3. Collect 3 design outputs                                      │
-│ 4. Score each output:                                            │
-│    - Checkpoint pass rate (40%)                                  │
-│    - Code quality (30%)                                          │
-│    - Completeness (30%)                                          │
-│ 5. Aggregate results:                                            │
-│    - best-of-n: Pick highest score                              │
-│    - consensus: Merge common elements                            │
-│    - manual-select: Present all to user                         │
-│ 6. Return winning design                                         │
-└──────────────────────────────────────────────────────────────────┘
-    ↓
-┌──────────────────────────────────────────────────────────────────┐
-│ Validators Layer (Tier 4 Agents)                                 │
-├──────────────────────────────────────────────────────────────────┤
-│ HOOK TRIGGER: After each tool call, every 3 tasks, pre-commit    │
-│                                                                   │
-│ 1. architecture-expert:                                          │
-│    - Check DI patterns (IDbContextFactory vs DbContext)          │
-│    - Validate async/await usage                                  │
-│    - Verify lifecycle scopes                                     │
-│                                                                   │
-│ 2. security-expert:                                              │
-│    - Scan for SQL injection patterns                             │
-│    - Check for XSS vulnerabilities                               │
-│    - Detect exposed secrets                                      │
-│                                                                   │
-│ 3. packages-validator:                                           │
-│    - Check NuGet package conflicts                               │
-│    - Verify .NET 10 compatibility                                │
-│                                                                   │
-│ 4. design-system-validator:                                      │
-│    - Validate CSS palette compliance                             │
-│    - Check spacing and typography                                │
-│                                                                   │
-│ Return: { passed: true/false, violations: [...] }                │
-└──────────────────────────────────────────────────────────────────┘
-    ↓
-┌──────────────────────────────────────────────────────────────────┐
-│ Checkpoint Manager (Every 3 tasks)                               │
-├──────────────────────────────────────────────────────────────────┤
-│ 1. Detect checkpoint trigger (task count % 3 === 0)              │
-│ 2. Run all validators in parallel                                │
-│ 3. Collect results                                               │
-│ 4. If failures:                                                  │
-│    a. Save artifact trail (screenshots, logs)                    │
-│    b. Mark task as NOT done                                      │
-│    c. Provide feedback to agent                                  │
-│    d. Retry (max 3 times)                                        │
-│ 5. If success:                                                   │
-│    a. Update state.json (checkpointPassRate)                     │
-│    b. Create context bundle (compress checkpoint)                │
-│    c. Continue to next tasks                                     │
-└──────────────────────────────────────────────────────────────────┘
-    ↓
-┌──────────────────────────────────────────────────────────────────┐
-│ Stop Hook Executor (IF L-THREAD)                                 │
-├──────────────────────────────────────────────────────────────────┤
-│ TRIGGER: Agent attempts to stop after 30 min of work             │
-│                                                                   │
-│ 1. Agent sends stop signal                                       │
-│ 2. Stop hook intercepts:                                         │
-│    framework/hooks/agent-stop/validate-and-continue.js           │
-│ 3. Run validation:                                               │
-│    a. Execute checkpoint validators                              │
-│    b. Check task completion                                      │
-│    c. Verify deliverables                                        │
-│ 4. Decision:                                                     │
-│    - If valid → return { action: 'complete' }                    │
-│    - If invalid → return { action: 'continue', feedback: '...' } │
-│ 5. Agent continues with feedback (loop up to 5 times)            │
-│ 6. Enables hours-long autonomous runs                            │
-└──────────────────────────────────────────────────────────────────┘
-    ↓
-┌──────────────────────────────────────────────────────────────────┐
-│ Trust Manager (src/lib/trust-manager.js)                         │
-├──────────────────────────────────────────────────────────────────┤
-│ 1. Track checkpoint pass rates per feature                       │
-│ 2. Calculate trust level:                                        │
-│    - <80% pass rate → low                                        │
-│    - 80-90% → medium                                             │
-│    - 90-95% → high                                               │
-│    - >95% → maximum                                              │
-│ 3. Update state.json trustConfig                                 │
-│ 4. Enable auto-approvals based on trust:                         │
-│    - medium → auto-approve design gate                           │
-│    - high → auto-approve design + tasks gates                    │
-│    - maximum → zero-touch workflow                               │
-└──────────────────────────────────────────────────────────────────┘
-    ↓
-┌──────────────────────────────────────────────────────────────────┐
-│ Approval Gates (src/commands/advance-phase.js)                   │
-├──────────────────────────────────────────────────────────────────┤
-│ 1. Check current phase (design/tasks)                            │
-│ 2. Query trust-manager for trust level                           │
-│ 3. Decision:                                                     │
-│    - If trust >= threshold → AUTO-APPROVE                        │
-│      • Log: "Auto-approved (high trust, 95% pass rate)"          │
-│      • Advance phase immediately                                 │
-│    - If trust < threshold → PAUSE                                │
-│      • Present outputs to user                                   │
-│      • Wait for approval                                         │
-│ 4. Update state.json approval status                             │
-└──────────────────────────────────────────────────────────────────┘
-    ↓
-┌──────────────────────────────────────────────────────────────────┐
-│ Analytics Engine (Continuous)                                    │
-├──────────────────────────────────────────────────────────────────┤
-│ RUNS IN BACKGROUND: Tracks metrics throughout execution          │
-│                                                                   │
-│ 1. Thread Analytics:                                             │
-│    - Tool calls count (Read, Write, Edit, Bash)                  │
-│    - Thread duration (start to completion)                       │
-│    - Parallel efficiency (actual vs theoretical)                 │
-│                                                                   │
-│ 2. Context Analytics:                                            │
-│    - Token usage per thread (peak, average)                      │
-│    - Optimization opportunities detection                        │
-│    - MCP server usage tracking                                   │
-│                                                                   │
-│ 3. Project Analytics:                                            │
-│    - Feature completion trends                                   │
-│    - Agent performance (pass rates)                              │
-│    - Trust level progression                                     │
-│                                                                   │
-│ 4. Real-time Updates:                                            │
-│    - Update state.json threadMetrics                             │
-│    - Generate recommendations                                    │
-│    - Trigger alerts (if efficiency < 50%)                        │
-└──────────────────────────────────────────────────────────────────┘
-    ↓
-┌──────────────────────────────────────────────────────────────────┐
-│ Learning System (Post-completion)                                │
-├──────────────────────────────────────────────────────────────────┤
-│ 1. Analyze feature outcome (success/failure)                     │
-│ 2. Extract patterns:                                             │
-│    - What worked? (capture as 'success' pattern)                 │
-│    - What failed? (capture as 'avoid' pattern)                   │
-│    - Any optimizations? (capture as 'optimization' pattern)      │
-│ 3. Update framework/memory/patterns-learned.md                   │
-│ 4. Promote patterns to standards if repeated 3+ times            │
-└──────────────────────────────────────────────────────────────────┘
-    ↓
-OUTPUT: Feature Complete + Analytics + Patterns
-```
-
----
-
-## Execution Scenarios
-
-### Scenario 1: Standard Feature (Sequential Execution)
-
-**User Request:** `morph-spec feature create user-pagination --request "add pagination to users table"`
-
-#### Step-by-Step Execution:
-
-```javascript
-// 1. CLI Entry Point
-// src/commands/feature-create.js
-async function createFeature(name, request) {
-  const projectState = await loadState();
-
-  // 2. Workflow Detection
-  const workflow = await workflowDetector.analyze({
-    request,
-    keywords: extractKeywords(request), // ['pagination', 'users', 'table']
-    estimatedFiles: 5,
-    estimatedLines: 200
-  });
-
-  console.log(`✓ Detected workflow: ${workflow.type} (${workflow.confidence}% confidence)`);
-  // Output: ✓ Detected workflow: standard (87% confidence)
-
-  // 3. Create Feature State
-  const feature = await stateManager.createFeature({
-    name: 'user-pagination',
-    workflow: workflow.type,
-    phase: 'proposal',
-    request
-  });
-
-  // 4. Context Optimization
-  const context = await contextOptimizer.prime({
-    featureType: 'feature', // detected from request
-    domain: 'backend',      // detected from 'pagination' keyword
-    standards: [
-      'backend/dotnet/core.md',
-      'backend/api/minimal-api.md',
-      'frontend/blazor/state.md'
-    ]
-  });
-
-  console.log(`✓ Context optimized: ${context.tokens} tokens (vs 23K baseline)`);
-  // Output: ✓ Context optimized: 4,200 tokens (vs 23K baseline)
-
-  // 5. Thread Creation (Base Thread - Sequential)
-  const thread = await threadManager.createThread({
-    feature: feature.name,
-    type: 'base',
-    agent: 'dotnet-senior',
-    context
-  });
-
-  // 6. Agent Execution
-  const agentConfig = await agentExecutor.configure({
-    agent: 'dotnet-senior',
-    hopTemplate: 'meta-prompts/backend-squad.md',
-    variables: {
-      SQUAD_NAME: 'Backend',
-      MISSION: 'Implement pagination for users table',
-      STANDARDS: context.standards,
-      TASKS: [] // Will be populated after TASKS phase
-    }
-  });
-
-  // 7. Execute Workflow Phases
-  await executePhase('proposal', agentConfig);
-  // Creates: .morph/features/user-pagination/proposal.md
-
-  await executePhase('design', agentConfig);
-  // Creates: spec.md, contracts, decisions.md
-
-  // 8. Approval Gate (Design)
-  const trustLevel = await trustManager.getTrustLevel(feature.name);
-  if (trustLevel === 'high' || trustLevel === 'maximum') {
-    console.log('✓ Design auto-approved (high trust, 94% historical pass rate)');
-    await stateManager.approveGate(feature.name, 'design');
-  } else {
-    console.log('⏸️  Paused for design approval (medium trust)');
-    return; // User must approve manually
-  }
-
-  await executePhase('tasks', agentConfig);
-  // Creates: tasks.json with dependency graph
-
-  // 9. Approval Gate (Tasks)
-  // Same logic as design gate
-
-  await executePhase('implement', agentConfig);
-  // Executes tasks sequentially: T001 → T002 → T003 → ...
-
-  // 10. Checkpoints (Every 3 tasks)
-  // After T003, T006, T009:
-  await checkpointManager.validate({
-    feature: feature.name,
-    validators: ['architecture-expert', 'security-expert', 'packages-validator']
-  });
-
-  // 11. Analytics Update (Continuous)
-  await analyticsEngine.recordMetrics({
-    feature: feature.name,
-    threadId: thread.id,
-    toolCalls: 87,
-    duration: '1h 23m',
-    checkpointPassRate: 1.0
-  });
-
-  console.log('✅ Feature complete: user-pagination');
-}
-```
-
----
-
-### Scenario 2: Parallel Feature (P-Thread Execution)
-
-**User Request:** `morph-spec feature create user-auth --request "implement complete authentication system with JWT"`
-
-#### Step-by-Step Execution:
-
-```javascript
-// 1. Workflow Detection
-const workflow = await workflowDetector.analyze({
-  request: "implement complete authentication system with JWT",
-  keywords: ['authentication', 'complete', 'system'],
-  estimatedFiles: 15,
-  estimatedLines: 800
-});
-
-console.log(`✓ Detected workflow: ${workflow.type}`);
-// Output: ✓ Detected workflow: full-morph (92% confidence)
-
-// 2. Thread Manager Decision
-const threadType = await threadManager.determineType({
-  workflow: 'full-morph',
-  complexity: 'high',
-  estimatedFiles: 15
-});
-
-console.log(`✓ Thread type: ${threadType}`);
-// Output: ✓ Thread type: parallel (P-Thread with 3 squads)
-
-// 3. Parallel Executor Setup
-const parallelConfig = {
-  maxConcurrent: 3,
-  squads: [
-    {
-      name: 'Backend',
-      leader: 'dotnet-senior',
-      members: ['ef-modeler', 'api-designer', 'event-architect'],
-      tasks: ['T001', 'T002', 'T003', 'T004', 'T005'] // Backend tasks
-    },
-    {
-      name: 'Frontend',
-      leader: 'blazor-builder',
-      members: ['css-specialist'],
-      tasks: ['T006', 'T007', 'T008'] // UI tasks
-    },
-    {
-      name: 'Infrastructure',
-      leader: 'bicep-architect',
-      members: ['azure-architect'],
-      tasks: ['T009', 'T010'] // Infra tasks
-    }
-  ]
-};
-
-// 4. Spawn Parallel Threads
-const threads = await parallelExecutor.spawn(parallelConfig);
-
-console.log(`✓ Spawned ${threads.length} parallel threads:`);
-// Output:
-// ✓ Spawned 3 parallel threads:
-//   - thread-001: Backend (dotnet-senior) - 5 tasks
-//   - thread-002: Frontend (blazor-builder) - 3 tasks
-//   - thread-003: Infrastructure (bicep-architect) - 2 tasks
-
-// 5. Execute Squads in Parallel
-await Promise.all([
-  executeSquad(threads[0]), // Backend: async, parallel execution
-  executeSquad(threads[1]), // Frontend: async, parallel execution
-  executeSquad(threads[2])  // Infrastructure: async, parallel execution
-]);
-
-// 6. Real-time Monitoring
-// Analytics engine tracks all threads simultaneously:
-setInterval(async () => {
-  const status = await threadManager.getStatus('user-auth');
-  console.log(`
-  📊 Parallel Execution Status:
-  - Backend: ${status.threads[0].progress}% (T003/T005 complete)
-  - Frontend: ${status.threads[1].progress}% (T007/T008 complete)
-  - Infrastructure: ${status.threads[2].progress}% (T010/T010 complete ✅)
-  - Parallel Efficiency: ${status.parallelEfficiency}%
-  `);
-}, 30000); // Every 30 seconds
-
-// 7. Thread Coordination
-// When one squad finishes early, it can help others:
-await threadCoordinator.balanceLoad({
-  feature: 'user-auth',
-  strategy: 'work-stealing' // Idle threads pick up remaining tasks
-});
-
-// 8. Aggregation
-await threadCoordinator.waitAll('user-auth');
-
-console.log('✅ All squads complete. Merging results...');
-
-const results = await threadCoordinator.mergeResults({
-  threads: threads,
-  conflictResolution: 'last-write-wins' // or 'manual-review'
-});
-
-// 9. Final Validation
-await checkpointManager.validate({
-  feature: 'user-auth',
-  validators: ['architecture-expert', 'security-expert'],
-  scope: 'full' // Check all files, not just deltas
-});
-
-console.log('✅ Feature complete: user-auth');
-console.log(`📊 Metrics:
-  - Total Duration: 47 minutes
-  - Tool Calls: 247 (82/checkpoint avg)
-  - Parallel Efficiency: 78% (3 concurrent threads)
-  - Improvement: 2.8x faster than sequential
-`);
-```
-
----
-
-### Scenario 3: Fusion Feature (F-Thread for High Confidence)
-
-**User Request:** `morph-spec feature create auth-system --request "design authentication (need high confidence)" --workflow=fusion`
-
-#### Step-by-Step Execution:
-
-```javascript
-// 1. Fusion Executor Setup
-const fusionConfig = {
-  agentCount: 3,
-  models: ['opus-4.6', 'sonnet-4.5', 'sonnet-4.5'],
-  aggregationStrategy: 'best-of-n',
-  criteria: {
-    checkpointPassRate: 0.4,  // 40% weight
-    codeQuality: 0.3,          // 30% weight
-    completeness: 0.3          // 30% weight
-  }
-};
-
-// 2. Spawn 3 Fusion Threads
-const fusionThreads = await fusionExecutor.spawn({
-  feature: 'auth-system',
-  phase: 'design',
-  prompt: 'Design authentication system with JWT tokens and refresh token rotation',
-  config: fusionConfig
-});
-
-console.log(`✓ Spawned ${fusionThreads.length} fusion threads (best-of-3)`);
-
-// 3. Execute in Parallel (Sandboxed)
-const designs = await Promise.all([
-  executeFusionThread(fusionThreads[0], 'opus-4.6'),   // Agent 1: Approach A
-  executeFusionThread(fusionThreads[1], 'sonnet-4.5'), // Agent 2: Approach B
-  executeFusionThread(fusionThreads[2], 'sonnet-4.5')  // Agent 3: Approach C
-]);
-
-console.log(`✓ Generated 3 design approaches:`);
-console.log(`  - Design A (Opus): JWT with HttpOnly cookies + CSRF`);
-console.log(`  - Design B (Sonnet): JWT in Authorization header + XSS protection`);
-console.log(`  - Design C (Sonnet): Session-based with Redis`);
-
-// 4. Validation & Scoring
-const scores = await Promise.all(
-  designs.map(async (design, index) => {
-    // Run validators on each design
-    const validation = await checkpointManager.validate({
-      feature: `auth-system-design-${index}`,
-      validators: ['architecture-expert', 'security-expert'],
-      files: design.files
-    });
-
-    // Calculate scores
-    const checkpointScore = validation.passed ? 1.0 : 0.0;
-    const qualityScore = await codeAnalyzer.analyze(design.files);
-    const completenessScore = calculateCompleteness(design);
-
-    const totalScore =
-      checkpointScore * fusionConfig.criteria.checkpointPassRate +
-      qualityScore * fusionConfig.criteria.codeQuality +
-      completenessScore * fusionConfig.criteria.completeness;
-
-    return {
-      design,
-      scores: { checkpoint: checkpointScore, quality: qualityScore, completeness: completenessScore },
-      totalScore
-    };
-  })
-);
-
-console.log(`📊 Scoring Results:`);
-scores.forEach((result, i) => {
-  console.log(`  Design ${String.fromCharCode(65 + i)}: ${(result.totalScore * 100).toFixed(1)}%`);
-  console.log(`    - Checkpoint: ${(result.scores.checkpoint * 100).toFixed(0)}%`);
-  console.log(`    - Quality: ${(result.scores.quality * 100).toFixed(0)}%`);
-  console.log(`    - Completeness: ${(result.scores.completeness * 100).toFixed(0)}%`);
-});
-
-// 5. Aggregation (best-of-n)
-const winner = scores.reduce((best, current) =>
-  current.totalScore > best.totalScore ? current : best
-);
-
-console.log(`✅ Winner: Design ${String.fromCharCode(65 + scores.indexOf(winner))} (${(winner.totalScore * 100).toFixed(1)}% score)`);
-
-// 6. Apply Winning Design
-await stateManager.saveDesign({
-  feature: 'auth-system',
-  design: winner.design,
-  metadata: {
-    fusionStrategy: 'best-of-n',
-    candidates: designs.length,
-    winnerScore: winner.totalScore,
-    alternatives: scores.filter(s => s !== winner).map(s => ({
-      score: s.totalScore,
-      files: s.design.files
-    }))
-  }
-});
-
-// 7. Continue with Standard Workflow
-console.log('✓ Design selected. Continuing with implementation...');
-await executePhase('implement', {
-  design: winner.design,
-  context: optimizedContext
-});
-```
-
----
-
-### Scenario 4: Long-Running Autonomous (L-Thread with Stop Hooks)
-
-**User Request:** `morph-spec feature create large-refactor --request "refactor entire data layer (autonomous, run for hours)"`
-
-#### Step-by-Step Execution:
-
-```javascript
-// 1. Workflow Detection
-const workflow = await workflowDetector.analyze({
-  request: "refactor entire data layer (autonomous, run for hours)",
-  keywords: ['autonomous', 'entire', 'hours', 'refactor'],
-  estimatedFiles: 25,
-  estimatedLines: 1200
-});
-
-console.log(`✓ Detected workflow: long-running (95% confidence)`);
-
-// 2. L-Thread Setup with Stop Hooks
-const lThreadConfig = {
-  maxDuration: '4 hours',
-  stopHookInterval: '30min',
-  maxRetries: 5,
-  validationCommand: 'morph-spec validate feature large-refactor',
-  autonomousMode: true
-};
-
-// 3. Start L-Thread
-const thread = await threadManager.createThread({
-  feature: 'large-refactor',
-  type: 'long-running',
-  config: lThreadConfig
-});
-
-console.log('✓ L-Thread started. Running autonomously...');
-console.log('  - Stop hooks enabled (every 30 min)');
-console.log('  - Max duration: 4 hours');
-console.log('  - You will be notified only when complete or if critical issues arise');
-
-// 4. Autonomous Execution Loop
-let iteration = 0;
-let continueExecution = true;
-
-while (continueExecution && iteration < 8) { // Max 8 iterations (4 hours / 30 min)
-  iteration++;
-  console.log(`\n🔄 Iteration ${iteration} started (${new Date().toLocaleTimeString()})`);
-
-  // Agent works for 30 minutes
-  const workResult = await agentExecutor.executeAutonomous({
-    thread: thread.id,
-    duration: '30min',
-    tasks: getRemainingTasks('large-refactor')
-  });
-
-  console.log(`  ✓ Work completed: ${workResult.tasksCompleted} tasks, ${workResult.toolCalls} tool calls`);
-
-  // 5. Stop Hook Triggered (After 30 min)
-  console.log(`  🪝 Stop hook triggered...`);
-
-  const validation = await stopHookExecutor.execute({
-    feature: 'large-refactor',
-    hookPath: 'framework/hooks/agent-stop/validate-and-continue.js',
-    context: {
-      iteration,
-      tasksCompleted: workResult.tasksCompleted,
-      totalTasks: getTotalTasks('large-refactor')
-    }
-  });
-
-  // 6. Validation Decision
-  if (validation.action === 'complete') {
-    console.log(`  ✅ Validation passed. Feature complete!`);
-    continueExecution = false;
-  } else if (validation.action === 'continue') {
-    console.log(`  ⚠️  Validation failed. Continuing with feedback:`);
-    console.log(`     ${validation.feedback}`);
-
-    // Inject feedback into next iteration
-    await agentExecutor.injectFeedback({
-      thread: thread.id,
-      feedback: validation.feedback
-    });
-
-    // Check retry limit
-    if (validation.retries >= lThreadConfig.maxRetries) {
-      console.log(`  ❌ Max retries (${lThreadConfig.maxRetries}) reached. Pausing for user intervention.`);
-      continueExecution = false;
-      await notifyUser('large-refactor', 'Max retries reached, manual review needed');
-    }
-  }
-
-  // 7. Analytics Update
-  await analyticsEngine.recordMetrics({
-    feature: 'large-refactor',
-    iteration,
-    toolCalls: workResult.toolCalls,
-    checkpointPassRate: validation.action === 'complete' ? 1.0 : 0.0
-  });
-}
-
-// 8. Final Report
-const finalMetrics = await analyticsEngine.getFeatureMetrics('large-refactor');
-console.log(`\n✅ L-Thread Complete`);
-console.log(`📊 Final Metrics:`);
-console.log(`  - Total Duration: ${finalMetrics.duration}`);
-console.log(`  - Iterations: ${iteration}`);
-console.log(`  - Tool Calls: ${finalMetrics.totalToolCalls}`);
-console.log(`  - Autonomous Runtime: ${finalMetrics.autonomousPercentage}%`);
-console.log(`  - User Intervention: ${finalMetrics.userInterventions} times`);
-```
-
----
-
-## Code Flow Examples
-
-### Example 1: Thread Manager Core Logic
-
-```javascript
-// src/lib/thread-manager.js
-
-class ThreadManager {
-  constructor(stateManager, analyticsEngine) {
-    this.stateManager = stateManager;
-    this.analyticsEngine = analyticsEngine;
-    this.activeThreads = new Map();
-  }
-
-  /**
-   * Create a new thread for a feature
-   * @param {Object} options - Thread configuration
-   * @returns {Promise<Thread>}
-   */
-  async createThread(options) {
-    const { feature, type, agent, context, config = {} } = options;
-
-    // Generate unique thread ID
-    const threadId = `thread-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
-
-    // Create thread object
-    const thread = {
-      id: threadId,
-      feature,
-      agent,
-      type, // 'base' | 'parallel' | 'fusion' | 'long-running' | 'zero-touch'
-      status: 'pending',
-      startedAt: new Date().toISOString(),
-      completedAt: null,
-      metrics: {
-        toolCalls: 0,
-        duration: null,
-        estimatedCompletion: this.estimateCompletion(type, context)
-      },
-      config
-    };
-
-    // Store in active threads map
-    this.activeThreads.set(threadId, thread);
-
-    // Persist to state.json
-    await this.stateManager.update({
-      threads: {
-        [threadId]: thread
-      }
-    });
-
-    // Start analytics tracking
-    await this.analyticsEngine.startTracking(threadId);
-
-    return thread;
-  }
-
-  /**
-   * Determine thread type based on workflow and complexity
-   * @param {Object} criteria - Decision criteria
-   * @returns {Promise<string>} Thread type
-   */
-  async determineType(criteria) {
-    const { workflow, complexity, estimatedFiles, parallelizable = true } = criteria;
-
-    // Decision tree for thread type
-    if (workflow === 'fusion' || criteria.highConfidenceNeeded) {
-      return 'fusion';
-    }
-
-    if (workflow === 'long-running' || criteria.autonomousMode) {
-      return 'long-running';
-    }
-
-    if (workflow === 'zero-touch' || criteria.trustLevel === 'maximum') {
-      return 'zero-touch';
-    }
-
-    // Check if parallel execution is beneficial
-    if (parallelizable && estimatedFiles >= 10 && complexity === 'high') {
-      return 'parallel';
-    }
-
-    // Default to base thread (sequential)
-    return 'base';
-  }
-
-  /**
-   * Get status of all threads for a feature
-   * @param {string} featureName - Feature name
-   * @returns {Promise<Object>} Status object
-   */
-  async getStatus(featureName) {
-    const state = await this.stateManager.getFeature(featureName);
-    const threads = Object.values(state.threads || {}).filter(
-      t => t.feature === featureName
-    );
-
-    // Calculate aggregated metrics
-    const totalToolCalls = threads.reduce((sum, t) => sum + t.metrics.toolCalls, 0);
-    const avgParallelThreads = threads.length > 1 ? threads.length : 1;
-
-    return {
-      feature: featureName,
-      threads: threads.map(t => ({
-        id: t.id,
-        agent: t.agent,
-        status: t.status,
-        progress: this.calculateProgress(t),
-        metrics: t.metrics
-      })),
-      aggregated: {
-        totalToolCalls,
-        avgParallelThreads,
-        parallelEfficiency: this.calculateEfficiency(threads)
-      }
-    };
-  }
-
-  /**
-   * Calculate parallel execution efficiency
-   * @param {Array<Thread>} threads - Thread instances
-   * @returns {number} Efficiency percentage (0-100)
-   */
-  calculateEfficiency(threads) {
-    if (threads.length <= 1) return 100; // Sequential is 100% efficient by definition
-
-    const maxDuration = Math.max(...threads.map(t => this.parseDuration(t.metrics.duration)));
-    const totalDuration = threads.reduce((sum, t) => sum + this.parseDuration(t.metrics.duration), 0);
-
-    // Theoretical speedup: totalDuration / maxDuration
-    // Actual speedup accounts for coordination overhead
-    const theoreticalSpeedup = totalDuration / maxDuration;
-    const actualSpeedup = threads.length; // Number of parallel threads
-
-    return Math.round((actualSpeedup / theoreticalSpeedup) * 100);
-  }
-
-  async killThread(threadId) {
-    const thread = this.activeThreads.get(threadId);
-    if (!thread) throw new Error(`Thread ${threadId} not found`);
-
-    thread.status = 'killed';
-    thread.completedAt = new Date().toISOString();
-
-    await this.stateManager.update({
-      threads: {
-        [threadId]: thread
-      }
-    });
-
-    this.activeThreads.delete(threadId);
-  }
-}
-
-export default ThreadManager;
-```
-
----
-
-### Example 2: Context Optimizer Implementation
-
-```javascript
-// src/lib/context-optimizer.js
-
-class ContextOptimizer {
-  constructor(mcpOptimizer, standardsLoader, templateRegistry) {
-    this.mcpOptimizer = mcpOptimizer;
-    this.standardsLoader = standardsLoader;
-    this.templateRegistry = templateRegistry;
-  }
-
-  /**
-   * Prime context for a feature
-   * @param {Object} options - Priming options
-   * @returns {Promise<Object>} Optimized context
-   */
-  async prime(options) {
-    const { featureType, domain, agents = [], standards = [] } = options;
-
-    // 1. Select appropriate prime file
-    const primeFile = this.selectPrimeFile(featureType);
-    const primeContent = await fs.readFile(primeFile, 'utf-8');
-
-    // 2. MCP Hygiene - Remove unused servers
-    const activeMcpServers = await this.mcpOptimizer.detectActive();
-    const unusedServers = await this.mcpOptimizer.findUnused();
-
-    console.log(`  MCP Hygiene: ${activeMcpServers.length} active, ${unusedServers.length} unused`);
-
-    // 3. Selective Standards Loading
-    const relevantStandards = standards.length > 0
-      ? standards
-      : await this.selectStandards(domain, featureType);
-
-    const standardsContent = await Promise.all(
-      relevantStandards.map(s => this.standardsLoader.load(s))
-    );
-
-    // 4. Select Agents
-    const relevantAgents = agents.length > 0
-      ? agents
-      : await this.selectAgents(domain, featureType);
-
-    // 5. Calculate token counts
-    const tokens = {
-      prime: this.countTokens(primeContent),
-      standards: standardsContent.reduce((sum, s) => sum + this.countTokens(s), 0),
-      agents: relevantAgents.length * 50, // Estimate
-      total: 0
-    };
-    tokens.total = tokens.prime + tokens.standards + tokens.agents;
-
-    console.log(`  Context Optimized:`);
-    console.log(`    - Prime file: ${tokens.prime} tokens`);
-    console.log(`    - Standards: ${tokens.standards} tokens (${relevantStandards.length} files)`);
-    console.log(`    - Agents: ${tokens.agents} tokens (${relevantAgents.length} agents)`);
-    console.log(`    - Total: ${tokens.total} tokens (vs 23K baseline = ${Math.round((1 - tokens.total/23000) * 100)}% reduction)`);
-
-    return {
-      prime: primeContent,
-      standards: relevantStandards,
-      standardsContent,
-      agents: relevantAgents,
-      mcpServers: activeMcpServers,
-      tokens
-    };
-  }
-
-  /**
-   * Select prime file based on feature type
-   * @param {string} featureType - Type of feature (feature/bug/refactor/design/infra)
-   * @returns {string} Path to prime file
-   */
-  selectPrimeFile(featureType) {
-    const primeFiles = {
-      feature: '.morph/context/feature-prime.md',
-      bug: '.morph/context/bug-prime.md',
-      refactor: '.morph/context/refactor-prime.md',
-      design: '.morph/context/design-prime.md',
-      infra: '.morph/context/infra-prime.md'
-    };
-
-    return primeFiles[featureType] || primeFiles.feature;
-  }
-
-  /**
-   * Select relevant standards based on domain
-   * @param {string} domain - Primary domain (backend/frontend/infrastructure/etc.)
-   * @param {string} featureType - Feature type
-   * @returns {Promise<Array<string>>} List of standard file paths
-   */
-  async selectStandards(domain, featureType) {
-    const domainMap = {
-      backend: [
-        'core/coding.md',
-        'core/architecture.md',
-        'backend/dotnet/core.md',
-        'backend/api/minimal-api.md'
-      ],
-      frontend: [
-        'core/coding.md',
-        'frontend/blazor/lifecycle.md',
-        'frontend/design-system/naming.md'
-      ],
-      infrastructure: [
-        'core/coding.md',
-        'infrastructure/azure/bicep-patterns.md',
-        'infrastructure/docker/dockerfile.md'
-      ],
-      data: [
-        'core/coding.md',
-        'backend/database/ef-core.md',
-        'backend/database/migrations.md'
-      ]
-    };
-
-    return domainMap[domain] || domainMap.backend;
-  }
-
-  /**
-   * Create context bundle for checkpoint
-   * @param {string} featureName - Feature name
-   * @param {number} checkpoint - Checkpoint number
-   * @returns {Promise<Object>} Bundle metadata
-   */
-  async createBundle(featureName, checkpoint) {
-    const state = await stateManager.getFeature(featureName);
-
-    // Compress context into bundle
-    const bundle = {
-      bundleId: `${featureName}-checkpoint-${checkpoint}`,
-      timestamp: new Date().toISOString(),
-      compressedContext: {
-        decisions: state.decisions || [],
-        artifacts: state.artifacts || [],
-        tasksCompleted: state.tasks.filter(t => t.status === 'done').map(t => t.id),
-        nextSteps: state.tasks.filter(t => t.status === 'pending').slice(0, 3)
-      },
-      fullContextPath: `.morph/bundles/${featureName}-checkpoint-${checkpoint}.json`,
-      replayTokens: 0 // Will be calculated
-    };
-
-    // Save full context to file
-    await fs.writeFile(
-      bundle.fullContextPath,
-      JSON.stringify(state, null, 2),
-      'utf-8'
-    );
-
-    // Calculate replay tokens (compressed vs full)
-    const fullTokens = this.countTokens(JSON.stringify(state));
-    const compressedTokens = this.countTokens(JSON.stringify(bundle.compressedContext));
-
-    bundle.replayTokens = compressedTokens;
-    bundle.savings = Math.round((1 - compressedTokens / fullTokens) * 100);
-
-    console.log(`  ✓ Context bundle created: ${bundle.bundleId}`);
-    console.log(`    - Full context: ${fullTokens} tokens`);
-    console.log(`    - Compressed: ${compressedTokens} tokens`);
-    console.log(`    - Savings: ${bundle.savings}%`);
-
-    return bundle;
-  }
-
-  countTokens(text) {
-    // Rough estimation: 1 token ≈ 4 characters
-    return Math.ceil(text.length / 4);
-  }
-}
-
-export default ContextOptimizer;
-```
-
----
-
-## State Management Flow
-
-### state.json Structure (Runtime)
-
-```json
-{
-  "version": "3.0.0",
-  "project": {
-    "name": "MyApp",
-    "type": "blazor-server",
-    "createdAt": "2026-02-18T10:00:00Z",
-    "updatedAt": "2026-02-18T14:30:00Z"
-  },
-
-  "threads": {
-    "thread-001": {
-      "id": "thread-001",
-      "feature": "user-auth",
-      "agent": "dotnet-senior",
-      "type": "parallel",
-      "status": "running",
-      "startedAt": "2026-02-18T10:05:00Z",
-      "completedAt": null,
-      "metrics": {
-        "toolCalls": 42,
-        "duration": null,
-        "estimatedCompletion": "2026-02-18T11:30:00Z"
-      }
-    },
-    "thread-002": {
-      "id": "thread-002",
-      "feature": "user-auth",
-      "agent": "blazor-builder",
-      "type": "parallel",
-      "status": "running",
-      "startedAt": "2026-02-18T10:05:00Z",
-      "completedAt": null,
-      "metrics": {
-        "toolCalls": 28,
-        "duration": null,
-        "estimatedCompletion": "2026-02-18T11:15:00Z"
-      }
-    }
-  },
-
-  "features": {
-    "user-auth": {
-      "name": "user-auth",
-      "workflow": "full-morph",
-      "phase": "implement",
-      "status": "active",
-      "request": "implement complete authentication system with JWT",
-      "createdAt": "2026-02-18T10:00:00Z",
-
-      "threadMetrics": {
-        "totalToolCalls": 247,
-        "threadDuration": "2h 15m",
-        "maxParallelThreads": 3,
-        "avgParallelThreads": 2.1,
-        "checkpointPassRate": 1.0
-      },
-
-      "trustConfig": {
-        "level": "high",
-        "autoApprove": {
-          "design": true,
-          "tasks": false
-        },
-        "reason": "95% checkpoint pass rate on similar features",
-        "history": [
-          { "feature": "product-catalog", "passRate": 1.0, "timestamp": "2026-02-15T14:00:00Z" },
-          { "feature": "order-mgmt", "passRate": 0.95, "timestamp": "2026-02-16T16:00:00Z" }
-        ]
-      },
-
-      "contextBundles": [
-        {
-          "bundleId": "user-auth-checkpoint-1",
-          "checkpoint": 1,
-          "timestamp": "2026-02-18T11:00:00Z",
-          "path": ".morph/bundles/user-auth-checkpoint-1.json",
-          "replayTokens": 12000,
-          "savings": 85
-        }
-      ],
-
-      "tasks": [
-        {
-          "id": "T001",
-          "description": "Create User entity",
-          "status": "done",
-          "agent": "ef-modeler",
-          "thread": "thread-001",
-          "completedAt": "2026-02-18T10:30:00Z"
-        },
-        {
-          "id": "T002",
-          "description": "Create AuthController",
-          "status": "in_progress",
-          "agent": "api-designer",
-          "thread": "thread-001",
-          "startedAt": "2026-02-18T10:31:00Z"
-        }
-      ],
-
-      "approvals": {
-        "design": {
-          "status": "auto-approved",
-          "reason": "high trust level (95% pass rate)",
-          "timestamp": "2026-02-18T10:45:00Z"
-        },
-        "tasks": {
-          "status": "pending",
-          "reason": "awaiting user approval",
-          "timestamp": null
-        }
-      }
-    }
-  },
-
-  "metadata": {
-    "totalFeatures": 12,
-    "completedFeatures": 9,
-    "activeFeatures": 3,
-    "totalCostEstimated": 0,
-    "totalTimeSpent": 0,
-    "lastUpdated": "2026-02-18T14:30:00Z"
-  }
-}
-```
-
-### State Transitions
-
-```javascript
-// State machine for feature phases
-const phaseTransitions = {
-  'proposal': ['setup'],
-  'setup': ['uiux', 'design'],
-  'uiux': ['design'],
-  'design': ['clarify'],  // Only if approved
-  'clarify': ['tasks'],
-  'tasks': ['implement'], // Only if approved
-  'implement': ['sync', 'archived'],
-  'sync': ['archived']
-};
-
-// State updates flow
-async function advancePhase(featureName, nextPhase) {
-  const state = await stateManager.getFeature(featureName);
-
-  // 1. Validate transition
-  if (!phaseTransitions[state.phase].includes(nextPhase)) {
-    throw new Error(`Invalid transition: ${state.phase} → ${nextPhase}`);
-  }
-
-  // 2. Check approval gates
-  if (nextPhase === 'clarify' && state.approvals.design.status !== 'approved') {
-    throw new Error('Design gate not approved');
-  }
-
-  if (nextPhase === 'implement' && state.approvals.tasks.status !== 'approved') {
-    throw new Error('Tasks gate not approved');
-  }
-
-  // 3. Update state
-  await stateManager.update({
-    features: {
-      [featureName]: {
-        phase: nextPhase,
-        updatedAt: new Date().toISOString()
-      }
-    }
-  });
-
-  console.log(`✓ Phase advanced: ${state.phase} → ${nextPhase}`);
-}
-```
-
----
-
-## Key Classes & Interfaces
-
-### Core Interfaces
-
-```typescript
-// src/types/thread.ts
-interface Thread {
-  id: string;
-  feature: string;
-  agent: string;
-  type: 'base' | 'parallel' | 'fusion' | 'long-running' | 'zero-touch';
-  status: 'pending' | 'running' | 'completed' | 'failed' | 'killed';
-  startedAt: string; // ISO8601
-  completedAt: string | null;
-  metrics: ThreadMetrics;
-  config?: Record<string, any>;
-}
-
-interface ThreadMetrics {
-  toolCalls: number;
-  duration: string | null;
-  estimatedCompletion: string | null;
-}
-
-// src/types/context.ts
-interface OptimizedContext {
-  prime: string;
-  standards: string[];
-  standardsContent: string[];
-  agents: string[];
-  mcpServers: string[];
-  tokens: {
-    prime: number;
-    standards: number;
-    agents: number;
-    total: number;
-  };
-}
-
-// src/types/analytics.ts
-interface FeatureMetrics {
-  feature: string;
-  totalToolCalls: number;
-  threadDuration: string;
-  maxParallelThreads: number;
-  avgParallelThreads: number;
-  checkpointPassRate: number;
-}
-```
-
----
-
-## Summary
-
-This execution flow document shows how MORPH-SPEC v3.0 will work in practice:
-
-**Runtime Components:**
-- Thread Manager orchestrates concurrent execution
-- Context Optimizer reduces tokens by 30-40%
-- Parallel/Fusion Executors enable 3-5x throughput
-- Stop Hooks enable hours-long autonomous runs
-- Trust Manager enables 50% auto-approvals
-- Analytics Engine tracks everything in real-time
-
-**State Flow:**
-- Centralized in state.json (single source of truth)
-- State machine enforces valid phase transitions
-- Approval gates check trust levels for auto-approval
-- Context bundles enable efficient session replay
-
-**Code Architecture:**
-- Modular classes with clear responsibilities
-- Async/await throughout for parallel execution
-- Event-driven hooks for validation
-- Real-time metrics tracking
-
-The finished framework will be a **highly orchestrated, data-driven system** that scales through parallelization, optimizes through context engineering, and improves through analytics - all while maintaining backward compatibility with v2.x.
-
----
-
-*MORPH-SPEC v3.0 Execution Flow - by Polymorphism Tech*