@polymorphism-tech/morph-spec 3.1.0 → 4.2.0

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

@@ -0,0 +1,1304 @@
+# 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*