pumuki 6.3.311 → 6.3.313

package/AGENTS.md

@@ -159,6 +159,10 @@ Antes de realizar cualquier accion:
   - crear commits atomicos separados o stashes con nombre explicito antes de continuar,
   - no usar un commit masivo para "limpiar" el estado.
 - Antes de cada commit:
+  - confirmar RED registrado o justificar que es cambio documental puro;
+  - confirmar GREEN con test focal ejecutado;
+  - confirmar REFACTOR acotado y gobernado por las skills aplicables;
+  - confirmar VERIFY con typecheck/compilacion/build aplicable;
   - revisar `git diff --cached --name-status`,
   - confirmar que todos los archivos staged pertenecen a la misma intencion,
   - dejar fuera del stage cualquier archivo no relacionado,
@@ -174,9 +178,28 @@ Antes de realizar cualquier accion:
   - preservar cambios en commit o stash con nombre explicito,
   - y reportar la evidencia.
 
+## Golden Flow TDD / Red-Green-Refactor (flujo principal no negociable)
+- Pumuki es primero un orquestador de flujo seguro de ingenieria: las skills son reglas de calidad dentro de este flujo, no sustituyen el flujo.
+- Todo cambio funcional, bugfix de gate/lifecycle, detector AST/nodal, notificacion, hook, policy o codigo de producto debe seguir obligatoriamente:
+  1. `RED`: crear o actualizar primero un test/regresion que falle por el bug o comportamiento esperado.
+  2. `GREEN`: tocar el minimo codigo de produccion necesario para hacer pasar ese test.
+  3. `REFACTOR`: limpiar solo dentro del alcance de la slice, sin cambiar comportamiento.
+  4. `VERIFY`: ejecutar test focal y compilacion/typecheck/build aplicable.
+  5. `COMMIT ATOMICO`: cerrar una unica intencion funcional o tecnica.
+- La fase `REFACTOR` debe aplicar las skills de plataforma correspondientes:
+  - iOS/Swift/SwiftUI: `ios-enterprise-rules`, `swift-concurrency`, `swiftui-expert-skill`; y `swift-testing-expert`, `core-data-expert` o skills Apple adicionales cuando aplique.
+  - Android: `android-enterprise-rules`.
+  - Frontend: `frontend-enterprise-rules`.
+  - Backend: `backend-enterprise-rules`.
+- Esta prohibido commitear codigo funcional sin test focal ejecutado y verde.
+- Esta prohibido publicar release o repinear consumers si el test focal, typecheck o build aplicable fallan.
+- Si no es tecnicamente posible escribir RED antes de tocar produccion, declarar `STATUS: BLOCKED` o documentar una excepcion explicita y trazable antes de continuar.
+- Cambios documentales puros pueden omitir RED, pero deben mantener diff acotado, trazabilidad y commit atomico.
+
 ## Gate operativo obligatorio (antes de editar codigo)
 - Declarar internamente las skills aplicables y tratarlas como activas durante TODO el turno.
 - Verificar cumplimiento minimo previo:
+  - Golden Flow TDD `RED -> GREEN -> REFACTOR -> VERIFY -> COMMIT ATOMICO` requerido para todo cambio funcional.
   - BDD/TDD requerido por la skill correspondiente.
   - Concurrencia y aislamiento segun `swift-concurrency` cuando haya codigo Swift.
   - Estado/arquitectura/UI segun `swiftui-expert-skill` e `ios-enterprise-rules` cuando aplique iOS/SwiftUI.

package/integrations/sdd/evidenceScaffold.ts

@@ -39,6 +39,10 @@ export type SddEvidenceScaffoldResult = {
         status: SddEvidenceScaffoldTestStatus;
         timestamp: string;
       };
+      verify: {
+        status: SddEvidenceScaffoldTestStatus;
+        timestamp: string;
+      };
     }>;
     metadata: {
       source: 'pumuki-sdd-evidence';
@@ -226,6 +230,10 @@ export const runSddEvidenceScaffold = (params?: {
           status: testStatus,
           timestamp: generatedAt,
         },
+        verify: {
+          status: testStatus,
+          timestamp: generatedAt,
+        },
       },
     ],
     metadata: {

package/integrations/tdd/contract.ts

@@ -17,6 +17,7 @@ const tddSliceSchema = z.object({
   red: tddEventSchema,
   green: tddEventSchema,
   refactor: tddEventSchema,
+  verify: tddEventSchema.optional(),
 });
 
 const tddIntegritySchema = z.object({

package/integrations/tdd/enforcement.ts

@@ -96,15 +96,21 @@ export const enforceTddBddPolicy = (params: {
         public_interface_files: scope.metrics.publicInterfaceFiles,
       },
     },
-    evidence: {
-      path: '',
-      state: 'not_required',
-      slices_total: 0,
-      slices_valid: 0,
-      slices_invalid: 0,
-      integrity_ok: true,
-      errors: [],
-    },
+      evidence: {
+        path: '',
+        state: 'not_required',
+        slices_total: 0,
+        slices_valid: 0,
+        slices_invalid: 0,
+        integrity_ok: true,
+        errors: [],
+        phases: {
+          red: 'missing',
+          green: 'missing',
+          refactor: 'missing',
+          verify: 'missing',
+        },
+      },
     waiver: {
       applied: false,
     },
@@ -163,7 +169,7 @@ export const enforceTddBddPolicy = (params: {
       ruleId: 'generic_evidence_integrity_required',
       code: 'TDD_BDD_EVIDENCE_MISSING',
       message:
-        'TDD/BDD evidence contract is required for new/complex changes and was not found.',
+        'Golden Flow evidence is required for functional code changes and was not found. Required phases: RED failed, GREEN passed, REFACTOR passed, VERIFY passed.',
       filePath: evidenceRead.path,
     });
     return {
@@ -207,6 +213,12 @@ export const enforceTddBddPolicy = (params: {
   const sliceFindings: Finding[] = [];
   const seenSliceIds = new Set<string>();
   let validSlices = 0;
+  const phaseState: NonNullable<TddBddSnapshot['evidence']['phases']> = {
+    red: 'missing',
+    green: 'missing',
+    refactor: 'missing',
+    verify: 'missing',
+  };
 
   if (evidenceRead.evidence.slices.length === 0) {
     sliceFindings.push(
@@ -258,6 +270,7 @@ export const enforceTddBddPolicy = (params: {
     }
 
     if (slice.red.status !== 'failed') {
+      phaseState.red = slice.red.status;
       sliceFindings.push(
         buildFinding({
           ruleId: 'generic_tdd_vertical_required',
@@ -266,8 +279,12 @@ export const enforceTddBddPolicy = (params: {
           filePath: evidenceRead.path,
         })
       );
+    } else {
+      phaseState.red = 'failed';
     }
 
+    phaseState.green = slice.green.status;
+    phaseState.refactor = slice.refactor.status;
     if (slice.green.status !== 'passed' || slice.refactor.status !== 'passed') {
       sliceFindings.push(
         buildFinding({
@@ -279,18 +296,42 @@ export const enforceTddBddPolicy = (params: {
       );
     }
 
+    if (!slice.verify) {
+      sliceFindings.push(
+        buildFinding({
+          ruleId: 'generic_golden_flow_verify_required',
+          code: 'GOLDEN_FLOW_VERIFY_EVIDENCE_MISSING',
+          message: `Slice ${slice.id} must include VERIFY passing evidence after REFACTOR.`,
+          filePath: evidenceRead.path,
+        })
+      );
+    } else {
+      phaseState.verify = slice.verify.status;
+      if (slice.verify.status !== 'passed') {
+        sliceFindings.push(
+          buildFinding({
+            ruleId: 'generic_golden_flow_verify_required',
+            code: 'GOLDEN_FLOW_VERIFY_MUST_PASS',
+            message: `Slice ${slice.id} must finish with VERIFY passing evidence.`,
+            filePath: evidenceRead.path,
+          })
+        );
+      }
+    }
+
     if (
       !isTimelineOrdered([
         slice.red.timestamp,
         slice.green.timestamp,
         slice.refactor.timestamp,
+        slice.verify?.timestamp,
       ])
     ) {
       sliceFindings.push(
         buildFinding({
           ruleId: 'generic_red_green_refactor_enforced',
           code: 'TDD_PHASE_TIMELINE_INVALID',
-          message: `Slice ${slice.id} has invalid RED->GREEN->REFACTOR timestamp ordering.`,
+          message: `Slice ${slice.id} has invalid RED->GREEN->REFACTOR->VERIFY timestamp ordering.`,
           filePath: evidenceRead.path,
         })
       );
@@ -320,6 +361,7 @@ export const enforceTddBddPolicy = (params: {
         slices_invalid: invalidSlices,
         integrity_ok: evidenceRead.integrity.valid,
         errors: sliceFindings.map((finding) => finding.code),
+        phases: phaseState,
       },
       waiver: {
         applied: false,

package/integrations/tdd/scope.ts

@@ -154,6 +154,9 @@ export const classifyTddBddScope = (
   }
 
   const reasons: string[] = [];
+  if (changedImplementationPaths.size > 0) {
+    reasons.push('functional.implementation_changed');
+  }
   if (changedImplementationPaths.size > thresholds.maxChangedFiles) {
     reasons.push('complex.changed_files_threshold');
   }
@@ -168,9 +171,9 @@ export const classifyTddBddScope = (
   }
 
   const isNewFeature = addedImplementationPaths.size > 0;
-  const isComplexChange = reasons.length > 0;
+  const isComplexChange = reasons.some((reason) => reason.startsWith('complex.'));
   return {
-    inScope: isNewFeature || isComplexChange,
+    inScope: changedImplementationPaths.size > 0,
     isNewFeature,
     isComplexChange,
     reasons,

package/integrations/tdd/types.ts

@@ -21,6 +21,12 @@ export type TddBddSnapshot = {
     slices_invalid: number;
     integrity_ok: boolean;
     errors: string[];
+    phases?: {
+      red: 'missing' | 'passed' | 'failed';
+      green: 'missing' | 'passed' | 'failed';
+      refactor: 'missing' | 'passed' | 'failed';
+      verify: 'missing' | 'passed' | 'failed';
+    };
   };
   waiver: {
     applied: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pumuki",
-  "version": "6.3.311",
+  "version": "6.3.313",
   "description": "Enterprise-grade AST Intelligence System with multi-platform support (iOS, Android, Backend, Frontend) and Feature-First + DDD + Clean Architecture enforcement. Includes dynamic violations API for intelligent querying.",
   "main": "index.js",
   "bin": {

package/scripts/framework-menu-system-notifications-macos-dialog-payload.ts

@@ -27,7 +27,10 @@ const buildBlockingCausesDetails = (
     ? 'Causas bloqueantes: 1'
     : `Causas bloqueantes: ${total}`;
   return resolvePrioritizedBlockingCauses(causes)
-    .flatMap((cause, index) => formatBlockingCauseForDialog(cause, index))
+    .flatMap((cause, index) => {
+      const formatted = formatBlockingCauseForDialog(cause, index);
+      return index === 0 ? formatted : ['', ...formatted];
+    })
     .reduce((lines, line) => [...lines, line], [header])
     .join('\n');
 };
@@ -49,10 +52,48 @@ const stripTechnicalFieldsFromMessage = (message: string): string => {
     .replace(/\blines?=[0-9][0-9,\-\s]*/gi, '')
     .replace(/\bmessage=/gi, '')
     .replace(/\bremediation=/gi, '')
+    .replace(/\bmissing=\[[^\]]*\]/gi, '')
+    .replace(/\bsnippet=.+$/gi, '')
+    .replace(/\bnode=.+$/gi, '')
+    .replace(/\bprimary_node=.+$/gi, '')
     .replace(/\s+/g, ' ')
     .trim();
 };
 
+const extractFieldFromCauseMessage = (message: string, field: string): string | null => {
+  const escapedField = field.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = message.match(new RegExp(`\\b${escapedField}=([^\\n]+?)(?=\\s(?:severity|code|rule|file|lines?|message|remediation|snippet|node|primary_node|missing)=|$)`, 'i'));
+  const value = match?.[1]?.trim();
+  return value && value.length > 0 ? normalizeNotificationText(value) : null;
+};
+
+const extractSnippetFromCauseMessage = (message: string): string | null =>
+  extractFieldFromCauseMessage(message, 'snippet') ??
+  extractFieldFromCauseMessage(message, 'node') ??
+  extractFieldFromCauseMessage(message, 'primary_node');
+
+const extractMissingContractFromCauseMessage = (message: string): string | null => {
+  const missing = extractFieldFromCauseMessage(message, 'missing')?.replace(/\]\]$/u, ']');
+  if (!missing) {
+    return null;
+  }
+  return `Falta: ${missing}`;
+};
+
+const buildEvidenceLine = (
+  cause: NonNullable<Extract<PumukiCriticalNotificationEvent, { kind: 'gate.blocked' }>['blockingCauses']>[number]
+): string | null => {
+  const snippet = extractSnippetFromCauseMessage(cause.message);
+  if (snippet) {
+    return `   Evidencia: ${truncateNotificationText(snippet, 160)}`;
+  }
+  const missing = extractMissingContractFromCauseMessage(cause.message);
+  if (missing) {
+    return `   Evidencia: ${truncateNotificationText(missing, 160)}`;
+  }
+  return null;
+};
+
 const formatLocation = (cause: NonNullable<Extract<PumukiCriticalNotificationEvent, { kind: 'gate.blocked' }>['blockingCauses']>[number]): string => {
   if (!cause.file) {
     return 'sin fichero';
@@ -61,6 +102,47 @@ const formatLocation = (cause: NonNullable<Extract<PumukiCriticalNotificationEve
   return line ? `${cause.file}:${line}` : cause.file;
 };
 
+const humanizeRuleId = (ruleId: string): string => {
+  const knownRules: Record<string, string> = {
+    'prefer-swift-testing': 'Swift Testing',
+    'no-xctassert': 'XCTest assertions',
+    'no-wait-for-expectations': 'waitForExpectations en XCTest',
+    'ios-test-quality': 'calidad de tests iOS',
+    'dynamic-type-font-scaling-automatico': 'Dynamic Type',
+    'dynamic-type-fuentes-escalables-y-layouts-adaptativos': 'fuentes escalables y layouts adaptativos',
+    'use-relative-layout-over-hard-coded-constants': 'layout relativo en vez de constantes fijas',
+    'magic-numbers-usar-constantes-con-nombres': 'números mágicos sin constantes con nombre',
+    'prefer-static-member-lookup-blue-vs-color-blue': 'colores semánticos en SwiftUI',
+  };
+  const normalized = ruleId
+    .replace(/^skills\./u, '')
+    .replace(/^governance\./u, '')
+    .replace(/^ai_gate\./u, '')
+    .replace(/_/gu, '-');
+  const parts = normalized.split('.').filter(Boolean);
+  const leaf = parts.at(-1) ?? normalized;
+  if (knownRules[leaf]) {
+    return knownRules[leaf];
+  }
+  return leaf
+    .replace(/-/gu, ' ')
+    .replace(/\bios\b/giu, 'iOS')
+    .replace(/\bui\b/giu, 'UI')
+    .replace(/\bapi\b/giu, 'API')
+    .replace(/\btdd\b/giu, 'TDD')
+    .replace(/\bsdd\b/giu, 'SDD')
+    .replace(/\bguard\b/giu, 'guard')
+    .trim();
+};
+
+const formatVisibleRule = (
+  cause: NonNullable<Extract<PumukiCriticalNotificationEvent, { kind: 'gate.blocked' }>['blockingCauses']>[number]
+): string => {
+  const ruleId = cause.ruleId ?? cause.code;
+  const readable = humanizeRuleId(ruleId);
+  return readable.length > 0 ? readable : ruleId;
+};
+
 const isWorktreeHygieneCause = (
   cause: NonNullable<Extract<PumukiCriticalNotificationEvent, { kind: 'gate.blocked' }>['blockingCauses']>[number]
 ): boolean =>
@@ -68,16 +150,78 @@ const isWorktreeHygieneCause = (
   cause.code === 'EVIDENCE_PREWRITE_WORKTREE_OVER_LIMIT' ||
   (cause.ruleId ?? '').includes('EVIDENCE_PREWRITE_WORKTREE');
 
+const isGoldenFlowCause = (
+  cause: NonNullable<Extract<PumukiCriticalNotificationEvent, { kind: 'gate.blocked' }>['blockingCauses']>[number]
+): boolean =>
+  cause.code.startsWith('GOLDEN_FLOW_') ||
+  cause.code.startsWith('TDD_') ||
+  (cause.ruleId ?? '').includes('golden_flow') ||
+  (cause.ruleId ?? '').startsWith('generic_tdd_') ||
+  (cause.ruleId ?? '').startsWith('generic_red_green_refactor');
+
+const isSkillCause = (
+  cause: NonNullable<Extract<PumukiCriticalNotificationEvent, { kind: 'gate.blocked' }>['blockingCauses']>[number]
+): boolean =>
+  (cause.ruleId ?? '').startsWith('skills.') ||
+  cause.code.startsWith('SKILLS_');
+
 const WORKTREE_HYGIENE_REMEDIATION =
   'Reduce el worktree pendiente a un slice atómico: stagea solo la tarea activa o guarda el resto en stash nombrado, y reejecuta PRE_WRITE.';
 
+const GOLDEN_FLOW_REMEDIATION =
+  'Ejecuta los tests de la implementación. Si están en verde, haz un commit atómico de los cambios.';
+
+const normalizeGoldenFlowMissingToken = (message: string): string => {
+  const missing = (extractMissingContractFromCauseMessage(message) ?? 'VERIFY passed')
+    .replace(/^Falta:\s*/u, '');
+  return missing.toUpperCase();
+};
+
+const formatGoldenFlowMissing = (message: string): string => {
+  const missing = normalizeGoldenFlowMissingToken(message);
+  if (missing.includes('RED')) {
+    return 'fase RED del ciclo TDD sin implementar';
+  }
+  if (missing.includes('GREEN')) {
+    return 'fase GREEN del ciclo TDD sin implementar';
+  }
+  if (missing.includes('REFACTOR')) {
+    return 'fase REFACTOR del ciclo TDD sin implementar';
+  }
+  if (missing.includes('VERIFY')) {
+    return 'tests finales en verde sin ejecutar antes del commit';
+  }
+  return missing.toLowerCase();
+};
+
+const formatGoldenFlowRemediation = (message: string): string => {
+  const missing = normalizeGoldenFlowMissingToken(message);
+  if (missing.includes('RED')) {
+    return 'Implementa la fase RED antes de continuar. Las fases del ciclo TDD (RED, GREEN, REFACTOR) deben completarse para desbloquear.';
+  }
+  if (missing.includes('GREEN')) {
+    return 'Implementa la fase GREEN antes de continuar. Haz el cambio mínimo para que el test pase y continúa el ciclo TDD.';
+  }
+  if (missing.includes('REFACTOR')) {
+    return 'Implementa la fase REFACTOR antes de continuar. Limpia la solución manteniendo los tests en verde.';
+  }
+  if (missing.includes('VERIFY')) {
+    return GOLDEN_FLOW_REMEDIATION;
+  }
+  return 'Completa el ciclo TDD en orden: RED, GREEN, REFACTOR y tests finales en verde antes del commit.';
+};
+
+
 const formatBlockingCauseForDialog = (
   cause: NonNullable<Extract<PumukiCriticalNotificationEvent, { kind: 'gate.blocked' }>['blockingCauses']>[number],
   index: number
 ): readonly string[] => {
   const rule = cause.ruleId ?? cause.code;
+  const visibleRule = formatVisibleRule(cause);
   const problem = stripTechnicalFieldsFromMessage(cause.message) || cause.code;
-  const remediation = isWorktreeHygieneCause(cause)
+  const remediation = isGoldenFlowCause(cause)
+    ? GOLDEN_FLOW_REMEDIATION
+    : isWorktreeHygieneCause(cause)
     ? WORKTREE_HYGIENE_REMEDIATION
     : cause.remediation
     ? normalizeNotificationText(cause.remediation)
@@ -90,13 +234,22 @@ const formatBlockingCauseForDialog = (
       `   Solución: ${truncateNotificationText(WORKTREE_HYGIENE_REMEDIATION, 180)}`,
     ];
   }
+  if (isGoldenFlowCause(cause)) {
+    return [
+      `${index + 1}. Causa bloqueante: Violación del ciclo TDD`,
+      `   Registro TDD: ${truncateNotificationText(formatLocation(cause), 120)}`,
+      `   Falta: ${truncateNotificationText(formatGoldenFlowMissing(cause.message), 120)}`,
+    ];
+  }
 
+  const causeLabel = isSkillCause(cause) ? 'Regla' : 'Causa bloqueante';
   return [
-    `${index + 1}. Regla: ${truncateNotificationText(rule, 96)}`,
+    `${index + 1}. ${causeLabel}: ${truncateNotificationText(visibleRule, 96)}`,
     `   Fichero: ${truncateNotificationText(formatLocation(cause), 120)}`,
     `   Viola: ${truncateNotificationText(problem, 160)}`,
+    buildEvidenceLine(cause),
     `   Solución: ${truncateNotificationText(remediation, 180)}`,
-  ];
+  ].filter((line): line is string => typeof line === 'string');
 };
 
 const hasOnlyWorktreeHygieneCauses = (
@@ -104,6 +257,18 @@ const hasOnlyWorktreeHygieneCauses = (
 ): boolean =>
   Boolean(causes?.length) && causes!.every(isWorktreeHygieneCause);
 
+const hasOnlyGoldenFlowCauses = (
+  causes: Extract<PumukiCriticalNotificationEvent, { kind: 'gate.blocked' }>['blockingCauses']
+): boolean =>
+  Boolean(causes?.length) && causes!.every(isGoldenFlowCause);
+
+const resolveGoldenFlowDialogRemediation = (
+  causes: Extract<PumukiCriticalNotificationEvent, { kind: 'gate.blocked' }>['blockingCauses']
+): string => {
+  const first = causes?.find(isGoldenFlowCause);
+  return first ? formatGoldenFlowRemediation(first.message) : GOLDEN_FLOW_REMEDIATION;
+};
+
 export const buildBlockedDialogPayload = (params: {
   event: Extract<PumukiCriticalNotificationEvent, { kind: 'gate.blocked' }>;
   repoRoot: string;
@@ -114,6 +279,8 @@ export const buildBlockedDialogPayload = (params: {
     ?? resolveBlockedCauseSummary(params.event, causeCode);
   const remediation = hasOnlyWorktreeHygieneCauses(params.event.blockingCauses)
     ? WORKTREE_HYGIENE_REMEDIATION
+    : hasOnlyGoldenFlowCauses(params.event.blockingCauses)
+    ? resolveGoldenFlowDialogRemediation(params.event.blockingCauses)
     : params.event.blockingCauses && params.event.blockingCauses.length > 0
     ? 'Corrige las violaciones listadas y vuelve a intentar el commit.'
     : resolveBlockedRemediation(params.event, causeCode);

package/scripts/framework-menu-system-notifications-payloads-blocked.ts

@@ -4,7 +4,10 @@ import type {
 } from './framework-menu-system-notifications-types';
 import { resolveBlockedCauseSummary } from './framework-menu-system-notifications-cause';
 import { resolveBlockedRemediation } from './framework-menu-system-notifications-remediation';
-import { truncateNotificationText } from './framework-menu-system-notifications-text';
+import {
+  normalizeNotificationText,
+  truncateNotificationText,
+} from './framework-menu-system-notifications-text';
 
 export {
   resolveBlockedCauseSummary,
@@ -23,6 +26,40 @@ const isSkillCause = (cause: BlockedCause): boolean => {
   return ruleId.startsWith('skills.') || code.startsWith('SKILLS_');
 };
 
+const isGoldenFlowCause = (cause: BlockedCause): boolean => {
+  const ruleId = cause.ruleId ?? '';
+  const code = cause.code ?? '';
+  return (
+    code.startsWith('GOLDEN_FLOW_') ||
+    code.startsWith('TDD_') ||
+    ruleId.includes('golden_flow') ||
+    ruleId.startsWith('generic_tdd_') ||
+    ruleId.startsWith('generic_red_green_refactor')
+  );
+};
+
+const normalizeGoldenFlowMissingToken = (message: string): string => {
+  const match = message.match(/missing=\[([^\]]+)\]/i);
+  return (match?.[1] ?? '').toUpperCase();
+};
+
+const formatGoldenFlowBannerRemediation = (cause: BlockedCause): string => {
+  const missing = normalizeGoldenFlowMissingToken(cause.message);
+  if (missing.includes('RED')) {
+    return 'Implementa la fase RED antes de continuar. Las fases del ciclo TDD (RED, GREEN, REFACTOR) deben completarse para desbloquear.';
+  }
+  if (missing.includes('GREEN')) {
+    return 'Implementa la fase GREEN antes de continuar. Haz el cambio mínimo para que el test pase y continúa el ciclo TDD.';
+  }
+  if (missing.includes('REFACTOR')) {
+    return 'Implementa la fase REFACTOR antes de continuar. Limpia la solución manteniendo los tests en verde.';
+  }
+  if (missing.includes('VERIFY')) {
+    return 'Ejecuta los tests de la implementación. Si están en verde, haz un commit atómico de los cambios.';
+  }
+  return 'Completa el ciclo TDD en orden: RED, GREEN, REFACTOR y tests finales en verde antes del commit.';
+};
+
 const formatCauseLocation = (cause: BlockedCause): string => {
   if (!cause.file) {
     return 'sin fichero';
@@ -37,6 +74,78 @@ const formatCauseLocation = (cause: BlockedCause): string => {
 
 const formatCauseRule = (cause: BlockedCause): string => cause.ruleId ?? cause.code;
 
+const humanizeRuleId = (ruleId: string): string => {
+  const knownRules: Record<string, string> = {
+    'prefer-swift-testing': 'Swift Testing',
+    'no-xctassert': 'XCTest assertions',
+    'no-wait-for-expectations': 'waitForExpectations en XCTest',
+    'ios-test-quality': 'calidad de tests iOS',
+    'dynamic-type-font-scaling-automatico': 'Dynamic Type',
+    'dynamic-type-fuentes-escalables-y-layouts-adaptativos': 'fuentes escalables y layouts adaptativos',
+    'use-relative-layout-over-hard-coded-constants': 'layout relativo en vez de constantes fijas',
+    'magic-numbers-usar-constantes-con-nombres': 'números mágicos sin constantes con nombre',
+    'prefer-static-member-lookup-blue-vs-color-blue': 'colores semánticos en SwiftUI',
+  };
+  const normalized = ruleId
+    .replace(/^skills\./u, '')
+    .replace(/^governance\./u, '')
+    .replace(/^ai_gate\./u, '')
+    .replace(/_/gu, '-');
+  const parts = normalized.split('.').filter(Boolean);
+  const leaf = parts.at(-1) ?? normalized;
+  if (knownRules[leaf]) {
+    return knownRules[leaf];
+  }
+  return leaf
+    .replace(/-/gu, ' ')
+    .replace(/\bios\b/giu, 'iOS')
+    .replace(/\bui\b/giu, 'UI')
+    .replace(/\bapi\b/giu, 'API')
+    .replace(/\btdd\b/giu, 'TDD')
+    .replace(/\bsdd\b/giu, 'SDD')
+    .replace(/\bguard\b/giu, 'guard')
+    .trim();
+};
+
+const formatVisibleRule = (cause: BlockedCause): string => {
+  const ruleId = formatCauseRule(cause);
+  const readable = humanizeRuleId(ruleId);
+  return readable.length > 0 ? readable : ruleId;
+};
+
+const extractMessageField = (message: string, field: string): string | null => {
+  const escapedField = field.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = message.match(new RegExp(`\\b${escapedField}=([^\\n]+?)(?=\\s(?:severity|code|rule|file|lines?|message|remediation|snippet|node|primary_node|missing)=|$)`, 'i'));
+  const value = match?.[1]?.trim();
+  return value && value.length > 0 ? normalizeNotificationText(value) : null;
+};
+
+const stripTechnicalFieldsFromMessage = (message: string): string =>
+  normalizeNotificationText(message)
+    .replace(/\bseverity=[A-Z]+\b/gi, '')
+    .replace(/\bcode=[A-Z0-9_]+\b/gi, '')
+    .replace(/\brule=[^\s]+/gi, '')
+    .replace(/\bfile=[^\s]+/gi, '')
+    .replace(/\blines?=[0-9][0-9,\-\s]*/gi, '')
+    .replace(/\bmessage=/gi, '')
+    .replace(/\bremediation=/gi, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+const formatCauseProblem = (cause: BlockedCause): string => {
+  const messageField = extractMessageField(cause.message, 'message');
+  if (messageField) {
+    return messageField;
+  }
+  return stripTechnicalFieldsFromMessage(cause.message) || cause.code;
+};
+
+const formatCauseFix = (cause: BlockedCause): string =>
+  normalizeNotificationText(
+    cause.remediation ??
+    'Corrige la violación indicada con regla, fichero y línea, y vuelve a ejecutar el gate.'
+  );
+
 export const resolvePrioritizedBlockingCauses = (
   causes: Extract<PumukiCriticalNotificationEvent, { kind: 'gate.blocked' }>['blockingCauses']
 ): ReadonlyArray<BlockedCause> => {
@@ -49,6 +158,11 @@ export const resolvePrioritizedBlockingCauses = (
     if (leftSkill !== rightSkill) {
       return leftSkill ? -1 : 1;
     }
+    const leftGoldenFlow = isGoldenFlowCause(left);
+    const rightGoldenFlow = isGoldenFlowCause(right);
+    if (leftGoldenFlow !== rightGoldenFlow) {
+      return leftGoldenFlow ? -1 : 1;
+    }
     return 0;
   });
 };
@@ -66,6 +180,12 @@ const buildBlockingCausesSummary = (
   }
   const prefix = isSkillCause(first) ? 'Skill violada' : 'Causa bloqueante';
   const overflow = prioritized.length > 1 ? ` (+${prioritized.length - 1} más)` : '';
+  if (isSkillCause(first)) {
+    return `${prefix}: ${formatCauseLocation(first)} · ${formatVisibleRule(first)}${overflow}`;
+  }
+  if (isGoldenFlowCause(first)) {
+    return `Violación del ciclo TDD${overflow}`;
+  }
   return `${prefix}: ${formatCauseRule(first)} · ${formatCauseLocation(first)}${overflow}`;
 };
 
@@ -80,10 +200,21 @@ const buildBlockingCausesRemediation = (
   if (!first) {
     return null;
   }
-  const remediation =
-    first.remediation ??
-    'Corrige la violación indicada con regla, fichero y línea, y vuelve a ejecutar el gate.';
-  return `${remediation} Revisa el reporte completo para el resto de causas bloqueantes.`;
+  if (isSkillCause(first)) {
+    return [
+      `Regla: ${formatVisibleRule(first)}.`,
+      `Fichero: ${formatCauseLocation(first)}.`,
+      `Viola: ${formatCauseProblem(first)}.`,
+      `Solución: ${formatCauseFix(first)}.`,
+      prioritized.length > 1 ? `Quedan ${prioritized.length - 1} causa(s) más en el reporte completo.` : '',
+    ]
+      .filter((line) => line.length > 0)
+      .join(' ');
+  }
+  if (isGoldenFlowCause(first)) {
+    return formatGoldenFlowBannerRemediation(first);
+  }
+  return `${formatCauseFix(first)} Revisa el reporte completo para el resto de causas bloqueantes.`;
 };
 
 export const buildGateBlockedPayload = (
@@ -93,7 +224,7 @@ export const buildGateBlockedPayload = (
   const causeCode = event.causeCode ?? 'GATE_BLOCKED';
   const causeSummary = truncateNotificationText(
     buildBlockingCausesSummary(event.blockingCauses) ?? resolveBlockedCauseSummary(event, causeCode),
-    72
+    96
   );
   const remediation =
     buildBlockingCausesRemediation(event.blockingCauses) ?? resolveBlockedRemediation(event, causeCode);