@polymorphism-tech/morph-spec 2.4.0 → 3.0.0

package/content/.morph/docs/workflows/enforcement-pipeline.md

@@ -0,0 +1,668 @@
+# Standards Enforcement Pipeline
+
+> MORPH-SPEC 3.0 Phases 1-6 Implementation
+
+Comprehensive enforcement pipeline that guarantees code quality and standards compliance through automated validation gates.
+
+---
+
+## Overview
+
+The enforcement pipeline consists of **6 integrated phases** that work together to ensure all code follows MORPH standards without manual checking:
+
+| Phase | Component | When | What |
+|-------|-----------|------|------|
+| **1** | Data-Driven Validators | FASE 5 (task done) | Maps agents → validators via agents.json |
+| **2** | Standards Context Injector | Agent detection | Auto-loads 55k+ chars of standards per agent |
+| **3** | Design System Enforcement | FASE 5 gate | Blocks UI features without design system |
+| **4** | Spec-Time Validation | FASE 2 gate | Validates contracts.cs before implementation |
+| **5** | Standards Optimization | N/A | Optimized standards (23% token reduction) |
+| **6** | Comprehensive Testing | All phases | 242 tests, 100% pass rate |
+
+**Total Files:** 20 modules | **Tests:** 242 | **Token Savings:** ~5k per agent activation
+
+---
+
+## Phase 1: Data-Driven Validators
+
+### Problem Solved
+
+Before: Hardcoded AGENT_VALIDATOR_MAP in validation-runner.js made it impossible to customize validator behavior without code changes.
+
+**After:** Single source of truth in `agents.json` - modify validator mapping without touching code.
+
+### Implementation
+
+**agents.json structure:**
+```json
+{
+  "agents": {
+    "blazor-builder": {
+      "validators": ["architecture", "blazor", "blazor-concurrency", "blazor-state", "css", "design-system"]
+    },
+    "standards-architect": {
+      "validators": ["architecture", "packages"]
+    }
+  }
+}
+```
+
+**validation-runner.js behavior:**
+1. `loadAgentValidatorMap(projectPath)` reads agents.json
+2. `detectValidators(featureName)` loads feature's activeAgents from state.json
+3. Maps agents → validators using data-driven map
+4. Runs each validator with options (including decision constraints)
+
+### Usage
+
+```bash
+# Validators run automatically on task completion
+morph-spec task done my-feature T001
+
+# To customize: edit content/.morph/config/agents.json
+{
+  "my-custom-agent": {
+    "validators": ["architecture", "custom-validator"]
+  }
+}
+```
+
+**Benefits:**
+- No code changes to add/remove validators
+- Per-agent validator customization
+- Fail-fast on missing agents.json (honest failure)
+
+---
+
+## Phase 2: Standards Context Injector
+
+### Problem Solved
+
+Before: Specialists had to manually read standards files, often missing relevant patterns.
+
+**After:** All relevant standards automatically loaded into agent context (55k+ chars for blazor-builder).
+
+### Implementation
+
+**standards-context-injector.js:**
+```javascript
+export function loadStandardsForAgent(agentId, projectPath) {
+  // Resolution order:
+  // 1. .morph/project/standards/{file}.md (project overrides)
+  // 2. content/.morph/standards/{file}.md (content standards)
+  // 3. framework/standards/{file}.md (framework standards)
+
+  return {
+    sections: [...],        // Array of { standard, content }
+    fullContent: string,    // Concatenated standards (55k+ chars)
+    standardNames: [...]    // List of loaded standards
+  };
+}
+```
+
+**Agent → Standards Mapping:**
+| Agent | Standards Loaded |
+|-------|------------------|
+| `blazor-builder` | blazor-lifecycle, blazor-state, blazor-efcore, blazor-pitfalls, html-to-blazor, fluent-ui-blazor, css-*, coding, architecture |
+| `ai-system-architect` | agent-framework-*, architecture, coding |
+| `azure-architect` | azure, architecture, dotnet10-compatibility |
+| `ms-agent-expert` | agent-framework-*, coding, architecture |
+
+### Usage
+
+```bash
+# Standards auto-injected when running detect-agents with --json
+npx morph-spec detect-agents --json "create blazor dashboard"
+
+# Output includes standardsSummary for each agent:
+{
+  "standardsSummary": {
+    "blazor-builder": {
+      "fullContent": "... 55304 characters ...",
+      "sections": [...]
+    }
+  }
+}
+```
+
+**Benefits:**
+- Zero manual context loading
+- Always up-to-date standards
+- Project-specific overrides supported
+- No token waste (200k context available)
+
+---
+
+## Phase 3: Design System Enforcement
+
+### Problem Solved
+
+Before: UI features implemented with hardcoded colors, inconsistent styling, no design tokens.
+
+**After:** Gate blocks implementation without design system; validator detects violations.
+
+### Components
+
+**1. design-system-detector.js**
+- Checks 4 levels (priority order):
+  1. Feature-level: `.morph/project/outputs/{feature}/ui-design-system.md`
+  2. Project-level: `.morph/project/design-system.md`
+  3. Generated CSS: `wwwroot/css/design-system.css`
+  4. Existing CSS variables: scans `.css` files for `--app-*` tokens
+
+**2. design-system-scaffolder.js**
+- Auto-creates design system from template
+- Scans existing CSS for color variables
+- Populates with sensible defaults
+
+**3. design-system-validator.js**
+- Parses design system tokens (colors, typography, spacing)
+- Scans CSS/Razor for hardcoded colors
+- Detects inline `style=""` attributes
+- Reports violations with file:line references
+
+**4. Gate in advance-phase.js**
+```javascript
+if (nextPhase === 'implement') {
+  const gateResult = designSystemGate(feature);
+  if (gateResult.blocked) {
+    // Block advancement + show solutions
+    process.exit(1);
+  }
+}
+```
+
+### Usage
+
+```bash
+# Gate blocks automatically if UI agents active without design system
+morph-spec phase advance my-ui-feature
+
+# Output:
+# ✗ Cannot advance to implementation — UI agents are active but no design system found
+#
+# Create a design system with one of these options:
+#   1. Project-level: .morph/project/design-system.md
+#   2. Feature-level: .morph/project/outputs/my-ui-feature/ui-design-system.md
+#   3. Auto-generate: morph-spec generate design-system
+
+# Auto-scaffold design system
+morph-spec generate design-system                    # Project-level
+morph-spec generate design-system my-ui-feature      # Feature-level
+```
+
+**Benefits:**
+- No hardcoded colors in production
+- Consistent design tokens
+- Auto-scaffolding from existing CSS
+- Clear error messages with solutions
+
+---
+
+## Phase 4: Spec-Time Validation
+
+### Problem Solved
+
+Before: C# coding violations only discovered during code review or runtime.
+
+**After:** contracts.cs validated at FASE 2 (design phase) before any implementation.
+
+### Validation Rules
+
+**spec-validator.js enforces 7 rules:**
+
+1. **CancellationToken Required**
+   ```csharp
+   // ❌ WRONG
+   public async Task<Order> GetOrderAsync(int id)
+
+   // ✅ CORRECT
+   public async Task<Order> GetOrderAsync(int id, CancellationToken ct = default)
+   ```
+
+2. **PascalCase Constants**
+   ```csharp
+   // ❌ WRONG
+   private const int MAX_RETRY_COUNT = 3;
+
+   // ✅ CORRECT
+   private const int MaxRetryCount = 3;
+   ```
+
+3. **Async Suffix**
+   ```csharp
+   // ❌ WRONG
+   public async Task ProcessOrder(int id)
+
+   // ✅ CORRECT
+   public async Task ProcessOrderAsync(int id)
+   ```
+
+4. **Sealed Classes**
+   ```csharp
+   // ⚠️ WARNING
+   public class OrderService { }
+
+   // ✅ CORRECT
+   public sealed class OrderService { }
+   ```
+
+5. **DTOs as Records**
+   ```csharp
+   // ⚠️ WARNING
+   public class OrderResponse { }
+
+   // ✅ CORRECT
+   public record OrderResponse(int Id, string Status);
+   ```
+
+6. **Interface Naming**
+   ```csharp
+   // ❌ WRONG
+   public interface OrderService { }
+
+   // ✅ CORRECT
+   public interface IOrderService { }
+   ```
+
+7. **Required Spec Sections**
+   - Overview
+   - Functional Requirements
+   - Non-Functional Requirements
+   - Technical Architecture
+   - Data Model
+
+### Gate Integration
+
+```javascript
+// advance-phase.js
+if (currentPhase === 'design' && (nextPhase === 'clarify' || nextPhase === 'tasks')) {
+  const specValidation = await validateSpec('.', feature);
+  if (specValidation.errors > 0) {
+    // Block advancement + show violations
+    process.exit(1);
+  }
+}
+```
+
+### Usage
+
+```bash
+# Runs automatically when advancing from design phase
+morph-spec phase advance my-feature
+
+# Manual validation
+morph-spec validate-spec my-feature
+
+# Output example:
+# ❌ Validation FAILED - 6 errors, 3 warnings
+#
+# Errors:
+# 1. ❌ [contracts] Async method 'GetOrderAsync' missing CancellationToken parameter
+#    💡 Solution: Add 'CancellationToken ct = default' parameter
+# 2. ❌ [contracts] Constant 'MAX_RETRY_COUNT' uses UPPER_SNAKE_CASE
+#    💡 Solution: Use PascalCase: 'MaxRetryCount'
+```
+
+**Benefits:**
+- Catches violations before implementation
+- Saves code review time
+- Enforces Microsoft C# guidelines
+- Actionable error messages
+
+---
+
+## Phase 5: Standards Optimization
+
+### Problem Solved
+
+Before: Standards files verbose (1761 lines total), wasting tokens on redundant explanations and emojis.
+
+**After:** 23% reduction (405 lines removed), optimized for LLM consumption.
+
+### Optimization Techniques
+
+1. **Removed Emojis** (per user feedback: "not necessary for LLMs")
+   ```markdown
+   <!-- Before -->
+   | ✅ Correct | ❌ Wrong |
+
+   <!-- After -->
+   | Correct | Wrong |
+   ```
+
+2. **Comparison Tables**
+   ```markdown
+   <!-- Before -->
+   **WRONG:** Using UPPER_SNAKE_CASE for constants
+   **CORRECT:** Use PascalCase instead
+
+   <!-- After -->
+   | Wrong | Right |
+   |-------|-------|
+   | `MAX_RETRY_COUNT` | `MaxRetryCount` |
+   ```
+
+3. **Condensed Code Examples**
+   ```markdown
+   <!-- Before: 15 lines with comments + boilerplate -->
+   public class OrderService
+   {
+       // Constructor with dependency injection
+       private readonly IOrderRepository _repository;
+       public OrderService(IOrderRepository repository)
+       {
+           _repository = repository;
+       }
+
+       // Main method
+       public async Task<Order> GetAsync(int id) { ... }
+   }
+
+   <!-- After: 3 lines, essential pattern only -->
+   public sealed class OrderService(IOrderRepository repository)
+   {
+       public async Task<Order> GetAsync(int id, CancellationToken ct = default)
+           => await repository.GetByIdAsync(id, ct);
+   }
+   ```
+
+4. **Removed Meta-Commentary**
+   - Kept: "what" and "how"
+   - Removed: verbose "why" explanations, pattern origins, historical context
+
+### Results
+
+| File | Before | After | Reduction |
+|------|--------|-------|-----------|
+| coding.md | 320 | 211 | 109 lines (34%) |
+| blazor-pitfalls.md | 254 | 143 | 111 lines (44%) |
+| architecture.md | 227 | 183 | 44 lines (19%) |
+| blazor-efcore.md | 227 | 173 | 54 lines (24%) |
+| css-naming.md | 108 | 62 | 46 lines (43%) |
+| blazor-lifecycle.md | 172 | 159 | 13 lines (7.6%) |
+| blazor-state.md | 164 | 161 | 3 lines (1.8%) |
+| css-animations.md | 157 | 149 | 8 lines (5.1%) |
+| dotnet10-compatibility.md | 132 | 115 | 17 lines (12.9%) |
+| **TOTAL** | **1761** | **1356** | **405 lines (23%)** |
+
+**Token Savings:** ~5,063 tokens per agent activation (when standards loaded via Phase 2)
+
+---
+
+## Phase 6: Comprehensive Testing
+
+### Test Coverage
+
+**18 test files, 242 tests total, 100% pass rate:**
+
+| Test File | Tests | Coverage |
+|-----------|-------|----------|
+| standards-context-injector.test.js | 15 | Agent→standards mapping, project overrides |
+| design-system-detector.test.js | 10 | 4-level detection priority |
+| design-system-scaffolder.test.js | 12 | Template + CSS scanning |
+| design-system-validator.test.js | 12 | Color detection, inline styles |
+| spec-validator.test.js | 12 | 7 C# coding rules |
+| validation-runner.test.js | 20 | Constraint injection, data-driven map |
+| advance-phase-design-gate.test.js | 8 | Design system gate |
+| advance-phase-spec-gate.test.js | 8 | Spec validation gate |
+| contract-compliance-validator.test.js | 15 | Contract parsing + checking |
+| decision-constraint-loader.test.js | 10 | ADR parsing |
+| + 8 existing test files | 120 | Complexity analyzer, context generator, etc. |
+
+### Integration Tests
+
+**6 verification tasks completed:**
+1. ✅ Run Tests (242/242 passing)
+2. ✅ Data-Driven Validator Map (agents.json → validators)
+3. ✅ Decision Wiring (decisions.md → constraints → validators)
+4. ✅ Design System Gate (blocks UI features without design system)
+5. ✅ Spec Validator (detects 9 C# violations in test)
+6. ✅ Standards Injector (55k+ chars loaded for blazor-builder)
+
+---
+
+## Integration Points
+
+### Complete Data Flow
+
+```
+1. User creates feature
+   ↓
+2. detect-agents --json → agents registered in state.json
+   ↓ (standards-context-injector loads 55k+ chars per agent)
+   ↓
+3. FASE 2: Design → spec.md + contracts.cs created
+   ↓
+4. Spec validator runs → blocks if C# violations found
+   ↓ (decisions.md ADRs parsed → constraints extracted)
+   ↓
+5. FASE 4: Tasks → advance-phase checks prerequisites
+   ↓
+6. FASE 5: Implement → design system gate blocks if UI agents + no design system
+   ↓
+7. Each `task done` → validation-runner orchestrates validators
+   ↓ (validators use: agents.json mapping + decision constraints + standards content)
+   ↓
+8. Validation results → per-validator details + summary
+   ↓
+9. Checkpoint includes validation summary
+```
+
+### Enforcement Levels
+
+| Level | Mechanism | When | Action |
+|-------|-----------|------|--------|
+| **Soft** | Standards context injection | Agent detection | Auto-load 55k+ chars of standards |
+| **Medium** | Validators | `task done` | Detect violations, show warnings |
+| **Hard** | Gates | `phase advance` | Block on critical failures (spec, design system) |
+
+---
+
+## Commands Reference
+
+### Automatic Execution
+
+```bash
+# Validators run automatically
+morph-spec task done {feature} {task-id}
+
+# Gates run automatically
+morph-spec phase advance {feature}
+```
+
+### Manual Validation
+
+```bash
+# Run all validators for a feature
+morph-spec validate {feature}
+
+# Run specific validator
+morph-spec validate {feature} --validator=blazor
+
+# Verbose output
+morph-spec validate {feature} --verbose
+
+# Validate spec/contracts only
+morph-spec validate-spec {feature}
+
+# Check design system
+morph-spec validate-design-system {feature}
+```
+
+### Emergency Bypass
+
+**⚠️ ONLY with explicit user authorization:**
+
+```bash
+# Skip validation (emergencies only)
+morph-spec task done {feature} {task-id} --skip-validation
+
+# Ignore warnings (not errors)
+morph-spec phase advance {feature} --skip-warnings
+```
+
+---
+
+## Troubleshooting
+
+### Validator Not Running
+
+**Symptom:** Expected validator didn't run for task completion
+
+**Check:**
+1. Is agent active? `morph-spec state get {feature}` → check activeAgents
+2. Is validator mapped? Check `content/.morph/config/agents.json` → agent's `validators` array
+3. Is agents.json readable? Run `morph-spec validate-agents-skills`
+
+**Fix:**
+```bash
+# Add agent to feature
+morph-spec state add-agent {feature} {agent-id}
+
+# Or edit agents.json directly
+{
+  "my-agent": {
+    "validators": ["architecture", "custom-validator"]
+  }
+}
+```
+
+### Gate Blocking Unexpectedly
+
+**Symptom:** Design system gate blocks even though design system exists
+
+**Check:**
+1. Detection order: feature > project > generated > existing CSS
+2. File location: `.morph/project/design-system.md` or `.morph/project/outputs/{feature}/ui-design-system.md`
+3. Format: Must have `# Design System` or `## Colors` sections
+
+**Fix:**
+```bash
+# Create design system
+morph-spec generate design-system {feature}
+
+# Or manually create .morph/project/design-system.md with:
+# # Design System
+# ## Colors
+# - primary: #007bff
+```
+
+### Spec Validation False Positives
+
+**Symptom:** Spec validator reports violations for valid code
+
+**Common cases:**
+- Method intentionally doesn't have CancellationToken (event handler, constructor)
+- Constant should be UPPER_CASE (external API constant)
+- DTO should be class (EF Core entity)
+
+**Fix:**
+```bash
+# Skip validation for this task (with user approval)
+morph-spec task done {feature} {task-id} --skip-validation
+
+# Or update contracts.cs to match coding.md standards
+```
+
+---
+
+## Extending the Pipeline
+
+### Adding a Custom Validator
+
+**1. Create validator file:**
+```javascript
+// src/lib/validators/my-custom-validator.js
+export async function validateMyCustom(projectPath, featureName, options) {
+  return {
+    passed: true,
+    errors: 0,
+    warnings: 0,
+    issues: []
+  };
+}
+```
+
+**2. Register in validation-runner.js:**
+```javascript
+case 'my-custom': {
+  const { validateMyCustom } = await import('./validators/my-custom-validator.js');
+  return await validateMyCustom(projectPath, featureName, options);
+}
+```
+
+**3. Map to agents in agents.json:**
+```json
+{
+  "my-agent": {
+    "validators": ["architecture", "my-custom"]
+  }
+}
+```
+
+**4. Add tests:**
+```javascript
+// test/lib/validators/my-custom-validator.test.js
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { validateMyCustom } from '../../../src/lib/validators/my-custom-validator.js';
+
+describe('MyCustomValidator', () => {
+  it('should pass valid code', async () => {
+    const result = await validateMyCustom('.', 'test-feature');
+    assert.strictEqual(result.passed, true);
+  });
+});
+```
+
+### Adding a Custom Gate
+
+**1. Add gate function in advance-phase.js:**
+```javascript
+function myCustomGate(feature, projectPath = '.') {
+  // Check condition
+  if (conditionNotMet) {
+    return {
+      blocked: true,
+      message: 'Cannot advance - custom gate failed',
+      solution: ['Do X', 'Or do Y']
+    };
+  }
+  return { blocked: false };
+}
+```
+
+**2. Call gate before phase transition:**
+```javascript
+if (nextPhase === 'my-target-phase') {
+  const gateResult = myCustomGate(feature);
+  if (gateResult.blocked) {
+    // Show error + exit
+  }
+}
+```
+
+---
+
+## Performance Considerations
+
+**Token Usage:**
+- Phase 2 (Standards Injector): ~55k chars per agent = ~14k tokens
+- 200k context window = room for 14 agents with full standards + code
+- Phase 5 (Optimization): Saved ~5k tokens per agent activation
+
+**Execution Time:**
+- Validators: ~100-500ms per validator (fast)
+- Gates: ~50-100ms per gate (very fast)
+- Standards injection: One-time cost at agent detection
+
+**Test Suite:**
+- 242 tests run in ~665ms total
+- Parallel test execution
+- No performance regressions
+
+---
+
+*MORPH-SPEC Standards Enforcement Pipeline v3.0*
+*Documentation generated: 2026-02-13*