@polymorphism-tech/morph-spec 4.8.14 → 4.8.15

package/framework/standards/frontend/design-system/aesthetic-direction.md

@@ -0,0 +1,213 @@
+# Aesthetic Direction
+
+> **Scope:** universal
+> **Layer:** 0 (always load)
+> **Keywords:** design, aesthetic, typography, color, motion, identity, visual
+> **Load When:** phase-uiux
+
+## Design Thinking Methodology
+
+Antes de qualquer especificação técnica, responder 4 perguntas para definir direção estética:
+
+1. **Purpose** — Que problema resolve? Quem usa? Qual o contexto profissional?
+2. **Tone** — Qual direção? (ver tabela Aesthetic Directions abaixo)
+3. **Differentiation** — Qual o 1 elemento memorável desta interface?
+4. **Constraints** — Framework, performance budget, brand guidelines existentes
+
+**CRITICAL:** Commitar à direção ANTES das specs técnicas. Documentar em `ui-design-system.md`
+na seção `## Aesthetic Direction` usando o template no final deste standard.
+
+---
+
+## Aesthetic Directions (Enterprise-Adapted)
+
+| Direction | Feel | Typography | Color | Motion |
+|-----------|------|-----------|-------|--------|
+| **Minimal Refined** | Luxuoso, silencioso, preciso | Serif elegante + sans leve | Monocromático + 1 accent sharp | Transitions suaves, sem floreios |
+| **Editorial** | Magazine profissional, opinionado | Display forte + body serifado | Contrastes altos, tipo tipográfico | Reveals dramáticos, scroll-driven |
+| **Soft Professional** | Acolhedor, confiável, humano | Sans rounded + body neutro | Pastéis quentes + accent vibrante | Entrada gentil, micro-interações sutis |
+| **Industrial** | Técnico, funcional, direto | Mono/condensed + utility sans | Neutros + accent de alerta | Sem animação ou movimento mínimo |
+| **Modern Luxury** | Exclusivo, refinado, material | Display itálico + sans premium | Escuro profundo + gold/copper accent | Parallax sutil, hover lift, shine effect |
+
+> **Nota:** Sem "brutalist chaos" — este guia é adaptado para contexto enterprise.
+
+---
+
+## Typography
+
+### Princípios
+
+- **Display font DISTINTIVA**: define o caráter da interface — evitar fontes genéricas como display
+- **Body font LEGÍVEL**: otimizada para leitura de conteúdo, densidade de informação
+- **Contraste de peso**: heading e body devem ter pesos visivelmente diferentes
+
+### Font Pairs por Direção
+
+| Direction | Display | Body | Fonte |
+|-----------|---------|------|-------|
+| Minimal Refined | Cormorant Garamond | DM Sans | Google Fonts |
+| Editorial | Playfair Display | Source Sans 3 | Google Fonts |
+| Soft Professional | Nunito | Inter | Google Fonts |
+| Industrial | JetBrains Mono | IBM Plex Sans | Google Fonts |
+| Modern Luxury | Bodoni Moda | Sora | Google Fonts |
+
+### Anti-padrões
+
+- ❌ Inter ou Roboto como fonte de display (genérico, sem caráter)
+- ❌ System fonts sem razão arquitetural explícita
+- ❌ Mesmo peso para heading e body (sem hierarquia)
+- ❌ Mais de 2 famílias de fontes sem justificativa visual clara
+
+---
+
+## Color Philosophy
+
+### Estrutura
+
+```
+1 dominant (60%) + 1 sharp accent (10%) + semantic colors (30%)
+```
+
+- **Dominant**: define o mood — não precisa ser "segura", precisa ser intencional
+- **Sharp accent**: cria tensão e foco — deve contrastar com dominant
+- **Semantic**: success, warning, error, info — seguir WCAG AA (4.5:1 mínimo)
+
+### Template CSS Variables
+
+```css
+:root {
+  /* Dominant palette */
+  --color-primary: #1a1a2e;
+  --color-primary-light: #16213e;
+  --color-primary-dark: #0f3460;
+
+  /* Sharp accent */
+  --color-accent: #e94560;
+  --color-accent-hover: #c73652;
+
+  /* Surface */
+  --color-surface: #ffffff;
+  --color-surface-alt: #f8f9fa;
+  --color-border: rgba(0,0,0,0.08);
+
+  /* Semantic */
+  --color-success: #22c55e;
+  --color-warning: #f59e0b;
+  --color-error: #ef4444;
+  --color-info: #3b82f6;
+
+  /* Text */
+  --color-text-primary: #1a1a1a;
+  --color-text-secondary: #6b7280;
+  --color-text-muted: #9ca3af;
+}
+```
+
+### Anti-padrões
+
+- ❌ Gradiente roxo em fundo branco (AI cliché #1)
+- ❌ Paleta de 5 cores de peso igual (sem dominant + accent)
+- ❌ Cinza neutro como "cor segura" sem intenção estética
+- ❌ Accent color igual ao primary (sem tensão visual)
+
+---
+
+## Motion Principles
+
+### Filosofia
+
+> 1 page-load bem orquestrado > micro-interações espalhadas por todo lado
+
+Criar delight através de momentos específicos, não movimento constante.
+
+### High-Impact Patterns
+
+| Pattern | Implementação | Quando usar |
+|---------|--------------|-------------|
+| **Entry stagger** | `animation-delay: 0.05s * index`, `animation-fill-mode: backwards` | Listas, cards, grids |
+| **Hover lift** | `transform: translateY(-4px)`, `box-shadow: var(--shadow-lg)` | Cards interativos, CTAs |
+| **Success bounce** | `@keyframes bounce` com `cubic-bezier(0.68, -0.55, 0.265, 1.55)` | Confirmações, saves |
+| **Data reveal** | `clip-path: inset(0 100% 0 0)` → `inset(0 0% 0 0)` | Métricas, progressos |
+
+### Acessibilidade (obrigatório)
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+> **Ref:** `framework/standards/frontend/design-system/animations.md` para keyframes e patterns completos.
+
+### Anti-padrões
+
+- ❌ Animação em absolutamente tudo (motion fatigue)
+- ❌ Transitions > 500ms para interações de UI comuns
+- ❌ Sem `prefers-reduced-motion` (acessibilidade obrigatória)
+- ❌ `animation-fill-mode` ausente em stagger (causa flash)
+
+---
+
+## Spatial Composition
+
+### Padrões por Tipo de Página
+
+**Feature Hero** — Produto, landing, showcase:
+- Elemento central oversized (tipografia ou visual)
+- Generous negative space ao redor
+- 1 elemento grid-breaking (overlap, diagonal, fora do ritmo)
+
+**Dashboard** — Métricas, dados, monitoramento:
+- Controlled density — cada cm² carrega informação
+- Hierarquia clara: KPIs > charts > tabelas
+- Micro-grid consistente (8px ou 4px base)
+
+**Form Pages** — Input, configuração, onboarding:
+- Campo único em foco (single-column preferred)
+- Progress visual explícito
+- Espaço generoso entre grupos de campos
+
+### Princípio Fundamental
+
+> Generous negative space OU controlled density — nunca o "meio-termo confortável"
+
+Interfaces no meio-termo parecem vazias E confusas ao mesmo tempo.
+
+---
+
+## Visual Atmosphere
+
+Técnicas por direção para criar profundidade e caráter:
+
+| Direction | Técnica Principal | Detalhe |
+|-----------|-----------------|---------|
+| Minimal Refined | Subtle noise texture | `filter: url(#noise)` SVG ou `backdrop-filter` |
+| Editorial | Dramatic type shadows | `text-shadow` em display com offset grande |
+| Soft Professional | Frosted glass cards | `backdrop-filter: blur(12px)`, `background: rgba(...)` |
+| Industrial | Hard borders + grid lines | `border: 1px solid`, sem arredondamento, monospace |
+| Modern Luxury | Gradient mesh background | Multi-stop radial gradients sobrepostos |
+
+---
+
+## Template de Documentação
+
+Usar no `ui-design-system.md` de cada feature (seção `## Aesthetic Direction`):
+
+```markdown
+## Aesthetic Direction
+
+- **Direction**: [Minimal Refined / Editorial / Soft Professional / Industrial / Modern Luxury]
+- **Tone**: [1-2 frases sobre o feel — ex: "Sóbrio e confiante, como um produto B2B premium"]
+- **Differentiator**: [O que torna memorável — ex: "Entrada staggered dos cards + tipografia editorial forte"]
+- **Font Pair**: [Display font] + [Body font]
+- **Color Philosophy**: [Dominant] + [Accent] — [rationale de 1 frase]
+- **Motion Intent**: [Padrão de entrada + interações-chave]
+- **Composition**: [Abordagem de layout — ex: "Dashboard controlled density, 8px grid"]
+```
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/templates/project/validate.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+/**
+ * bin/validate.js — generated by morph-spec setup-infra
+ *
+ * Thin validator entry-point called by morph-spec validate-completion hook:
+ *   node bin/validate.js <validator> [--json]
+ *
+ * Supported validators: architecture, blazor, blazor-concurrency, nextjs-component,
+ *   packages, design-system, ui-contrast, css
+ *
+ * Exits 0 on pass, 1 on validation errors.
+ * --json flag prints structured JSON to stdout.
+ */
+
+const validator = process.argv[2];
+const isJson = process.argv.includes('--json');
+
+if (!validator) {
+  console.error('Usage: node bin/validate.js <validator> [--json]');
+  process.exit(1);
+}
+
+const { execSync } = await import('child_process');
+const { existsSync } = await import('fs');
+const { join } = await import('path');
+
+const cwd = process.cwd();
+
+const results = {
+  validator,
+  errors: 0,
+  warnings: 0,
+  passed: true,
+  issues: [],
+};
+
+/**
+ * Run a shell command and capture output.
+ * Returns { success, stdout, stderr }.
+ */
+function runCommand(cmd, options = {}) {
+  try {
+    const stdout = execSync(cmd, { cwd, stdio: ['pipe', 'pipe', 'pipe'], ...options }).toString();
+    return { success: true, stdout, stderr: '' };
+  } catch (err) {
+    return {
+      success: false,
+      stdout: err.stdout?.toString() || '',
+      stderr: err.stderr?.toString() || err.message,
+    };
+  }
+}
+
+// ── Stack detection ───────────────────────────────────────────────────────────
+
+const hasFrontend = existsSync(join(cwd, 'src/frontend')) || existsSync(join(cwd, 'frontend'));
+const hasBackend  = existsSync(join(cwd, 'src/backend'))  || existsSync(join(cwd, 'backend'));
+const hasSln      = existsSync(join(cwd, 'src/backend/backend.sln')) ||
+                    existsSync(join(cwd, 'src/backend/Backend.sln'));
+
+const frontendDir = existsSync(join(cwd, 'src/frontend')) ? 'src/frontend' : 'frontend';
+const backendDir  = existsSync(join(cwd, 'src/backend'))  ? 'src/backend'  : 'backend';
+
+// ── Validator dispatch ────────────────────────────────────────────────────────
+
+switch (validator) {
+  case 'architecture':
+  case 'blazor':
+  case 'blazor-concurrency': {
+    if (hasBackend && hasSln) {
+      const slnFile = hasSln ? (
+        existsSync(join(cwd, 'src/backend/backend.sln')) ? 'backend.sln' : 'Backend.sln'
+      ) : '.';
+      const result = runCommand(`dotnet build ${slnFile} --no-restore -warnaserror`, { cwd: join(cwd, backendDir) });
+      if (!result.success) {
+        results.errors++;
+        results.passed = false;
+        results.issues.push({ level: 'error', message: `dotnet build failed: ${result.stderr.split('\n')[0]}` });
+      }
+    }
+    break;
+  }
+
+  case 'nextjs-component':
+  case 'packages':
+  case 'design-system': {
+    if (hasFrontend) {
+      const result = runCommand('npx tsc --noEmit', { cwd: join(cwd, frontendDir) });
+      if (!result.success) {
+        results.errors++;
+        results.passed = false;
+        results.issues.push({ level: 'error', message: `TypeScript errors found. Run: npx tsc --noEmit` });
+      }
+    }
+    break;
+  }
+
+  case 'ui-contrast':
+  case 'css': {
+    // CSS/contrast validators are visual — report as informational
+    results.issues.push({ level: 'info', message: `${validator} requires manual review` });
+    break;
+  }
+
+  default:
+    results.issues.push({ level: 'warning', message: `Unknown validator: ${validator}` });
+    break;
+}
+
+// ── Output ────────────────────────────────────────────────────────────────────
+
+if (isJson) {
+  console.log(JSON.stringify(results, null, 2));
+} else {
+  const icon = results.passed ? '✅' : '❌';
+  console.log(`${icon} Validator: ${validator} — ${results.passed ? 'PASSED' : `FAILED (${results.errors} errors)`}`);
+  for (const issue of results.issues) {
+    console.log(`  [${issue.level}] ${issue.message}`);
+  }
+}
+
+process.exit(results.passed ? 0 : 1);

package/framework/workflows/configs/zero-touch.json

@@ -69,6 +69,13 @@
     "requireHumanForSchemaChanges": false
   },
 
+  "phaseChain": {
+    "enabled": true,
+    "pauseOn": ["blocked_tasks", "escalation_required", "low_pass_rate"],
+    "continueOn": ["missing_optional_outputs"],
+    "maxAutoPhases": 6
+  },
+
   "keywords": ["zero-touch", "autonomous", "fully automated", "hands-off", "auto-pilot"],
 
   "priority": 5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "4.8.14",
+  "version": "4.8.15",
   "description": "MORPH-SPEC: AI-First development framework with validation pipeline and multi-stack support",
   "keywords": [
     "claude-code",

package/src/commands/agents/dispatch-agents.js

@@ -20,6 +20,7 @@ import { readFileSync, existsSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { loadState, stateExists } from '../../core/state/state-manager.js';
+import { buildAgentBriefing, buildValidatorPrompt } from '../../lib/standards/digest-builder.js';
 import chalk from 'chalk';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -115,7 +116,7 @@ function getAgentGroup(agentId, agentData) {
  * Check whether an agent should be dispatched for the given phase.
  *
  * Rules (in priority order):
- * 1. Tier-4 validators → never dispatch (no task work)
+ * 1. Tier-4 validators → never dispatch (no task work) [overridden by validate mode]
  * 2. Agent-level `active_phases` array → use that list
  * 3. Relationships-level `active_phases` array → use that list
  * 4. `always_active: true` → dispatchable for all DISPATCHABLE_PHASES
@@ -127,7 +128,7 @@ function getAgentGroup(agentId, agentData) {
  * @returns {boolean}
  */
 function isRelevantForPhase(agentId, agentData, phase) {
-  // Tier-4 validators have no implementation tasks
+  // Tier-4 validators have no implementation tasks (validate mode bypasses this)
   if (agentData.tier === 4) return false;
 
   // Explicit active_phases on agent root
@@ -252,6 +253,7 @@ export async function buildDispatchConfig(projectPath, featureName, phase, opts
 
   // Collect dispatchable agents
   // Process all agents: active ones from state + always_active ones not yet in state
+  const isValidateMode = opts.mode === 'validate';
   const processed = new Set();
   const dispatchableAgents = [];
 
@@ -261,6 +263,12 @@ export async function buildDispatchConfig(projectPath, featureName, phase, opts
     ...Object.entries(allAgents)
       .filter(([id, data]) => !id.startsWith('_comment') && data.always_active)
       .map(([id]) => id),
+    // In validate mode, also include tier-4 validators
+    ...(isValidateMode
+      ? Object.entries(allAgents)
+          .filter(([id, data]) => !id.startsWith('_comment') && data.tier === 4)
+          .map(([id]) => id)
+      : []),
   ];
 
   for (const agentId of candidateIds) {
@@ -270,23 +278,40 @@ export async function buildDispatchConfig(projectPath, featureName, phase, opts
     const agentData = allAgents[agentId];
     if (!agentData || agentId.startsWith('_comment')) continue;
 
-    // Must have a spawn_prompt to be dispatchable
-    if (!agentData.teammate?.spawn_prompt) continue;
+    const isTier4 = agentData.tier === 4;
 
-    // Phase relevance check
-    if (!isRelevantForPhase(agentId, agentData, phase)) continue;
+    // Must have a spawn_prompt (or be a tier-4 with hook_behavior in validate mode)
+    if (!agentData.teammate?.spawn_prompt && !(isValidateMode && isTier4 && agentData.hook_behavior)) continue;
+
+    // Phase relevance check (tier-4 bypass in validate mode)
+    if (!isRelevantForPhase(agentId, agentData, phase) && !(isValidateMode && isTier4)) continue;
 
     const group = getAgentGroup(agentId, agentData);
 
+    // Build task prompt: validator prompt for tier-4 in validate mode, else spawn_prompt
+    let rawPrompt;
+    if (isValidateMode && isTier4) {
+      rawPrompt = buildValidatorPrompt(agentId) || agentData.teammate?.spawn_prompt || '';
+    } else {
+      rawPrompt = agentData.teammate.spawn_prompt;
+    }
+
+    // Append standards digest as Constraints block
+    const briefing = buildAgentBriefing(agentId, phase);
+    const fullTaskPrompt = briefing
+      ? `${rawPrompt}\n\nConstraints:\n${briefing}`
+      : rawPrompt;
+
     dispatchableAgents.push({
       id: agentId,
       title: agentData.title,
       tier: agentData.tier,
-      icon: agentData.teammate.icon || '🤖',
-      role: agentData.teammate.role,
+      icon: agentData.teammate?.icon || '🤖',
+      role: agentData.teammate?.role || agentData.description || '',
       parallelGroup: group,
       canRunParallel: true,
-      taskPrompt: agentData.teammate.spawn_prompt,
+      canWrite: !isTier4,
+      taskPrompt: fullTaskPrompt,
     });
   }
 
@@ -302,6 +327,21 @@ export async function buildDispatchConfig(projectPath, featureName, phase, opts
 
   const shouldDispatch = dispatchableAgents.length >= 2;
 
+  // ── Execution mode recommendation ─────────────────────────────────────────
+  // Derive recommended mode from agent composition:
+  // - 'agent-teams' : 2+ distinct parallel groups AND 5+ total agents (critical multi-domain)
+  // - 'subagents'   : shouldDispatch=true but below agent-teams threshold
+  // - 'single'      : no dispatch benefit
+  const distinctGroups = new Set(dispatchableAgents.map(a => a.parallelGroup)).size;
+  let mode;
+  if (shouldDispatch && distinctGroups >= 2 && dispatchableAgents.length >= 5) {
+    mode = 'agent-teams';
+  } else if (shouldDispatch) {
+    mode = 'subagents';
+  } else {
+    mode = 'single';
+  }
+
   // ── Task groups ────────────────────────────────────────────────────────────
   const taskGroups = {};
 
@@ -340,6 +380,7 @@ export async function buildDispatchConfig(projectPath, featureName, phase, opts
   return {
     feature: featureName,
     phase,
+    mode,
     shouldDispatch,
     reason: shouldDispatch
       ? `${dispatchableAgents.length} dispatchable agents for phase '${phase}'`
@@ -377,7 +418,9 @@ export async function dispatchAgentsCommand(featureName, phase, options = {}) {
   }
 
   try {
-    const config = await buildDispatchConfig(process.cwd(), featureName, normalizedPhase);
+    const dispatchOpts = {};
+    if (options.mode) dispatchOpts.mode = options.mode;
+    const config = await buildDispatchConfig(process.cwd(), featureName, normalizedPhase, dispatchOpts);
 
     if (options.table) {
       // Human-readable table format

package/src/commands/state/advance-phase.js

@@ -362,6 +362,13 @@ export async function advancePhaseCommand(feature, options = {}) {
     // Hook executor unavailable — non-blocking
   }
 
+  // Emit Tier-4 validator dispatch when advancing into implement or sync phase
+  const phasesNeedingValidation = ['implement', 'sync'];
+  if (phasesNeedingValidation.includes(nextPhase) || phasesNeedingValidation.includes(currentPhase)) {
+    const validationPhase = phasesNeedingValidation.includes(nextPhase) ? nextPhase : currentPhase;
+    await emitValidatorDispatch(feature, validationPhase, process.cwd());
+  }
+
   console.log(chalk.green(`\n✓ Advanced to ${nextPhaseDef.name}`));
 
   // Show what's needed in the new phase
@@ -466,3 +473,52 @@ function designSystemGate(feature, projectPath = '.') {
     ]
   };
 }
+
+/**
+ * Emit Tier-4 validation dispatch block after phase advance.
+ * Outputs a JSON block listing active Tier-4 validators for the LLM to dispatch
+ * as read-only subagents before proceeding to implementation.
+ * Non-blocking — fails silently.
+ *
+ * @param {string} featureName
+ * @param {string} phase
+ * @param {string} cwd
+ */
+async function emitValidatorDispatch(featureName, phase, cwd) {
+  try {
+    const { buildDispatchConfig } = await import('../agents/dispatch-agents.js');
+    const config = await buildDispatchConfig(cwd, featureName, phase, { mode: 'validate' });
+    const validators = config.agents?.filter(a => a.tier === 4);
+    if (!validators || validators.length === 0) return;
+
+    const agentsPath = join(__dirname, '../../../framework/agents.json');
+    const agentsData = JSON.parse(readFileSync(agentsPath, 'utf8'));
+    const allAgents = agentsData.agents || {};
+
+    const validatorEntries = validators.map(v => {
+      const agentData = allAgents[v.id];
+      return {
+        id: v.id,
+        title: v.title,
+        severity: agentData?.hook_behavior?.severity || 'error',
+        blocksOnFail: agentData?.hook_behavior?.blocks_on_fail ?? true,
+        checks: agentData?.hook_behavior?.validates || [],
+        taskPrompt: v.taskPrompt
+      };
+    });
+
+    const dispatch = {
+      validationRequired: true,
+      phase,
+      feature: featureName,
+      validators: validatorEntries,
+      instruction: 'Dispatch these validators as READ-ONLY subagents before continuing. Each must output { "passed": boolean, "issues": [] }. Blocking validators (blocksOnFail: true) must pass before marking phase complete.'
+    };
+
+    console.log(chalk.cyan('\n--- VALIDATION DISPATCH ---'));
+    console.log(JSON.stringify(dispatch, null, 2));
+    console.log(chalk.cyan('--- END VALIDATION DISPATCH ---\n'));
+  } catch {
+    // Non-blocking — fail silently
+  }
+}

package/src/commands/state/index.js

@@ -3,5 +3,6 @@
  */
 export { stateCommand } from './state.js';
 export { advancePhaseCommand } from './advance-phase.js';
-export { approveCommand, rejectCommand, approvalStatusCommand } from './approve.js';
+export { approveCommand, unapproveCommand, approvalStatusCommand } from './approve.js';
 export { validatePhaseCommand } from './validate-phase.js';
+export { phaseRunCommand } from './phase-runner.js';