@polymorphism-tech/morph-spec 3.2.0 → 4.3.0

package/stacks/blazor-azure/.morph/docs/workflows/enforcement-pipeline.md

@@ -1,668 +0,0 @@
-# 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 .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. .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 `.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*

package/stacks/blazor-azure/.morph/docs/workflows/fast-track.md

@@ -1,29 +0,0 @@
-# Workflow: FAST TRACK (Trivial)
-
-> **Layer:** 1 | **Load:** on-keyword | **Keywords:** bug, fix, corrigir, ajustar, hotfix, edge case, cor, css
-
-## Critérios
-
-- ≤ 3 arquivos modificados, ≤ 50 linhas, 0 novos componentes
-- Sem infraestrutura, sem decisões arquiteturais
-
-## Fases
-
-### 1. Quick Analysis (FASE 0+1+2 combinadas)
-- Identifica problema em 2-3 parágrafos
-- Propõe solução direta
-- **PAUSA:** Aprovar ou ajustar?
-
-### 2. Implement & Test
-- Implementa diretamente
-- Testa
-- Cria commit descritivo
-
-## Outputs
-Nenhum (ou apenas commit message detalhado)
-
-## Exemplos
-- "Corrigir validação de CPF no formulário"
-- "Ajustar cor do botão primário"
-- "Hotfix: null pointer na home"
-- "Edge case: validação quando campo vazio"